diff options
| author | Leo Tenenbaum <pommicket@gmail.com> | 2018-08-20 21:12:06 -0400 |
|---|---|---|
| committer | Leo Tenenbaum <pommicket@gmail.com> | 2018-08-20 21:12:06 -0400 |
| commit | 63e87c2d0c9d263f14c77b68f85c67d46ece82a9 (patch) | |
| tree | 6260365cbf7d24f37d27669e8538227fcb72e243 /gtk+-mingw/share/info | |
| parent | a4460f6d9453bbd7e584937686449cef3e19f052 (diff) | |
Diffstat (limited to 'gtk+-mingw/share/info')
| -rw-r--r-- | gtk+-mingw/share/info/autosprintf.info | 134 | ||||
| -rw-r--r-- | gtk+-mingw/share/info/dir | 23 | ||||
| -rw-r--r-- | gtk+-mingw/share/info/gettext.info | 18374 | ||||
| -rw-r--r-- | gtk+-mingw/share/info/libffi.info | 617 | ||||
| -rw-r--r-- | gtk+-mingw/share/info/libtool.info | 140 | ||||
| -rw-r--r-- | gtk+-mingw/share/info/libtool.info-1 | 6698 | ||||
| -rw-r--r-- | gtk+-mingw/share/info/libtool.info-2 | 1227 |
7 files changed, 0 insertions, 27213 deletions
diff --git a/gtk+-mingw/share/info/autosprintf.info b/gtk+-mingw/share/info/autosprintf.info deleted file mode 100644 index 37af0bd..0000000 --- a/gtk+-mingw/share/info/autosprintf.info +++ /dev/null @@ -1,134 +0,0 @@ -This is autosprintf.info, produced by makeinfo version 4.13 from -autosprintf.texi. - -INFO-DIR-SECTION C++ libraries -START-INFO-DIR-ENTRY -* autosprintf: (autosprintf). Support for printf format strings in C++. -END-INFO-DIR-ENTRY - - This file provides documentation for GNU `autosprintf' library. - - Copyright (C) 2002-2003, 2006-2007 Free Software Foundation, Inc. - - This manual is free documentation. It is dually licensed under the -GNU FDL and the GNU GPL. This means that you can redistribute this -manual under either of these two licenses, at your choice. - - This manual is covered by the GNU FDL. Permission is granted to -copy, distribute and/or modify this document under the terms of the GNU -Free Documentation License (FDL), either version 1.2 of the License, or -(at your option) any later version published by the Free Software -Foundation (FSF); with no Invariant Sections, with no Front-Cover Text, -and with no Back-Cover Texts. A copy of the license is at -`http://www.gnu.org/licenses/fdl.html'. - - This manual is covered by the GNU GPL. You can redistribute it -and/or modify it under the terms of the GNU General Public License -(GPL), either version 2 of the License, or (at your option) any later -version published by the Free Software Foundation (FSF). A copy of the -license is at `http://www.gnu.org/licenses/gpl.html'. - - -File: autosprintf.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) - -GNU autosprintf -*************** - -This manual documents the GNU autosprintf class, version 1.0. - -* Menu: - -* Introduction:: Introduction -* Class autosprintf:: The `autosprintf' class -* Using autosprintf:: Using `autosprintf' in own programs - - -File: autosprintf.info, Node: Introduction, Next: Class autosprintf, Prev: Top, Up: Top - -1 Introduction -************** - -This package makes the C formatted output routines (`fprintf' et al.) -usable in C++ programs, for use with the `<string>' strings and the -`<iostream>' streams. - - It allows to write code like - - cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring); - -instead of - - cerr << "syntax error in " << filename << ":" << line << ": " << errstring; - - The benefits of the autosprintf syntax are: - - * It reuses the standard POSIX printf facility. Easy migration from - C to C++. - - * English sentences are kept together. - - * It makes internationalization possible. Internationalization - requires format strings, because in some cases the translator - needs to change the order of a sentence, and more generally it is - easier for the translator to work with a single string for a - sentence than with multiple string pieces. - - * It reduces the risk of programming errors due to forgotten state - in the output stream (e.g. `cout << hex;' not followed by `cout << - dec;'). - - -File: autosprintf.info, Node: Class autosprintf, Next: Using autosprintf, Prev: Introduction, Up: Top - -2 The `autosprintf' class -************************* - -An instance of class `autosprintf' just contains a string with the -formatted output result. Such an instance is usually allocated as an -automatic storage variable, i.e. on the stack, not with `new' on the -heap. - - The constructor `autosprintf (const char *format, ...)' takes a -format string and additional arguments, like the C function `printf'. - - Conversions to `char *' and `std::string' are defined that return -the encapsulated string. The conversion to `char *' returns a freshly -allocated copy of the encapsulated string; it needs to be freed using -`delete[]'. The conversion to `std::string' returns a copy of the -encapsulated string, with automatic memory management. - - The destructor `~autosprintf ()' destroys the encapsulated string. - - An `operator <<' is provided that outputs the encapsulated string to -the given `ostream'. - - -File: autosprintf.info, Node: Using autosprintf, Prev: Class autosprintf, Up: Top - -3 Using `autosprintf' in own programs -************************************* - -To use the `autosprintf' class in your programs, you need to add - - #include "autosprintf.h" - using gnu::autosprintf; - -to your source code. The include file defines the class `autosprintf', -in a namespace called `gnu'. The `using' statement makes it possible to -use the class without the (otherwise natural) `gnu::' prefix. - - When linking your program, you need to link with `libasprintf', -because that's where the class is defined. In projects using GNU -`autoconf', this means adding `AC_LIB_LINKFLAGS([asprintf])' to -`configure.in' or `configure.ac', and using the @LIBASPRINTF@ Makefile -variable that it provides. - - - -Tag Table: -Node: Top1348 -Node: Introduction1708 -Node: Class autosprintf2859 -Node: Using autosprintf3869 - -End Tag Table diff --git a/gtk+-mingw/share/info/dir b/gtk+-mingw/share/info/dir deleted file mode 100644 index e240bf0..0000000 --- a/gtk+-mingw/share/info/dir +++ /dev/null @@ -1,23 +0,0 @@ -This is the file .../info/dir, which contains the -topmost node of the Info hierarchy, called (dir)Top. -The first time you invoke Info you start off looking at this node. - -File: dir, Node: Top This is the top of the INFO tree - - This (the Directory node) gives a menu of major topics. - Typing "q" exits, "?" lists all Info commands, "d" returns here, - "h" gives a primer for first-timers, - "mEmacs<Return>" visits the Emacs manual, etc. - - In Emacs, you can click mouse button 2 on a menu item or cross reference - to select it. - -* Menu: - -GNU programming tools -* Libtool: (libtool). Generic shared library support script. - -Individual utilities -* libtool-invocation: (libtool)Invoking libtool. - Running the `libtool' script. -* libtoolize: (libtool)Invoking libtoolize. Adding libtool support. diff --git a/gtk+-mingw/share/info/gettext.info b/gtk+-mingw/share/info/gettext.info deleted file mode 100644 index abd1869..0000000 --- a/gtk+-mingw/share/info/gettext.info +++ /dev/null @@ -1,18374 +0,0 @@ -This is gettext.info, produced by makeinfo version 4.13 from -gettext.texi. - -INFO-DIR-SECTION GNU Gettext Utilities -START-INFO-DIR-ENTRY -* gettext: (gettext). GNU gettext utilities. -* autopoint: (gettext)autopoint Invocation. Copy gettext infrastructure. -* envsubst: (gettext)envsubst Invocation. Expand environment variables. -* gettextize: (gettext)gettextize Invocation. Prepare a package for gettext. -* msgattrib: (gettext)msgattrib Invocation. Select part of a PO file. -* msgcat: (gettext)msgcat Invocation. Combine several PO files. -* msgcmp: (gettext)msgcmp Invocation. Compare a PO file and template. -* msgcomm: (gettext)msgcomm Invocation. Match two PO files. -* msgconv: (gettext)msgconv Invocation. Convert PO file to encoding. -* msgen: (gettext)msgen Invocation. Create an English PO file. -* msgexec: (gettext)msgexec Invocation. Process a PO file. -* msgfilter: (gettext)msgfilter Invocation. Pipe a PO file through a filter. -* msgfmt: (gettext)msgfmt Invocation. Make MO files out of PO files. -* msggrep: (gettext)msggrep Invocation. Select part of a PO file. -* msginit: (gettext)msginit Invocation. Create a fresh PO file. -* msgmerge: (gettext)msgmerge Invocation. Update a PO file from template. -* msgunfmt: (gettext)msgunfmt Invocation. Uncompile MO file into PO file. -* msguniq: (gettext)msguniq Invocation. Unify duplicates for PO file. -* ngettext: (gettext)ngettext Invocation. Translate a message with plural. -* xgettext: (gettext)xgettext Invocation. Extract strings into a PO file. -* ISO639: (gettext)Language Codes. ISO 639 language codes. -* ISO3166: (gettext)Country Codes. ISO 3166 country codes. -END-INFO-DIR-ENTRY - - This file provides documentation for GNU `gettext' utilities. It -also serves as a reference for the free Translation Project. - - Copyright (C) 1995-1998, 2001-2007 Free Software Foundation, Inc. - - This manual is free documentation. It is dually licensed under the -GNU FDL and the GNU GPL. This means that you can redistribute this -manual under either of these two licenses, at your choice. - - This manual is covered by the GNU FDL. Permission is granted to -copy, distribute and/or modify this document under the terms of the GNU -Free Documentation License (FDL), either version 1.2 of the License, or -(at your option) any later version published by the Free Software -Foundation (FSF); with no Invariant Sections, with no Front-Cover Text, -and with no Back-Cover Texts. A copy of the license is included in -*note GNU FDL::. - - This manual is covered by the GNU GPL. You can redistribute it -and/or modify it under the terms of the GNU General Public License -(GPL), either version 2 of the License, or (at your option) any later -version published by the Free Software Foundation (FSF). A copy of the -license is included in *note GNU GPL::. - - -File: gettext.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) - -GNU `gettext' utilities -*********************** - - This manual documents the GNU gettext tools and the GNU libintl -library, version 0.18.1. - -* Menu: - -* Introduction:: Introduction -* Users:: The User's View -* PO Files:: The Format of PO Files -* Sources:: Preparing Program Sources -* Template:: Making the PO Template File -* Creating:: Creating a New PO File -* Updating:: Updating Existing PO Files -* Editing:: Editing PO Files -* Manipulating:: Manipulating PO Files -* Binaries:: Producing Binary MO Files -* Programmers:: The Programmer's View -* Translators:: The Translator's View -* Maintainers:: The Maintainer's View -* Installers:: The Installer's and Distributor's View -* Programming Languages:: Other Programming Languages -* Conclusion:: Concluding Remarks - -* Language Codes:: ISO 639 language codes -* Country Codes:: ISO 3166 country codes -* Licenses:: Licenses - -* Program Index:: Index of Programs -* Option Index:: Index of Command-Line Options -* Variable Index:: Index of Environment Variables -* PO Mode Index:: Index of Emacs PO Mode Commands -* Autoconf Macro Index:: Index of Autoconf Macros -* Index:: General Index - - --- The Detailed Node Listing --- - -Introduction - -* Why:: The Purpose of GNU `gettext' -* Concepts:: I18n, L10n, and Such -* Aspects:: Aspects in Native Language Support -* Files:: Files Conveying Translations -* Overview:: Overview of GNU `gettext' - -The User's View - -* System Installation:: Questions During Operating System Installation -* Setting the GUI Locale:: How to Specify the Locale Used by GUI Programs -* Setting the POSIX Locale:: How to Specify the Locale According to POSIX -* Installing Localizations:: How to Install Additional Translations - -Setting the POSIX Locale - -* Locale Names:: How a Locale Specification Looks Like -* Locale Environment Variables:: Which Environment Variable Specfies What -* The LANGUAGE variable:: How to Specify a Priority List of Languages - -Preparing Program Sources - -* Importing:: Importing the `gettext' declaration -* Triggering:: Triggering `gettext' Operations -* Preparing Strings:: Preparing Translatable Strings -* Mark Keywords:: How Marks Appear in Sources -* Marking:: Marking Translatable Strings -* c-format Flag:: Telling something about the following string -* Special cases:: Special Cases of Translatable Strings -* Bug Report Address:: Letting Users Report Translation Bugs -* Names:: Marking Proper Names for Translation -* Libraries:: Preparing Library Sources - -Making the PO Template File - -* xgettext Invocation:: Invoking the `xgettext' Program - -Creating a New PO File - -* msginit Invocation:: Invoking the `msginit' Program -* Header Entry:: Filling in the Header Entry - -Updating Existing PO Files - -* msgmerge Invocation:: Invoking the `msgmerge' Program - -Editing PO Files - -* KBabel:: KDE's PO File Editor -* Gtranslator:: GNOME's PO File Editor -* PO Mode:: Emacs's PO File Editor -* Compendium:: Using Translation Compendia - -Emacs's PO File Editor - -* Installation:: Completing GNU `gettext' Installation -* Main PO Commands:: Main Commands -* Entry Positioning:: Entry Positioning -* Normalizing:: Normalizing Strings in Entries -* Translated Entries:: Translated Entries -* Fuzzy Entries:: Fuzzy Entries -* Untranslated Entries:: Untranslated Entries -* Obsolete Entries:: Obsolete Entries -* Modifying Translations:: Modifying Translations -* Modifying Comments:: Modifying Comments -* Subedit:: Mode for Editing Translations -* C Sources Context:: C Sources Context -* Auxiliary:: Consulting Auxiliary PO Files - -Using Translation Compendia - -* Creating Compendia:: Merging translations for later use -* Using Compendia:: Using older translations if they fit - -Manipulating PO Files - -* msgcat Invocation:: Invoking the `msgcat' Program -* msgconv Invocation:: Invoking the `msgconv' Program -* msggrep Invocation:: Invoking the `msggrep' Program -* msgfilter Invocation:: Invoking the `msgfilter' Program -* msguniq Invocation:: Invoking the `msguniq' Program -* msgcomm Invocation:: Invoking the `msgcomm' Program -* msgcmp Invocation:: Invoking the `msgcmp' Program -* msgattrib Invocation:: Invoking the `msgattrib' Program -* msgen Invocation:: Invoking the `msgen' Program -* msgexec Invocation:: Invoking the `msgexec' Program -* Colorizing:: Highlighting parts of PO files -* libgettextpo:: Writing your own programs that process PO files - -Highlighting parts of PO files - -* The --color option:: Triggering colorized output -* The TERM variable:: The environment variable `TERM' -* The --style option:: The `--style' option -* Style rules:: Style rules for PO files -* Customizing less:: Customizing `less' for viewing PO files - -Producing Binary MO Files - -* msgfmt Invocation:: Invoking the `msgfmt' Program -* msgunfmt Invocation:: Invoking the `msgunfmt' Program -* MO Files:: The Format of GNU MO Files - -The Programmer's View - -* catgets:: About `catgets' -* gettext:: About `gettext' -* Comparison:: Comparing the two interfaces -* Using libintl.a:: Using libintl.a in own programs -* gettext grok:: Being a `gettext' grok -* Temp Programmers:: Temporary Notes for the Programmers Chapter - -About `catgets' - -* Interface to catgets:: The interface -* Problems with catgets:: Problems with the `catgets' interface?! - -About `gettext' - -* Interface to gettext:: The interface -* Ambiguities:: Solving ambiguities -* Locating Catalogs:: Locating message catalog files -* Charset conversion:: How to request conversion to Unicode -* Contexts:: Solving ambiguities in GUI programs -* Plural forms:: Additional functions for handling plurals -* Optimized gettext:: Optimization of the *gettext functions - -Temporary Notes for the Programmers Chapter - -* Temp Implementations:: Temporary - Two Possible Implementations -* Temp catgets:: Temporary - About `catgets' -* Temp WSI:: Temporary - Why a single implementation -* Temp Notes:: Temporary - Notes - -The Translator's View - -* Trans Intro 0:: Introduction 0 -* Trans Intro 1:: Introduction 1 -* Discussions:: Discussions -* Organization:: Organization -* Information Flow:: Information Flow -* Translating plural forms:: How to fill in `msgstr[0]', `msgstr[1]' -* Prioritizing messages:: How to find which messages to translate first - -Organization - -* Central Coordination:: Central Coordination -* National Teams:: National Teams -* Mailing Lists:: Mailing Lists - -National Teams - -* Sub-Cultures:: Sub-Cultures -* Organizational Ideas:: Organizational Ideas - -The Maintainer's View - -* Flat and Non-Flat:: Flat or Non-Flat Directory Structures -* Prerequisites:: Prerequisite Works -* gettextize Invocation:: Invoking the `gettextize' Program -* Adjusting Files:: Files You Must Create or Alter -* autoconf macros:: Autoconf macros for use in `configure.ac' -* CVS Issues:: Integrating with CVS -* Release Management:: Creating a Distribution Tarball - -Files You Must Create or Alter - -* po/POTFILES.in:: `POTFILES.in' in `po/' -* po/LINGUAS:: `LINGUAS' in `po/' -* po/Makevars:: `Makevars' in `po/' -* po/Rules-*:: Extending `Makefile' in `po/' -* configure.ac:: `configure.ac' at top level -* config.guess:: `config.guess', `config.sub' at top level -* mkinstalldirs:: `mkinstalldirs' at top level -* aclocal:: `aclocal.m4' at top level -* acconfig:: `acconfig.h' at top level -* config.h.in:: `config.h.in' at top level -* Makefile:: `Makefile.in' at top level -* src/Makefile:: `Makefile.in' in `src/' -* lib/gettext.h:: `gettext.h' in `lib/' - -Autoconf macros for use in `configure.ac' - -* AM_GNU_GETTEXT:: AM_GNU_GETTEXT in `gettext.m4' -* AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in `gettext.m4' -* AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in `gettext.m4' -* AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4' -* AM_PO_SUBDIRS:: AM_PO_SUBDIRS in `po.m4' -* AM_ICONV:: AM_ICONV in `iconv.m4' - -Integrating with CVS - -* Distributed CVS:: Avoiding version mismatch in distributed development -* Files under CVS:: Files to put under CVS version control -* autopoint Invocation:: Invoking the `autopoint' Program - -Other Programming Languages - -* Language Implementors:: The Language Implementor's View -* Programmers for other Languages:: The Programmer's View -* Translators for other Languages:: The Translator's View -* Maintainers for other Languages:: The Maintainer's View -* List of Programming Languages:: Individual Programming Languages -* List of Data Formats:: Internationalizable Data - -The Translator's View - -* c-format:: C Format Strings -* objc-format:: Objective C Format Strings -* sh-format:: Shell Format Strings -* python-format:: Python Format Strings -* lisp-format:: Lisp Format Strings -* elisp-format:: Emacs Lisp Format Strings -* librep-format:: librep Format Strings -* scheme-format:: Scheme Format Strings -* smalltalk-format:: Smalltalk Format Strings -* java-format:: Java Format Strings -* csharp-format:: C# Format Strings -* awk-format:: awk Format Strings -* object-pascal-format:: Object Pascal Format Strings -* ycp-format:: YCP Format Strings -* tcl-format:: Tcl Format Strings -* perl-format:: Perl Format Strings -* php-format:: PHP Format Strings -* gcc-internal-format:: GCC internal Format Strings -* gfc-internal-format:: GFC internal Format Strings -* qt-format:: Qt Format Strings -* qt-plural-format:: Qt Plural Format Strings -* kde-format:: KDE Format Strings -* boost-format:: Boost Format Strings - -Individual Programming Languages - -* C:: C, C++, Objective C -* sh:: sh - Shell Script -* bash:: bash - Bourne-Again Shell Script -* Python:: Python -* Common Lisp:: GNU clisp - Common Lisp -* clisp C:: GNU clisp C sources -* Emacs Lisp:: Emacs Lisp -* librep:: librep -* Scheme:: GNU guile - Scheme -* Smalltalk:: GNU Smalltalk -* Java:: Java -* C#:: C# -* gawk:: GNU awk -* Pascal:: Pascal - Free Pascal Compiler -* wxWidgets:: wxWidgets library -* YCP:: YCP - YaST2 scripting language -* Tcl:: Tcl - Tk's scripting language -* Perl:: Perl -* PHP:: PHP Hypertext Preprocessor -* Pike:: Pike -* GCC-source:: GNU Compiler Collection sources - -sh - Shell Script - -* Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization -* gettext.sh:: Contents of `gettext.sh' -* gettext Invocation:: Invoking the `gettext' program -* ngettext Invocation:: Invoking the `ngettext' program -* envsubst Invocation:: Invoking the `envsubst' program -* eval_gettext Invocation:: Invoking the `eval_gettext' function -* eval_ngettext Invocation:: Invoking the `eval_ngettext' function - -Perl - -* General Problems:: General Problems Parsing Perl Code -* Default Keywords:: Which Keywords Will xgettext Look For? -* Special Keywords:: How to Extract Hash Keys -* Quote-like Expressions:: What are Strings And Quote-like Expressions? -* Interpolation I:: Invalid String Interpolation -* Interpolation II:: Valid String Interpolation -* Parentheses:: When To Use Parentheses -* Long Lines:: How To Grok with Long Lines -* Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work - -Internationalizable Data - -* POT:: POT - Portable Object Template -* RST:: Resource String Table -* Glade:: Glade - GNOME user interface description - -Concluding Remarks - -* History:: History of GNU `gettext' -* References:: Related Readings - -Language Codes - -* Usual Language Codes:: Two-letter ISO 639 language codes -* Rare Language Codes:: Three-letter ISO 639 language codes - -Licenses - -* GNU GPL:: GNU General Public License -* GNU LGPL:: GNU Lesser General Public License -* GNU FDL:: GNU Free Documentation License - - -File: gettext.info, Node: Introduction, Next: Users, Prev: Top, Up: Top - -1 Introduction -************** - - This chapter explains the goals sought in the creation of GNU -`gettext' and the free Translation Project. Then, it explains a few -broad concepts around Native Language Support, and positions message -translation with regard to other aspects of national and cultural -variance, as they apply to programs. It also surveys those files used -to convey the translations. It explains how the various tools interact -in the initial generation of these files, and later, how the maintenance -cycle should usually operate. - - In this manual, we use _he_ when speaking of the programmer or -maintainer, _she_ when speaking of the translator, and _they_ when -speaking of the installers or end users of the translated program. -This is only a convenience for clarifying the documentation. It is -_absolutely_ not meant to imply that some roles are more appropriate to -males or females. Besides, as you might guess, GNU `gettext' is meant -to be useful for people using computers, whatever their sex, race, -religion or nationality! - - Please send suggestions and corrections to: - - Internet address: - bug-gnu-gettext@gnu.org - -Please include the manual's edition number and update date in your -messages. - -* Menu: - -* Why:: The Purpose of GNU `gettext' -* Concepts:: I18n, L10n, and Such -* Aspects:: Aspects in Native Language Support -* Files:: Files Conveying Translations -* Overview:: Overview of GNU `gettext' - - -File: gettext.info, Node: Why, Next: Concepts, Prev: Introduction, Up: Introduction - -1.1 The Purpose of GNU `gettext' -================================ - - Usually, programs are written and documented in English, and use -English at execution time to interact with users. This is true not -only of GNU software, but also of a great deal of proprietary and free -software. Using a common language is quite handy for communication -between developers, maintainers and users from all countries. On the -other hand, most people are less comfortable with English than with -their own native language, and would prefer to use their mother tongue -for day to day's work, as far as possible. Many would simply _love_ to -see their computer screen showing a lot less of English, and far more -of their own language. - - However, to many people, this dream might appear so far fetched that -they may believe it is not even worth spending time thinking about it. -They have no confidence at all that the dream might ever become true. -Yet some have not lost hope, and have organized themselves. The -Translation Project is a formalization of this hope into a workable -structure, which has a good chance to get all of us nearer the -achievement of a truly multi-lingual set of programs. - - GNU `gettext' is an important step for the Translation Project, as -it is an asset on which we may build many other steps. This package -offers to programmers, translators and even users, a well integrated -set of tools and documentation. Specifically, the GNU `gettext' -utilities are a set of tools that provides a framework within which -other free packages may produce multi-lingual messages. These tools -include - - * A set of conventions about how programs should be written to - support message catalogs. - - * A directory and file naming organization for the message catalogs - themselves. - - * A runtime library supporting the retrieval of translated messages. - - * A few stand-alone programs to massage in various ways the sets of - translatable strings, or already translated strings. - - * A library supporting the parsing and creation of files containing - translated messages. - - * A special mode for Emacs(1) which helps preparing these sets and - bringing them up to date. - - GNU `gettext' is designed to minimize the impact of -internationalization on program sources, keeping this impact as small -and hardly noticeable as possible. Internationalization has better -chances of succeeding if it is very light weighted, or at least, appear -to be so, when looking at program sources. - - The Translation Project also uses the GNU `gettext' distribution as -a vehicle for documenting its structure and methods. This goes beyond -the strict technicalities of documenting the GNU `gettext' proper. By -so doing, translators will find in a single place, as far as possible, -all they need to know for properly doing their translating work. Also, -this supplemental documentation might also help programmers, and even -curious users, in understanding how GNU `gettext' is related to the -remainder of the Translation Project, and consequently, have a glimpse -at the _big picture_. - - ---------- Footnotes ---------- - - (1) In this manual, all mentions of Emacs refers to either GNU Emacs -or to XEmacs, which people sometimes call FSF Emacs and Lucid Emacs, -respectively. - - -File: gettext.info, Node: Concepts, Next: Aspects, Prev: Why, Up: Introduction - -1.2 I18n, L10n, and Such -======================== - - Two long words appear all the time when we discuss support of native -language in programs, and these words have a precise meaning, worth -being explained here, once and for all in this document. The words are -_internationalization_ and _localization_. Many people, tired of -writing these long words over and over again, took the habit of writing -"i18n" and "l10n" instead, quoting the first and last letter of each -word, and replacing the run of intermediate letters by a number merely -telling how many such letters there are. But in this manual, in the -sake of clarity, we will patiently write the names in full, each time... - - By "internationalization", one refers to the operation by which a -program, or a set of programs turned into a package, is made aware of -and able to support multiple languages. This is a generalization -process, by which the programs are untied from calling only English -strings or other English specific habits, and connected to generic ways -of doing the same, instead. Program developers may use various -techniques to internationalize their programs. Some of these have been -standardized. GNU `gettext' offers one of these standards. *Note -Programmers::. - - By "localization", one means the operation by which, in a set of -programs already internationalized, one gives the program all needed -information so that it can adapt itself to handle its input and output -in a fashion which is correct for some native language and cultural -habits. This is a particularisation process, by which generic methods -already implemented in an internationalized program are used in -specific ways. The programming environment puts several functions to -the programmers disposal which allow this runtime configuration. The -formal description of specific set of cultural habits for some country, -together with all associated translations targeted to the same native -language, is called the "locale" for this language or country. Users -achieve localization of programs by setting proper values to special -environment variables, prior to executing those programs, identifying -which locale should be used. - - In fact, locale message support is only one component of the cultural -data that makes up a particular locale. There are a whole host of -routines and functions provided to aid programmers in developing -internationalized software and which allow them to access the data -stored in a particular locale. When someone presently refers to a -particular locale, they are obviously referring to the data stored -within that particular locale. Similarly, if a programmer is referring -to "accessing the locale routines", they are referring to the complete -suite of routines that access all of the locale's information. - - One uses the expression "Native Language Support", or merely NLS, -for speaking of the overall activity or feature encompassing both -internationalization and localization, allowing for multi-lingual -interactions in a program. In a nutshell, one could say that -internationalization is the operation by which further localizations -are made possible. - - Also, very roughly said, when it comes to multi-lingual messages, -internationalization is usually taken care of by programmers, and -localization is usually taken care of by translators. - - -File: gettext.info, Node: Aspects, Next: Files, Prev: Concepts, Up: Introduction - -1.3 Aspects in Native Language Support -====================================== - - For a totally multi-lingual distribution, there are many things to -translate beyond output messages. - - * As of today, GNU `gettext' offers a complete toolset for - translating messages output by C programs. Perl scripts and shell - scripts will also need to be translated. Even if there are today - some hooks by which this can be done, these hooks are not - integrated as well as they should be. - - * Some programs, like `autoconf' or `bison', are able to produce - other programs (or scripts). Even if the generating programs - themselves are internationalized, the generated programs they - produce may need internationalization on their own, and this - indirect internationalization could be automated right from the - generating program. In fact, quite usually, generating and - generated programs could be internationalized independently, as - the effort needed is fairly orthogonal. - - * A few programs include textual tables which might need translation - themselves, independently of the strings contained in the program - itself. For example, RFC 1345 gives an English description for - each character which the `recode' program is able to reconstruct - at execution. Since these descriptions are extracted from the RFC - by mechanical means, translating them properly would require a - prior translation of the RFC itself. - - * Almost all programs accept options, which are often worded out so - to be descriptive for the English readers; one might want to - consider offering translated versions for program options as well. - - * Many programs read, interpret, compile, or are somewhat driven by - input files which are texts containing keywords, identifiers, or - replies which are inherently translatable. For example, one may - want `gcc' to allow diacriticized characters in identifiers or use - translated keywords; `rm -i' might accept something else than `y' - or `n' for replies, etc. Even if the program will eventually make - most of its output in the foreign languages, one has to decide - whether the input syntax, option values, etc., are to be localized - or not. - - * The manual accompanying a package, as well as all documentation - files in the distribution, could surely be translated, too. - Translating a manual, with the intent of later keeping up with - updates, is a major undertaking in itself, generally. - - - As we already stressed, translation is only one aspect of locales. -Other internationalization aspects are system services and are handled -in GNU `libc'. There are many attributes that are needed to define a -country's cultural conventions. These attributes include beside the -country's native language, the formatting of the date and time, the -representation of numbers, the symbols for currency, etc. These local -"rules" are termed the country's locale. The locale represents the -knowledge needed to support the country's native attributes. - - There are a few major areas which may vary between countries and -hence, define what a locale must describe. The following list helps -putting multi-lingual messages into the proper context of other tasks -related to locales. See the GNU `libc' manual for details. - -_Characters and Codesets_ - The codeset most commonly used through out the USA and most English - speaking parts of the world is the ASCII codeset. However, there - are many characters needed by various locales that are not found - within this codeset. The 8-bit ISO 8859-1 code set has most of - the special characters needed to handle the major European - languages. However, in many cases, choosing ISO 8859-1 is - nevertheless not adequate: it doesn't even handle the major - European currency. Hence each locale will need to specify which - codeset they need to use and will need to have the appropriate - character handling routines to cope with the codeset. - -_Currency_ - The symbols used vary from country to country as does the position - used by the symbol. Software needs to be able to transparently - display currency figures in the native mode for each locale. - -_Dates_ - The format of date varies between locales. For example, Christmas - day in 1994 is written as 12/25/94 in the USA and as 25/12/94 in - Australia. Other countries might use ISO 8601 dates, etc. - - Time of the day may be noted as HH:MM, HH.MM, or otherwise. Some - locales require time to be specified in 24-hour mode rather than - as AM or PM. Further, the nature and yearly extent of the - Daylight Saving correction vary widely between countries. - -_Numbers_ - Numbers can be represented differently in different locales. For - example, the following numbers are all written correctly for their - respective locales: - - 12,345.67 English - 12.345,67 German - 12345,67 French - 1,2345.67 Asia - - Some programs could go further and use different unit systems, like - English units or Metric units, or even take into account variants - about how numbers are spelled in full. - -_Messages_ - The most obvious area is the language support within a locale. - This is where GNU `gettext' provides the means for developers and - users to easily change the language that the software uses to - communicate to the user. - - - These areas of cultural conventions are called _locale categories_. -It is an unfortunate term; _locale aspects_ or _locale feature -categories_ would be a better term, because each "locale category" -describes an area or task that requires localization. The concrete data -that describes the cultural conventions for such an area and for a -particular culture is also called a _locale category_. In this sense, -a locale is composed of several locale categories: the locale category -describing the codeset, the locale category describing the formatting -of numbers, the locale category containing the translated messages, and -so on. - - Components of locale outside of message handling are standardized in -the ISO C standard and the POSIX:2001 standard (also known as the SUSV3 -specification). GNU `libc' fully implements this, and most other -modern systems provide a more or less reasonable support for at least -some of the missing components. - - -File: gettext.info, Node: Files, Next: Overview, Prev: Aspects, Up: Introduction - -1.4 Files Conveying Translations -================================ - - The letters PO in `.po' files means Portable Object, to distinguish -it from `.mo' files, where MO stands for Machine Object. This -paradigm, as well as the PO file format, is inspired by the NLS -standard developed by Uniforum, and first implemented by Sun in their -Solaris system. - - PO files are meant to be read and edited by humans, and associate -each original, translatable string of a given package with its -translation in a particular target language. A single PO file is -dedicated to a single target language. If a package supports many -languages, there is one such PO file per language supported, and each -package has its own set of PO files. These PO files are best created by -the `xgettext' program, and later updated or refreshed through the -`msgmerge' program. Program `xgettext' extracts all marked messages -from a set of C files and initializes a PO file with empty -translations. Program `msgmerge' takes care of adjusting PO files -between releases of the corresponding sources, commenting obsolete -entries, initializing new ones, and updating all source line -references. Files ending with `.pot' are kind of base translation -files found in distributions, in PO file format. - - MO files are meant to be read by programs, and are binary in nature. -A few systems already offer tools for creating and handling MO files as -part of the Native Language Support coming with the system, but the -format of these MO files is often different from system to system, and -non-portable. The tools already provided with these systems don't -support all the features of GNU `gettext'. Therefore GNU `gettext' -uses its own format for MO files. Files ending with `.gmo' are really -MO files, when it is known that these files use the GNU format. - - -File: gettext.info, Node: Overview, Prev: Files, Up: Introduction - -1.5 Overview of GNU `gettext' -============================= - - The following diagram summarizes the relation between the files -handled by GNU `gettext' and the tools acting on these files. It is -followed by somewhat detailed explanations, which you should read while -keeping an eye on the diagram. Having a clear understanding of these -interrelations will surely help programmers, translators and -maintainers. - - Original C Sources ---> Preparation ---> Marked C Sources ---. - | - .---------<--- GNU gettext Library | - .--- make <---+ | - | `---------<--------------------+---------------' - | | - | .-----<--- PACKAGE.pot <--- xgettext <---' .---<--- PO Compendium - | | | ^ - | | `---. | - | `---. +---> PO editor ---. - | +----> msgmerge ------> LANG.po ---->--------' | - | .---' | - | | | - | `-------------<---------------. | - | +--- New LANG.po <--------------------' - | .--- LANG.gmo <--- msgfmt <---' - | | - | `---> install ---> /.../LANG/PACKAGE.mo ---. - | +---> "Hello world!" - `-------> install ---> /.../bin/PROGRAM -------' - - As a programmer, the first step to bringing GNU `gettext' into your -package is identifying, right in the C sources, those strings which are -meant to be translatable, and those which are untranslatable. This -tedious job can be done a little more comfortably using emacs PO mode, -but you can use any means familiar to you for modifying your C sources. -Beside this some other simple, standard changes are needed to properly -initialize the translation library. *Note Sources::, for more -information about all this. - - For newly written software the strings of course can and should be -marked while writing it. The `gettext' approach makes this very easy. -Simply put the following lines at the beginning of each file or in a -central header file: - - #define _(String) (String) - #define N_(String) String - #define textdomain(Domain) - #define bindtextdomain(Package, Directory) - -Doing this allows you to prepare the sources for internationalization. -Later when you feel ready for the step to use the `gettext' library -simply replace these definitions by the following: - - #include <libintl.h> - #define _(String) gettext (String) - #define gettext_noop(String) String - #define N_(String) gettext_noop (String) - -and link against `libintl.a' or `libintl.so'. Note that on GNU -systems, you don't need to link with `libintl' because the `gettext' -library functions are already contained in GNU libc. That is all you -have to change. - - Once the C sources have been modified, the `xgettext' program is -used to find and extract all translatable strings, and create a PO -template file out of all these. This `PACKAGE.pot' file contains all -original program strings. It has sets of pointers to exactly where in -C sources each string is used. All translations are set to empty. The -letter `t' in `.pot' marks this as a Template PO file, not yet oriented -towards any particular language. *Note xgettext Invocation::, for more -details about how one calls the `xgettext' program. If you are -_really_ lazy, you might be interested at working a lot more right -away, and preparing the whole distribution setup (*note Maintainers::). -By doing so, you spare yourself typing the `xgettext' command, as `make' -should now generate the proper things automatically for you! - - The first time through, there is no `LANG.po' yet, so the `msgmerge' -step may be skipped and replaced by a mere copy of `PACKAGE.pot' to -`LANG.po', where LANG represents the target language. See *note -Creating:: for details. - - Then comes the initial translation of messages. Translation in -itself is a whole matter, still exclusively meant for humans, and whose -complexity far overwhelms the level of this manual. Nevertheless, a -few hints are given in some other chapter of this manual (*note -Translators::). You will also find there indications about how to -contact translating teams, or becoming part of them, for sharing your -translating concerns with others who target the same native language. - - While adding the translated messages into the `LANG.po' PO file, if -you are not using one of the dedicated PO file editors (*note -Editing::), you are on your own for ensuring that your efforts fully -respect the PO file format, and quoting conventions (*note PO Files::). -This is surely not an impossible task, as this is the way many people -have handled PO files around 1995. On the other hand, by using a PO -file editor, most details of PO file format are taken care of for you, -but you have to acquire some familiarity with PO file editor itself. - - If some common translations have already been saved into a compendium -PO file, translators may use PO mode for initializing untranslated -entries from the compendium, and also save selected translations into -the compendium, updating it (*note Compendium::). Compendium files are -meant to be exchanged between members of a given translation team. - - Programs, or packages of programs, are dynamic in nature: users write -bug reports and suggestion for improvements, maintainers react by -modifying programs in various ways. The fact that a package has -already been internationalized should not make maintainers shy of -adding new strings, or modifying strings already translated. They just -do their job the best they can. For the Translation Project to work -smoothly, it is important that maintainers do not carry translation -concerns on their already loaded shoulders, and that translators be -kept as free as possible of programming concerns. - - The only concern maintainers should have is carefully marking new -strings as translatable, when they should be, and do not otherwise -worry about them being translated, as this will come in proper time. -Consequently, when programs and their strings are adjusted in various -ways by maintainers, and for matters usually unrelated to translation, -`xgettext' would construct `PACKAGE.pot' files which are evolving over -time, so the translations carried by `LANG.po' are slowly fading out of -date. - - It is important for translators (and even maintainers) to understand -that package translation is a continuous process in the lifetime of a -package, and not something which is done once and for all at the start. -After an initial burst of translation activity for a given package, -interventions are needed once in a while, because here and there, -translated entries become obsolete, and new untranslated entries -appear, needing translation. - - The `msgmerge' program has the purpose of refreshing an already -existing `LANG.po' file, by comparing it with a newer `PACKAGE.pot' -template file, extracted by `xgettext' out of recent C sources. The -refreshing operation adjusts all references to C source locations for -strings, since these strings move as programs are modified. Also, -`msgmerge' comments out as obsolete, in `LANG.po', those already -translated entries which are no longer used in the program sources -(*note Obsolete Entries::). It finally discovers new strings and -inserts them in the resulting PO file as untranslated entries (*note -Untranslated Entries::). *Note msgmerge Invocation::, for more -information about what `msgmerge' really does. - - Whatever route or means taken, the goal is to obtain an updated -`LANG.po' file offering translations for all strings. - - The temporal mobility, or fluidity of PO files, is an integral part -of the translation game, and should be well understood, and accepted. -People resisting it will have a hard time participating in the -Translation Project, or will give a hard time to other participants! In -particular, maintainers should relax and include all available official -PO files in their distributions, even if these have not recently been -updated, without exerting pressure on the translator teams to get the -job done. The pressure should rather come from the community of users -speaking a particular language, and maintainers should consider -themselves fairly relieved of any concern about the adequacy of -translation files. On the other hand, translators should reasonably -try updating the PO files they are responsible for, while the package -is undergoing pretest, prior to an official distribution. - - Once the PO file is complete and dependable, the `msgfmt' program is -used for turning the PO file into a machine-oriented format, which may -yield efficient retrieval of translations by the programs of the -package, whenever needed at runtime (*note MO Files::). *Note msgfmt -Invocation::, for more information about all modes of execution for the -`msgfmt' program. - - Finally, the modified and marked C sources are compiled and linked -with the GNU `gettext' library, usually through the operation of -`make', given a suitable `Makefile' exists for the project, and the -resulting executable is installed somewhere users will find it. The MO -files themselves should also be properly installed. Given the -appropriate environment variables are set (*note Setting the POSIX -Locale::), the program should localize itself automatically, whenever -it executes. - - The remainder of this manual has the purpose of explaining in depth -the various steps outlined above. - - -File: gettext.info, Node: Users, Next: PO Files, Prev: Introduction, Up: Top - -2 The User's View -***************** - - Nowadays, when users log into a computer, they usually find that all -their programs show messages in their native language - at least for -users of languages with an active free software community, like French -or German; to a lesser extent for languages with a smaller -participation in free software and the GNU project, like Hindi and -Filipino. - - How does this work? How can the user influence the language that is -used by the programs? This chapter will answer it. - -* Menu: - -* System Installation:: Questions During Operating System Installation -* Setting the GUI Locale:: How to Specify the Locale Used by GUI Programs -* Setting the POSIX Locale:: How to Specify the Locale According to POSIX -* Installing Localizations:: How to Install Additional Translations - - -File: gettext.info, Node: System Installation, Next: Setting the GUI Locale, Prev: Users, Up: Users - -2.1 Operating System Installation -================================= - - The default language is often already specified during operating -system installation. When the operating system is installed, the -installer typically asks for the language used for the installation -process and, separately, for the language to use in the installed -system. Some OS installers only ask for the language once. - - This determines the system-wide default language for all users. But -the installers often give the possibility to install extra -localizations for additional languages. For example, the localizations -of KDE (the K Desktop Environment) and OpenOffice.org are often bundled -separately, as one installable package per language. - - At this point it is good to consider the intended use of the -machine: If it is a machine designated for personal use, additional -localizations are probably not necessary. If, however, the machine is -in use in an organization or company that has international -relationships, one can consider the needs of guest users. If you have -a guest from abroad, for a week, what could be his preferred locales? -It may be worth installing these additional localizations ahead of -time, since they cost only a bit of disk space at this point. - - The system-wide default language is the locale configuration that is -used when a new user account is created. But the user can have his own -locale configuration that is different from the one of the other users -of the same machine. He can specify it, typically after the first -login, as described in the next section. - - -File: gettext.info, Node: Setting the GUI Locale, Next: Setting the POSIX Locale, Prev: System Installation, Up: Users - -2.2 Setting the Locale Used by GUI Programs -=========================================== - - The immediately available programs in a user's desktop come from a -group of programs called a "desktop environment"; it usually includes -the window manager, a web browser, a text editor, and more. The most -common free desktop environments are KDE, GNOME, and Xfce. - - The locale used by GUI programs of the desktop environment can be -specified in a configuration screen called "control center", "language -settings" or "country settings". - - Individual GUI programs that are not part of the desktop environment -can have their locale specified either in a settings panel, or through -environment variables. - - For some programs, it is possible to specify the locale through -environment variables, possibly even to a different locale than the -desktop's locale. This means, instead of starting a program through a -menu or from the file system, you can start it from the command-line, -after having set some environment variables. The environment variables -can be those specified in the next section (*note Setting the POSIX -Locale::); for some versions of KDE, however, the locale is specified -through a variable `KDE_LANG', rather than `LANG' or `LC_ALL'. - - -File: gettext.info, Node: Setting the POSIX Locale, Next: Installing Localizations, Prev: Setting the GUI Locale, Up: Users - -2.3 Setting the Locale through Environment Variables -==================================================== - - As a user, if your language has been installed for this package, in -the simplest case, you only have to set the `LANG' environment variable -to the appropriate `LL_CC' combination. For example, let's suppose -that you speak German and live in Germany. At the shell prompt, merely -execute `setenv LANG de_DE' (in `csh'), `export LANG; LANG=de_DE' (in -`sh') or `export LANG=de_DE' (in `bash'). This can be done from your -`.login' or `.profile' file, once and for all. - -* Menu: - -* Locale Names:: How a Locale Specification Looks Like -* Locale Environment Variables:: Which Environment Variable Specfies What -* The LANGUAGE variable:: How to Specify a Priority List of Languages - - -File: gettext.info, Node: Locale Names, Next: Locale Environment Variables, Prev: Setting the POSIX Locale, Up: Setting the POSIX Locale - -2.3.1 Locale Names ------------------- - - A locale name usually has the form `LL_CC'. Here `LL' is an ISO 639 -two-letter language code, and `CC' is an ISO 3166 two-letter country -code. For example, for German in Germany, LL is `de', and CC is `DE'. -You find a list of the language codes in appendix *note Language -Codes:: and a list of the country codes in appendix *note Country -Codes::. - - You might think that the country code specification is redundant. -But in fact, some languages have dialects in different countries. For -example, `de_AT' is used for Austria, and `pt_BR' for Brazil. The -country code serves to distinguish the dialects. - - Many locale names have an extended syntax `LL_CC.ENCODING' that also -specifies the character encoding. These are in use because between -2000 and 2005, most users have switched to locales in UTF-8 encoding. -For example, the German locale on glibc systems is nowadays -`de_DE.UTF-8'. The older name `de_DE' still refers to the German -locale as of 2000 that stores characters in ISO-8859-1 encoding - a -text encoding that cannot even accomodate the Euro currency sign. - - Some locale names use `LL_CC.@VARIANT' instead of `LL_CC'. The -`@VARIANT' can denote any kind of characteristics that is not already -implied by the language LL and the country CC. It can denote a -particular monetary unit. For example, on glibc systems, `de_DE@euro' -denotes the locale that uses the Euro currency, in contrast to the -older locale `de_DE' which implies the use of the currency before 2002. -It can also denote a dialect of the language, or the script used to -write text (for example, `sr_RS@latin' uses the Latin script, whereas -`sr_RS' uses the Cyrillic script to write Serbian), or the orthography -rules, or similar. - - On other systems, some variations of this scheme are used, such as -`LL'. You can get the list of locales supported by your system for -your language by running the command `locale -a | grep '^LL''. - - There is also a special locale, called `C'. When it is used, it -disables all localization: in this locale, all programs standardized by -POSIX use English messages and an unspecified character encoding (often -US-ASCII, but sometimes also ISO-8859-1 or UTF-8, depending on the -operating system). - - -File: gettext.info, Node: Locale Environment Variables, Next: The LANGUAGE variable, Prev: Locale Names, Up: Setting the POSIX Locale - -2.3.2 Locale Environment Variables ----------------------------------- - - A locale is composed of several _locale categories_, see *note -Aspects::. When a program looks up locale dependent values, it does -this according to the following environment variables, in priority -order: - - 1. `LANGUAGE' - - 2. `LC_ALL' - - 3. `LC_xxx', according to selected locale category: `LC_CTYPE', - `LC_NUMERIC', `LC_TIME', `LC_COLLATE', `LC_MONETARY', - `LC_MESSAGES', ... - - 4. `LANG' - - Variables whose value is set but is empty are ignored in this lookup. - - `LANG' is the normal environment variable for specifying a locale. -As a user, you normally set this variable (unless some of the other -variables have already been set by the system, in `/etc/profile' or -similar initialization files). - - `LC_CTYPE', `LC_NUMERIC', `LC_TIME', `LC_COLLATE', `LC_MONETARY', -`LC_MESSAGES', and so on, are the environment variables meant to -override `LANG' and affecting a single locale category only. For -example, assume you are a Swedish user in Spain, and you want your -programs to handle numbers and dates according to Spanish conventions, -and only the messages should be in Swedish. Then you could create a -locale named `sv_ES' or `sv_ES.UTF-8' by use of the `localedef' -program. But it is simpler, and achieves the same effect, to set the -`LANG' variable to `es_ES.UTF-8' and the `LC_MESSAGES' variable to -`sv_SE.UTF-8'; these two locales come already preinstalled with the -operating system. - - `LC_ALL' is an environment variable that overrides all of these. It -is typically used in scripts that run particular programs. For example, -`configure' scripts generated by GNU autoconf use `LC_ALL' to make sure -that the configuration tests don't operate in locale dependent ways. - - Some systems, unfortunately, set `LC_ALL' in `/etc/profile' or in -similar initialization files. As a user, you therefore have to unset -this variable if you want to set `LANG' and optionally some of the other -`LC_xxx' variables. - - The `LANGUAGE' variable is described in the next subsection. - - -File: gettext.info, Node: The LANGUAGE variable, Prev: Locale Environment Variables, Up: Setting the POSIX Locale - -2.3.3 Specifying a Priority List of Languages ---------------------------------------------- - - Not all programs have translations for all languages. By default, an -English message is shown in place of a nonexistent translation. If you -understand other languages, you can set up a priority list of languages. -This is done through a different environment variable, called -`LANGUAGE'. GNU `gettext' gives preference to `LANGUAGE' over `LC_ALL' -and `LANG' for the purpose of message handling, but you still need to -have `LANG' (or `LC_ALL') set to the primary language; this is required -by other parts of the system libraries. For example, some Swedish -users who would rather read translations in German than English for -when Swedish is not available, set `LANGUAGE' to `sv:de' while leaving -`LANG' to `sv_SE'. - - Special advice for Norwegian users: The language code for Norwegian -bokma*l changed from `no' to `nb' recently (in 2003). During the -transition period, while some message catalogs for this language are -installed under `nb' and some older ones under `no', it is recommended -for Norwegian users to set `LANGUAGE' to `nb:no' so that both newer and -older translations are used. - - In the `LANGUAGE' environment variable, but not in the other -environment variables, `LL_CC' combinations can be abbreviated as `LL' -to denote the language's main dialect. For example, `de' is equivalent -to `de_DE' (German as spoken in Germany), and `pt' to `pt_PT' -(Portuguese as spoken in Portugal) in this context. - - Note: The variable `LANGUAGE' is ignored if the locale is set to -`C'. In other words, you have to first enable localization, by setting -`LANG' (or `LC_ALL') to a value other than `C', before you can use a -language priority list through the `LANGUAGE' variable. - - -File: gettext.info, Node: Installing Localizations, Prev: Setting the POSIX Locale, Up: Users - -2.4 Installing Translations for Particular Programs -=================================================== - - Languages are not equally well supported in all packages using GNU -`gettext', and more translations are added over time. Usually, you use -the translations that are shipped with the operating system or with -particular packages that you install afterwards. But you can also -install newer localizations directly. For doing this, you will need an -understanding where each localization file is stored on the file system. - - For programs that participate in the Translation Project, you can -start looking for translations here: -`http://translationproject.org/team/index.html'. A snapshot of this -information is also found in the `ABOUT-NLS' file that is shipped with -GNU gettext. - - For programs that are part of the KDE project, the starting point is: -`http://i18n.kde.org/'. - - For programs that are part of the GNOME project, the starting point -is: `http://www.gnome.org/i18n/'. - - For other programs, you may check whether the program's source code -package contains some `LL.po' files; often they are kept together in a -directory called `po/'. Each `LL.po' file contains the message -translations for the language whose abbreviation of LL. - - -File: gettext.info, Node: PO Files, Next: Sources, Prev: Users, Up: Top - -3 The Format of PO Files -************************ - - The GNU `gettext' toolset helps programmers and translators at -producing, updating and using translation files, mainly those PO files -which are textual, editable files. This chapter explains the format of -PO files. - - A PO file is made up of many entries, each entry holding the relation -between an original untranslated string and its corresponding -translation. All entries in a given PO file usually pertain to a -single project, and all translations are expressed in a single target -language. One PO file "entry" has the following schematic structure: - - WHITE-SPACE - # TRANSLATOR-COMMENTS - #. EXTRACTED-COMMENTS - #: REFERENCE... - #, FLAG... - #| msgid PREVIOUS-UNTRANSLATED-STRING - msgid UNTRANSLATED-STRING - msgstr TRANSLATED-STRING - - The general structure of a PO file should be well understood by the -translator. When using PO mode, very little has to be known about the -format details, as PO mode takes care of them for her. - - A simple entry can look like this: - - #: lib/error.c:116 - msgid "Unknown system error" - msgstr "Error desconegut del sistema" - - Entries begin with some optional white space. Usually, when -generated through GNU `gettext' tools, there is exactly one blank line -between entries. Then comments follow, on lines all starting with the -character `#'. There are two kinds of comments: those which have some -white space immediately following the `#' - the TRANSLATOR COMMENTS -, -which comments are created and maintained exclusively by the -translator, and those which have some non-white character just after the -`#' - the AUTOMATIC COMMENTS -, which comments are created and -maintained automatically by GNU `gettext' tools. Comment lines -starting with `#.' contain comments given by the programmer, directed -at the translator; these comments are called EXTRACTED COMMENTS because -the `xgettext' program extracts them from the program's source code. -Comment lines starting with `#:' contain references to the program's -source code. Comment lines starting with `#,' contain flags; more -about these below. Comment lines starting with `#|' contain the -previous untranslated string for which the translator gave a -translation. - - All comments, of either kind, are optional. - - After white space and comments, entries show two strings, namely -first the untranslated string as it appears in the original program -sources, and then, the translation of this string. The original string -is introduced by the keyword `msgid', and the translation, by `msgstr'. -The two strings, untranslated and translated, are quoted in various -ways in the PO file, using `"' delimiters and `\' escapes, but the -translator does not really have to pay attention to the precise quoting -format, as PO mode fully takes care of quoting for her. - - The `msgid' strings, as well as automatic comments, are produced and -managed by other GNU `gettext' tools, and PO mode does not provide -means for the translator to alter these. The most she can do is merely -deleting them, and only by deleting the whole entry. On the other -hand, the `msgstr' string, as well as translator comments, are really -meant for the translator, and PO mode gives her the full control she -needs. - - The comment lines beginning with `#,' are special because they are -not completely ignored by the programs as comments generally are. The -comma separated list of FLAGs is used by the `msgfmt' program to give -the user some better diagnostic messages. Currently there are two -forms of flags defined: - -`fuzzy' - This flag can be generated by the `msgmerge' program or it can be - inserted by the translator herself. It shows that the `msgstr' - string might not be a correct translation (anymore). Only the - translator can judge if the translation requires further - modification, or is acceptable as is. Once satisfied with the - translation, she then removes this `fuzzy' attribute. The - `msgmerge' program inserts this when it combined the `msgid' and - `msgstr' entries after fuzzy search only. *Note Fuzzy Entries::. - -`c-format' -`no-c-format' - These flags should not be added by a human. Instead only the - `xgettext' program adds them. In an automated PO file processing - system as proposed here, the user's changes would be thrown away - again as soon as the `xgettext' program generates a new template - file. - - The `c-format' flag indicates that the untranslated string and the - translation are supposed to be C format strings. The `no-c-format' - flag indicates that they are not C format strings, even though the - untranslated string happens to look like a C format string (with - `%' directives). - - When the `c-format' flag is given for a string the `msgfmt' - program does some more tests to check the validity of the - translation. *Note msgfmt Invocation::, *note c-format Flag:: and - *note c-format::. - -`objc-format' -`no-objc-format' - Likewise for Objective C, see *note objc-format::. - -`sh-format' -`no-sh-format' - Likewise for Shell, see *note sh-format::. - -`python-format' -`no-python-format' - Likewise for Python, see *note python-format::. - -`lisp-format' -`no-lisp-format' - Likewise for Lisp, see *note lisp-format::. - -`elisp-format' -`no-elisp-format' - Likewise for Emacs Lisp, see *note elisp-format::. - -`librep-format' -`no-librep-format' - Likewise for librep, see *note librep-format::. - -`scheme-format' -`no-scheme-format' - Likewise for Scheme, see *note scheme-format::. - -`smalltalk-format' -`no-smalltalk-format' - Likewise for Smalltalk, see *note smalltalk-format::. - -`java-format' -`no-java-format' - Likewise for Java, see *note java-format::. - -`csharp-format' -`no-csharp-format' - Likewise for C#, see *note csharp-format::. - -`awk-format' -`no-awk-format' - Likewise for awk, see *note awk-format::. - -`object-pascal-format' -`no-object-pascal-format' - Likewise for Object Pascal, see *note object-pascal-format::. - -`ycp-format' -`no-ycp-format' - Likewise for YCP, see *note ycp-format::. - -`tcl-format' -`no-tcl-format' - Likewise for Tcl, see *note tcl-format::. - -`perl-format' -`no-perl-format' - Likewise for Perl, see *note perl-format::. - -`perl-brace-format' -`no-perl-brace-format' - Likewise for Perl brace, see *note perl-format::. - -`php-format' -`no-php-format' - Likewise for PHP, see *note php-format::. - -`gcc-internal-format' -`no-gcc-internal-format' - Likewise for the GCC sources, see *note gcc-internal-format::. - -`gfc-internal-format' -`no-gfc-internal-format' - Likewise for the GNU Fortran Compiler sources, see *note - gfc-internal-format::. - -`qt-format' -`no-qt-format' - Likewise for Qt, see *note qt-format::. - -`qt-plural-format' -`no-qt-plural-format' - Likewise for Qt plural forms, see *note qt-plural-format::. - -`kde-format' -`no-kde-format' - Likewise for KDE, see *note kde-format::. - -`boost-format' -`no-boost-format' - Likewise for Boost, see *note boost-format::. - - - It is also possible to have entries with a context specifier. They -look like this: - - WHITE-SPACE - # TRANSLATOR-COMMENTS - #. EXTRACTED-COMMENTS - #: REFERENCE... - #, FLAG... - #| msgctxt PREVIOUS-CONTEXT - #| msgid PREVIOUS-UNTRANSLATED-STRING - msgctxt CONTEXT - msgid UNTRANSLATED-STRING - msgstr TRANSLATED-STRING - - The context serves to disambiguate messages with the same -UNTRANSLATED-STRING. It is possible to have several entries with the -same UNTRANSLATED-STRING in a PO file, provided that they each have a -different CONTEXT. Note that an empty CONTEXT string and an absent -`msgctxt' line do not mean the same thing. - - A different kind of entries is used for translations which involve -plural forms. - - WHITE-SPACE - # TRANSLATOR-COMMENTS - #. EXTRACTED-COMMENTS - #: REFERENCE... - #, FLAG... - #| msgid PREVIOUS-UNTRANSLATED-STRING-SINGULAR - #| msgid_plural PREVIOUS-UNTRANSLATED-STRING-PLURAL - msgid UNTRANSLATED-STRING-SINGULAR - msgid_plural UNTRANSLATED-STRING-PLURAL - msgstr[0] TRANSLATED-STRING-CASE-0 - ... - msgstr[N] TRANSLATED-STRING-CASE-N - - Such an entry can look like this: - - #: src/msgcmp.c:338 src/po-lex.c:699 - #, c-format - msgid "found %d fatal error" - msgid_plural "found %d fatal errors" - msgstr[0] "s'ha trobat %d error fatal" - msgstr[1] "s'han trobat %d errors fatals" - - Here also, a `msgctxt' context can be specified before `msgid', like -above. - - Here, additional kinds of flags can be used: - -`range:' - This flag is followed by a range of non-negative numbers, using - the syntax `range: MINIMUM-VALUE..MAXIMUM-VALUE'. It designates - the possible values that the numeric parameter of the message can - take. In some languages, translators may produce slightly better - translations if they know that the value can only take on values - between 0 and 10, for example. - - The PREVIOUS-UNTRANSLATED-STRING is optionally inserted by the -`msgmerge' program, at the same time when it marks a message fuzzy. It -helps the translator to see which changes were done by the developers -on the UNTRANSLATED-STRING. - - It happens that some lines, usually whitespace or comments, follow -the very last entry of a PO file. Such lines are not part of any entry, -and will be dropped when the PO file is processed by the tools, or may -disturb some PO file editors. - - The remainder of this section may be safely skipped by those using a -PO file editor, yet it may be interesting for everybody to have a better -idea of the precise format of a PO file. On the other hand, those -wishing to modify PO files by hand should carefully continue reading on. - - Each of UNTRANSLATED-STRING and TRANSLATED-STRING respects the C -syntax for a character string, including the surrounding quotes and -embedded backslashed escape sequences. When the time comes to write -multi-line strings, one should not use escaped newlines. Instead, a -closing quote should follow the last character on the line to be -continued, and an opening quote should resume the string at the -beginning of the following PO file line. For example: - - msgid "" - "Here is an example of how one might continue a very long string\n" - "for the common case the string represents multi-line output.\n" - -In this example, the empty string is used on the first line, to allow -better alignment of the `H' from the word `Here' over the `f' from the -word `for'. In this example, the `msgid' keyword is followed by three -strings, which are meant to be concatenated. Concatenating the empty -string does not change the resulting overall string, but it is a way -for us to comply with the necessity of `msgid' to be followed by a -string on the same line, while keeping the multi-line presentation -left-justified, as we find this to be a cleaner disposition. The empty -string could have been omitted, but only if the string starting with -`Here' was promoted on the first line, right after `msgid'.(1) It was -not really necessary either to switch between the two last quoted -strings immediately after the newline `\n', the switch could have -occurred after _any_ other character, we just did it this way because -it is neater. - - One should carefully distinguish between end of lines marked as `\n' -_inside_ quotes, which are part of the represented string, and end of -lines in the PO file itself, outside string quotes, which have no -incidence on the represented string. - - Outside strings, white lines and comments may be used freely. -Comments start at the beginning of a line with `#' and extend until the -end of the PO file line. Comments written by translators should have -the initial `#' immediately followed by some white space. If the `#' -is not immediately followed by white space, this comment is most likely -generated and managed by specialized GNU tools, and might disappear or -be replaced unexpectedly when the PO file is given to `msgmerge'. - - ---------- Footnotes ---------- - - (1) This limitation is not imposed by GNU `gettext', but is for -compatibility with the `msgfmt' implementation on Solaris. - - -File: gettext.info, Node: Sources, Next: Template, Prev: PO Files, Up: Top - -4 Preparing Program Sources -*************************** - - For the programmer, changes to the C source code fall into three -categories. First, you have to make the localization functions known -to all modules needing message translation. Second, you should -properly trigger the operation of GNU `gettext' when the program -initializes, usually from the `main' function. Last, you should -identify, adjust and mark all constant strings in your program needing -translation. - -* Menu: - -* Importing:: Importing the `gettext' declaration -* Triggering:: Triggering `gettext' Operations -* Preparing Strings:: Preparing Translatable Strings -* Mark Keywords:: How Marks Appear in Sources -* Marking:: Marking Translatable Strings -* c-format Flag:: Telling something about the following string -* Special cases:: Special Cases of Translatable Strings -* Bug Report Address:: Letting Users Report Translation Bugs -* Names:: Marking Proper Names for Translation -* Libraries:: Preparing Library Sources - - -File: gettext.info, Node: Importing, Next: Triggering, Prev: Sources, Up: Sources - -4.1 Importing the `gettext' declaration -======================================= - - Presuming that your set of programs, or package, has been adjusted -so all needed GNU `gettext' files are available, and your `Makefile' -files are adjusted (*note Maintainers::), each C module having -translated C strings should contain the line: - - #include <libintl.h> - - Similarly, each C module containing `printf()'/`fprintf()'/... -calls with a format string that could be a translated C string (even if -the C string comes from a different C module) should contain the line: - - #include <libintl.h> - - -File: gettext.info, Node: Triggering, Next: Preparing Strings, Prev: Importing, Up: Sources - -4.2 Triggering `gettext' Operations -=================================== - - The initialization of locale data should be done with more or less -the same code in every program, as demonstrated below: - - int - main (int argc, char *argv[]) - { - ... - setlocale (LC_ALL, ""); - bindtextdomain (PACKAGE, LOCALEDIR); - textdomain (PACKAGE); - ... - } - - PACKAGE and LOCALEDIR should be provided either by `config.h' or by -the Makefile. For now consult the `gettext' or `hello' sources for -more information. - - The use of `LC_ALL' might not be appropriate for you. `LC_ALL' -includes all locale categories and especially `LC_CTYPE'. This latter -category is responsible for determining character classes with the -`isalnum' etc. functions from `ctype.h' which could especially for -programs, which process some kind of input language, be wrong. For -example this would mean that a source code using the ç (c-cedilla -character) is runnable in France but not in the U.S. - - Some systems also have problems with parsing numbers using the -`scanf' functions if an other but the `LC_ALL' locale category is used. -The standards say that additional formats but the one known in the -`"C"' locale might be recognized. But some systems seem to reject -numbers in the `"C"' locale format. In some situation, it might also -be a problem with the notation itself which makes it impossible to -recognize whether the number is in the `"C"' locale or the local -format. This can happen if thousands separator characters are used. -Some locales define this character according to the national -conventions to `'.'' which is the same character used in the `"C"' -locale to denote the decimal point. - - So it is sometimes necessary to replace the `LC_ALL' line in the -code above by a sequence of `setlocale' lines - - { - ... - setlocale (LC_CTYPE, ""); - setlocale (LC_MESSAGES, ""); - ... - } - -On all POSIX conformant systems the locale categories `LC_CTYPE', -`LC_MESSAGES', `LC_COLLATE', `LC_MONETARY', `LC_NUMERIC', and `LC_TIME' -are available. On some systems which are only ISO C compliant, -`LC_MESSAGES' is missing, but a substitute for it is defined in GNU -gettext's `<libintl.h>' and in GNU gnulib's `<locale.h>'. - - Note that changing the `LC_CTYPE' also affects the functions -declared in the `<ctype.h>' standard header and some functions declared -in the `<string.h>' and `<stdlib.h>' standard headers. If this is not -desirable in your application (for example in a compiler's parser), you -can use a set of substitute functions which hardwire the C locale, such -as found in the modules `c-ctype', `c-strcase', `c-strcasestr', -`c-strtod', `c-strtold' in the GNU gnulib source distribution. - - It is also possible to switch the locale forth and back between the -environment dependent locale and the C locale, but this approach is -normally avoided because a `setlocale' call is expensive, because it is -tedious to determine the places where a locale switch is needed in a -large program's source, and because switching a locale is not -multithread-safe. - - -File: gettext.info, Node: Preparing Strings, Next: Mark Keywords, Prev: Triggering, Up: Sources - -4.3 Preparing Translatable Strings -================================== - - Before strings can be marked for translations, they sometimes need to -be adjusted. Usually preparing a string for translation is done right -before marking it, during the marking phase which is described in the -next sections. What you have to keep in mind while doing that is the -following. - - * Decent English style. - - * Entire sentences. - - * Split at paragraphs. - - * Use format strings instead of string concatenation. - - * Avoid unusual markup and unusual control characters. - -Let's look at some examples of these guidelines. - - Translatable strings should be in good English style. If slang -language with abbreviations and shortcuts is used, often translators -will not understand the message and will produce very inappropriate -translations. - - "%s: is parameter\n" - -This is nearly untranslatable: Is the displayed item _a_ parameter or -_the_ parameter? - - "No match" - -The ambiguity in this message makes it unintelligible: Is the program -attempting to set something on fire? Does it mean "The given object does -not match the template"? Does it mean "The template does not fit for any -of the objects"? - - In both cases, adding more words to the message will help both the -translator and the English speaking user. - - Translatable strings should be entire sentences. It is often not -possible to translate single verbs or adjectives in a substitutable way. - - printf ("File %s is %s protected", filename, rw ? "write" : "read"); - -Most translators will not look at the source and will thus only see the -string `"File %s is %s protected"', which is unintelligible. Change -this to - - printf (rw ? "File %s is write protected" : "File %s is read protected", - filename); - -This way the translator will not only understand the message, she will -also be able to find the appropriate grammatical construction. A French -translator for example translates "write protected" like "protected -against writing". - - Entire sentences are also important because in many languages, the -declination of some word in a sentence depends on the gender or the -number (singular/plural) of another part of the sentence. There are -usually more interdependencies between words than in English. The -consequence is that asking a translator to translate two half-sentences -and then combining these two half-sentences through dumb string -concatenation will not work, for many languages, even though it would -work for English. That's why translators need to handle entire -sentences. - - Often sentences don't fit into a single line. If a sentence is -output using two subsequent `printf' statements, like this - - printf ("Locale charset \"%s\" is different from\n", lcharset); - printf ("input file charset \"%s\".\n", fcharset); - -the translator would have to translate two half sentences, but nothing -in the POT file would tell her that the two half sentences belong -together. It is necessary to merge the two `printf' statements so that -the translator can handle the entire sentence at once and decide at -which place to insert a line break in the translation (if at all): - - printf ("Locale charset \"%s\" is different from\n\ - input file charset \"%s\".\n", lcharset, fcharset); - - You may now ask: how about two or more adjacent sentences? Like in -this case: - - puts ("Apollo 13 scenario: Stack overflow handling failed."); - puts ("On the next stack overflow we will crash!!!"); - -Should these two statements merged into a single one? I would recommend -to merge them if the two sentences are related to each other, because -then it makes it easier for the translator to understand and translate -both. On the other hand, if one of the two messages is a stereotypic -one, occurring in other places as well, you will do a favour to the -translator by not merging the two. (Identical messages occurring in -several places are combined by xgettext, so the translator has to -handle them once only.) - - Translatable strings should be limited to one paragraph; don't let a -single message be longer than ten lines. The reason is that when the -translatable string changes, the translator is faced with the task of -updating the entire translated string. Maybe only a single word will -have changed in the English string, but the translator doesn't see that -(with the current translation tools), therefore she has to proofread -the entire message. - - Many GNU programs have a `--help' output that extends over several -screen pages. It is a courtesy towards the translators to split such a -message into several ones of five to ten lines each. While doing that, -you can also attempt to split the documented options into groups, such -as the input options, the output options, and the informative output -options. This will help every user to find the option he is looking -for. - - Hardcoded string concatenation is sometimes used to construct English -strings: - - strcpy (s, "Replace "); - strcat (s, object1); - strcat (s, " with "); - strcat (s, object2); - strcat (s, "?"); - -In order to present to the translator only entire sentences, and also -because in some languages the translator might want to swap the order -of `object1' and `object2', it is necessary to change this to use a -format string: - - sprintf (s, "Replace %s with %s?", object1, object2); - - A similar case is compile time concatenation of strings. The ISO C -99 include file `<inttypes.h>' contains a macro `PRId64' that can be -used as a formatting directive for outputting an `int64_t' integer -through `printf'. It expands to a constant string, usually "d" or "ld" -or "lld" or something like this, depending on the platform. Assume you -have code like - - printf ("The amount is %0" PRId64 "\n", number); - -The `gettext' tools and library have special support for these -`<inttypes.h>' macros. You can therefore simply write - - printf (gettext ("The amount is %0" PRId64 "\n"), number); - -The PO file will contain the string "The amount is %0<PRId64>\n". The -translators will provide a translation containing "%0<PRId64>" as well, -and at runtime the `gettext' function's result will contain the -appropriate constant string, "d" or "ld" or "lld". - - This works only for the predefined `<inttypes.h>' macros. If you -have defined your own similar macros, let's say `MYPRId64', that are -not known to `xgettext', the solution for this problem is to change the -code like this: - - char buf1[100]; - sprintf (buf1, "%0" MYPRId64, number); - printf (gettext ("The amount is %s\n"), buf1); - - This means, you put the platform dependent code in one statement, -and the internationalization code in a different statement. Note that -a buffer length of 100 is safe, because all available hardware integer -types are limited to 128 bits, and to print a 128 bit integer one needs -at most 54 characters, regardless whether in decimal, octal or -hexadecimal. - - All this applies to other programming languages as well. For -example, in Java and C#, string concatenation is very frequently used, -because it is a compiler built-in operator. Like in C, in Java, you -would change - - System.out.println("Replace "+object1+" with "+object2+"?"); - -into a statement involving a format string: - - System.out.println( - MessageFormat.format("Replace {0} with {1}?", - new Object[] { object1, object2 })); - -Similarly, in C#, you would change - - Console.WriteLine("Replace "+object1+" with "+object2+"?"); - -into a statement involving a format string: - - Console.WriteLine( - String.Format("Replace {0} with {1}?", object1, object2)); - - Unusual markup or control characters should not be used in -translatable strings. Translators will likely not understand the -particular meaning of the markup or control characters. - - For example, if you have a convention that `|' delimits the -left-hand and right-hand part of some GUI elements, translators will -often not understand it without specific comments. It might be better -to have the translator translate the left-hand and right-hand part -separately. - - Another example is the `argp' convention to use a single `\v' -(vertical tab) control character to delimit two sections inside a -string. This is flawed. Some translators may convert it to a simple -newline, some to blank lines. With some PO file editors it may not be -easy to even enter a vertical tab control character. So, you cannot be -sure that the translation will contain a `\v' character, at the -corresponding position. The solution is, again, to let the translator -translate two separate strings and combine at run-time the two -translated strings with the `\v' required by the convention. - - HTML markup, however, is common enough that it's probably ok to use -in translatable strings. But please bear in mind that the GNU gettext -tools don't verify that the translations are well-formed HTML. - - -File: gettext.info, Node: Mark Keywords, Next: Marking, Prev: Preparing Strings, Up: Sources - -4.4 How Marks Appear in Sources -=============================== - - All strings requiring translation should be marked in the C sources. -Marking is done in such a way that each translatable string appears to -be the sole argument of some function or preprocessor macro. There are -only a few such possible functions or macros meant for translation, and -their names are said to be marking keywords. The marking is attached -to strings themselves, rather than to what we do with them. This -approach has more uses. A blatant example is an error message produced -by formatting. The format string needs translation, as well as some -strings inserted through some `%s' specification in the format, while -the result from `sprintf' may have so many different instances that it -is impractical to list them all in some `error_string_out()' routine, -say. - - This marking operation has two goals. The first goal of marking is -for triggering the retrieval of the translation, at run time. The -keyword is possibly resolved into a routine able to dynamically return -the proper translation, as far as possible or wanted, for the argument -string. Most localizable strings are found in executable positions, -that is, attached to variables or given as parameters to functions. -But this is not universal usage, and some translatable strings appear -in structured initializations. *Note Special cases::. - - The second goal of the marking operation is to help `xgettext' at -properly extracting all translatable strings when it scans a set of -program sources and produces PO file templates. - - The canonical keyword for marking translatable strings is `gettext', -it gave its name to the whole GNU `gettext' package. For packages -making only light use of the `gettext' keyword, macro or function, it -is easily used _as is_. However, for packages using the `gettext' -interface more heavily, it is usually more convenient to give the main -keyword a shorter, less obtrusive name. Indeed, the keyword might -appear on a lot of strings all over the package, and programmers -usually do not want nor need their program sources to remind them -forcefully, all the time, that they are internationalized. Further, a -long keyword has the disadvantage of using more horizontal space, -forcing more indentation work on sources for those trying to keep them -within 79 or 80 columns. - - Many packages use `_' (a simple underline) as a keyword, and write -`_("Translatable string")' instead of `gettext ("Translatable -string")'. Further, the coding rule, from GNU standards, wanting that -there is a space between the keyword and the opening parenthesis is -relaxed, in practice, for this particular usage. So, the textual -overhead per translatable string is reduced to only three characters: -the underline and the two parentheses. However, even if GNU `gettext' -uses this convention internally, it does not offer it officially. The -real, genuine keyword is truly `gettext' indeed. It is fairly easy for -those wanting to use `_' instead of `gettext' to declare: - - #include <libintl.h> - #define _(String) gettext (String) - -instead of merely using `#include <libintl.h>'. - - The marking keywords `gettext' and `_' take the translatable string -as sole argument. It is also possible to define marking functions that -take it at another argument position. It is even possible to make the -marked argument position depend on the total number of arguments of the -function call; this is useful in C++. All this is achieved using -`xgettext''s `--keyword' option. How to pass such an option to -`xgettext', assuming that `gettextize' is used, is described in *note -po/Makevars:: and *note AM_XGETTEXT_OPTION::. - - Note also that long strings can be split across lines, into multiple -adjacent string tokens. Automatic string concatenation is performed at -compile time according to ISO C and ISO C++; `xgettext' also supports -this syntax. - - Later on, the maintenance is relatively easy. If, as a programmer, -you add or modify a string, you will have to ask yourself if the new or -altered string requires translation, and include it within `_()' if you -think it should be translated. For example, `"%s"' is an example of -string _not_ requiring translation. But `"%s: %d"' _does_ require -translation, because in French, unlike in English, it's customary to -put a space before a colon. - - -File: gettext.info, Node: Marking, Next: c-format Flag, Prev: Mark Keywords, Up: Sources - -4.5 Marking Translatable Strings -================================ - - In PO mode, one set of features is meant more for the programmer than -for the translator, and allows him to interactively mark which strings, -in a set of program sources, are translatable, and which are not. Even -if it is a fairly easy job for a programmer to find and mark such -strings by other means, using any editor of his choice, PO mode makes -this work more comfortable. Further, this gives translators who feel a -little like programmers, or programmers who feel a little like -translators, a tool letting them work at marking translatable strings -in the program sources, while simultaneously producing a set of -translation in some language, for the package being internationalized. - - The set of program sources, targeted by the PO mode commands describe -here, should have an Emacs tags table constructed for your project, -prior to using these PO file commands. This is easy to do. In any -shell window, change the directory to the root of your project, then -execute a command resembling: - - etags src/*.[hc] lib/*.[hc] - -presuming here you want to process all `.h' and `.c' files from the -`src/' and `lib/' directories. This command will explore all said -files and create a `TAGS' file in your root directory, somewhat -summarizing the contents using a special file format Emacs can -understand. - - For packages following the GNU coding standards, there is a make -goal `tags' or `TAGS' which constructs the tag files in all directories -and for all files containing source code. - - Once your `TAGS' file is ready, the following commands assist the -programmer at marking translatable strings in his set of sources. But -these commands are necessarily driven from within a PO file window, and -it is likely that you do not even have such a PO file yet. This is not -a problem at all, as you may safely open a new, empty PO file, mainly -for using these commands. This empty PO file will slowly fill in while -you mark strings as translatable in your program sources. - -`,' - Search through program sources for a string which looks like a - candidate for translation (`po-tags-search'). - -`M-,' - Mark the last string found with `_()' (`po-mark-translatable'). - -`M-.' - Mark the last string found with a keyword taken from a set of - possible keywords. This command with a prefix allows some - management of these keywords (`po-select-mark-and-mark'). - - - The `,' (`po-tags-search') command searches for the next occurrence -of a string which looks like a possible candidate for translation, and -displays the program source in another Emacs window, positioned in such -a way that the string is near the top of this other window. If the -string is too big to fit whole in this window, it is positioned so only -its end is shown. In any case, the cursor is left in the PO file -window. If the shown string would be better presented differently in -different native languages, you may mark it using `M-,' or `M-.'. -Otherwise, you might rather ignore it and skip to the next string by -merely repeating the `,' command. - - A string is a good candidate for translation if it contains a -sequence of three or more letters. A string containing at most two -letters in a row will be considered as a candidate if it has more -letters than non-letters. The command disregards strings containing no -letters, or isolated letters only. It also disregards strings within -comments, or strings already marked with some keyword PO mode knows -(see below). - - If you have never told Emacs about some `TAGS' file to use, the -command will request that you specify one from the minibuffer, the -first time you use the command. You may later change your `TAGS' file -by using the regular Emacs command `M-x visit-tags-table', which will -ask you to name the precise `TAGS' file you want to use. *Note Tag -Tables: (emacs)Tags. - - Each time you use the `,' command, the search resumes from where it -was left by the previous search, and goes through all program sources, -obeying the `TAGS' file, until all sources have been processed. -However, by giving a prefix argument to the command (`C-u ,'), you may -request that the search be restarted all over again from the first -program source; but in this case, strings that you recently marked as -translatable will be automatically skipped. - - Using this `,' command does not prevent using of other regular Emacs -tags commands. For example, regular `tags-search' or -`tags-query-replace' commands may be used without disrupting the -independent `,' search sequence. However, as implemented, the -_initial_ `,' command (or the `,' command is used with a prefix) might -also reinitialize the regular Emacs tags searching to the first tags -file, this reinitialization might be considered spurious. - - The `M-,' (`po-mark-translatable') command will mark the recently -found string with the `_' keyword. The `M-.' -(`po-select-mark-and-mark') command will request that you type one -keyword from the minibuffer and use that keyword for marking the -string. Both commands will automatically create a new PO file -untranslated entry for the string being marked, and make it the current -entry (making it easy for you to immediately proceed to its -translation, if you feel like doing it right away). It is possible -that the modifications made to the program source by `M-,' or `M-.' -render some source line longer than 80 columns, forcing you to break -and re-indent this line differently. You may use the `O' command from -PO mode, or any other window changing command from Emacs, to break out -into the program source window, and do any needed adjustments. You -will have to use some regular Emacs command to return the cursor to the -PO file window, if you want command `,' for the next string, say. - - The `M-.' command has a few built-in speedups, so you do not have to -explicitly type all keywords all the time. The first such speedup is -that you are presented with a _preferred_ keyword, which you may accept -by merely typing `<RET>' at the prompt. The second speedup is that you -may type any non-ambiguous prefix of the keyword you really mean, and -the command will complete it automatically for you. This also means -that PO mode has to _know_ all your possible keywords, and that it will -not accept mistyped keywords. - - If you reply `?' to the keyword request, the command gives a list of -all known keywords, from which you may choose. When the command is -prefixed by an argument (`C-u M-.'), it inhibits updating any program -source or PO file buffer, and does some simple keyword management -instead. In this case, the command asks for a keyword, written in -full, which becomes a new allowed keyword for later `M-.' commands. -Moreover, this new keyword automatically becomes the _preferred_ -keyword for later commands. By typing an already known keyword in -response to `C-u M-.', one merely changes the _preferred_ keyword and -does nothing more. - - All keywords known for `M-.' are recognized by the `,' command when -scanning for strings, and strings already marked by any of those known -keywords are automatically skipped. If many PO files are opened -simultaneously, each one has its own independent set of known keywords. -There is no provision in PO mode, currently, for deleting a known -keyword, you have to quit the file (maybe using `q') and reopen it -afresh. When a PO file is newly brought up in an Emacs window, only -`gettext' and `_' are known as keywords, and `gettext' is preferred for -the `M-.' command. In fact, this is not useful to prefer `_', as this -one is already built in the `M-,' command. - - -File: gettext.info, Node: c-format Flag, Next: Special cases, Prev: Marking, Up: Sources - -4.6 Special Comments preceding Keywords -======================================= - - In C programs strings are often used within calls of functions from -the `printf' family. The special thing about these format strings is -that they can contain format specifiers introduced with `%'. Assume we -have the code - - printf (gettext ("String `%s' has %d characters\n"), s, strlen (s)); - -A possible German translation for the above string might be: - - "%d Zeichen lang ist die Zeichenkette `%s'" - - A C programmer, even if he cannot speak German, will recognize that -there is something wrong here. The order of the two format specifiers -is changed but of course the arguments in the `printf' don't have. -This will most probably lead to problems because now the length of the -string is regarded as the address. - - To prevent errors at runtime caused by translations the `msgfmt' -tool can check statically whether the arguments in the original and the -translation string match in type and number. If this is not the case -and the `-c' option has been passed to `msgfmt', `msgfmt' will give an -error and refuse to produce a MO file. Thus consequent use of `msgfmt --c' will catch the error, so that it cannot cause cause problems at -runtime. - -If the word order in the above German translation would be correct one -would have to write - - "%2$d Zeichen lang ist die Zeichenkette `%1$s'" - -The routines in `msgfmt' know about this special notation. - - Because not all strings in a program must be format strings it is not -useful for `msgfmt' to test all the strings in the `.po' file. This -might cause problems because the string might contain what looks like a -format specifier, but the string is not used in `printf'. - - Therefore the `xgettext' adds a special tag to those messages it -thinks might be a format string. There is no absolute rule for this, -only a heuristic. In the `.po' file the entry is marked using the -`c-format' flag in the `#,' comment line (*note PO Files::). - - The careful reader now might say that this again can cause problems. -The heuristic might guess it wrong. This is true and therefore -`xgettext' knows about a special kind of comment which lets the -programmer take over the decision. If in the same line as or the -immediately preceding line to the `gettext' keyword the `xgettext' -program finds a comment containing the words `xgettext:c-format', it -will mark the string in any case with the `c-format' flag. This kind -of comment should be used when `xgettext' does not recognize the string -as a format string but it really is one and it should be tested. -Please note that when the comment is in the same line as the `gettext' -keyword, it must be before the string to be translated. - - This situation happens quite often. The `printf' function is often -called with strings which do not contain a format specifier. Of course -one would normally use `fputs' but it does happen. In this case -`xgettext' does not recognize this as a format string but what happens -if the translation introduces a valid format specifier? The `printf' -function will try to access one of the parameters but none exists -because the original code does not pass any parameters. - - `xgettext' of course could make a wrong decision the other way -round, i.e. a string marked as a format string actually is not a format -string. In this case the `msgfmt' might give too many warnings and -would prevent translating the `.po' file. The method to prevent this -wrong decision is similar to the one used above, only the comment to -use must contain the string `xgettext:no-c-format'. - - If a string is marked with `c-format' and this is not correct the -user can find out who is responsible for the decision. See *note -xgettext Invocation:: to see how the `--debug' option can be used for -solving this problem. - - -File: gettext.info, Node: Special cases, Next: Bug Report Address, Prev: c-format Flag, Up: Sources - -4.7 Special Cases of Translatable Strings -========================================= - - The attentive reader might now point out that it is not always -possible to mark translatable string with `gettext' or something like -this. Consider the following case: - - { - static const char *messages[] = { - "some very meaningful message", - "and another one" - }; - const char *string; - ... - string - = index > 1 ? "a default message" : messages[index]; - - fputs (string); - ... - } - - While it is no problem to mark the string `"a default message"' it -is not possible to mark the string initializers for `messages'. What -is to be done? We have to fulfill two tasks. First we have to mark the -strings so that the `xgettext' program (*note xgettext Invocation::) -can find them, and second we have to translate the string at runtime -before printing them. - - The first task can be fulfilled by creating a new keyword, which -names a no-op. For the second we have to mark all access points to a -string from the array. So one solution can look like this: - - #define gettext_noop(String) String - - { - static const char *messages[] = { - gettext_noop ("some very meaningful message"), - gettext_noop ("and another one") - }; - const char *string; - ... - string - = index > 1 ? gettext ("a default message") : gettext (messages[index]); - - fputs (string); - ... - } - - Please convince yourself that the string which is written by `fputs' -is translated in any case. How to get `xgettext' know the additional -keyword `gettext_noop' is explained in *note xgettext Invocation::. - - The above is of course not the only solution. You could also come -along with the following one: - - #define gettext_noop(String) String - - { - static const char *messages[] = { - gettext_noop ("some very meaningful message", - gettext_noop ("and another one") - }; - const char *string; - ... - string - = index > 1 ? gettext_noop ("a default message") : messages[index]; - - fputs (gettext (string)); - ... - } - - But this has a drawback. The programmer has to take care that he -uses `gettext_noop' for the string `"a default message"'. A use of -`gettext' could have in rare cases unpredictable results. - - One advantage is that you need not make control flow analysis to make -sure the output is really translated in any case. But this analysis is -generally not very difficult. If it should be in any situation you can -use this second method in this situation. - - -File: gettext.info, Node: Bug Report Address, Next: Names, Prev: Special cases, Up: Sources - -4.8 Letting Users Report Translation Bugs -========================================= - - Code sometimes has bugs, but translations sometimes have bugs too. -The users need to be able to report them. Reporting translation bugs -to the programmer or maintainer of a package is not very useful, since -the maintainer must never change a translation, except on behalf of the -translator. Hence the translation bugs must be reported to the -translators. - - Here is a way to organize this so that the maintainer does not need -to forward translation bug reports, nor even keep a list of the -addresses of the translators or their translation teams. - - Every program has a place where is shows the bug report address. For -GNU programs, it is the code which handles the "-help" option, -typically in a function called "usage". In this place, instruct the -translator to add her own bug reporting address. For example, if that -code has a statement - - printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT); - - you can add some translator instructions like this: - - /* TRANSLATORS: The placeholder indicates the bug-reporting address - for this package. Please add _another line_ saying - "Report translation bugs to <...>\n" with the address for translation - bugs (typically your translation team's web or email address). */ - printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT); - - These will be extracted by `xgettext', leading to a .pot file that -contains this: - - #. TRANSLATORS: The placeholder indicates the bug-reporting address - #. for this package. Please add _another line_ saying - #. "Report translation bugs to <...>\n" with the address for translation - #. bugs (typically your translation team's web or email address). - #: src/hello.c:178 - #, c-format - msgid "Report bugs to <%s>.\n" - msgstr "" - - -File: gettext.info, Node: Names, Next: Libraries, Prev: Bug Report Address, Up: Sources - -4.9 Marking Proper Names for Translation -======================================== - - Should names of persons, cities, locations etc. be marked for -translation or not? People who only know languages that can be written -with Latin letters (English, Spanish, French, German, etc.) are tempted -to say "no", because names usually do not change when transported -between these languages. However, in general when translating from one -script to another, names are translated too, usually phonetically or by -transliteration. For example, Russian or Greek names are converted to -the Latin alphabet when being translated to English, and English or -French names are converted to the Katakana script when being translated -to Japanese. This is necessary because the speakers of the target -language in general cannot read the script the name is originally -written in. - - As a programmer, you should therefore make sure that names are marked -for translation, with a special comment telling the translators that it -is a proper name and how to pronounce it. In its simple form, it looks -like this: - - printf (_("Written by %s.\n"), - /* TRANSLATORS: This is a proper name. See the gettext - manual, section Names. Note this is actually a non-ASCII - name: The first name is (with Unicode escapes) - "Fran\u00e7ois" or (with HTML entities) "François". - Pronunciation is like "fraa-swa pee-nar". */ - _("Francois Pinard")); - -The GNU gnulib library offers a module `propername' -(`http://www.gnu.org/software/gnulib/MODULES.html#module=propername') -which takes care to automatically append the original name, in -parentheses, to the translated name. For names that cannot be written -in ASCII, it also frees the translator from the task of entering the -appropriate non-ASCII characters if no script change is needed. In -this more comfortable form, it looks like this: - - printf (_("Written by %s and %s.\n"), - proper_name ("Ulrich Drepper"), - /* TRANSLATORS: This is a proper name. See the gettext - manual, section Names. Note this is actually a non-ASCII - name: The first name is (with Unicode escapes) - "Fran\u00e7ois" or (with HTML entities) "François". - Pronunciation is like "fraa-swa pee-nar". */ - proper_name_utf8 ("Francois Pinard", "Fran\303\247ois Pinard")); - -You can also write the original name directly in Unicode (rather than -with Unicode escapes or HTML entities) and denote the pronunciation -using the International Phonetic Alphabet (see -`http://www.wikipedia.org/wiki/International_Phonetic_Alphabet'). - - As a translator, you should use some care when translating names, -because it is frustrating if people see their names mutilated or -distorted. - - If your language uses the Latin script, all you need to do is to -reproduce the name as perfectly as you can within the usual character -set of your language. In this particular case, this means to provide a -translation containing the c-cedilla character. If your language uses -a different script and the people speaking it don't usually read Latin -words, it means transliteration. If the programmer used the simple -case, you should still give, in parentheses, the original writing of -the name - for the sake of the people that do read the Latin script. -If the programmer used the `propername' module mentioned above, you -don't need to give the original writing of the name in parentheses, -because the program will already do so. Here is an example, using -Greek as the target script: - - #. This is a proper name. See the gettext - #. manual, section Names. Note this is actually a non-ASCII - #. name: The first name is (with Unicode escapes) - #. "Fran\u00e7ois" or (with HTML entities) "François". - #. Pronunciation is like "fraa-swa pee-nar". - msgid "Francois Pinard" - msgstr "\phi\rho\alpha\sigma\omicron\alpha \pi\iota\nu\alpha\rho" - " (Francois Pinard)" - - Because translation of names is such a sensitive domain, it is a good -idea to test your translation before submitting it. - - -File: gettext.info, Node: Libraries, Prev: Names, Up: Sources - -4.10 Preparing Library Sources -============================== - - When you are preparing a library, not a program, for the use of -`gettext', only a few details are different. Here we assume that the -library has a translation domain and a POT file of its own. (If it -uses the translation domain and POT file of the main program, then the -previous sections apply without changes.) - - 1. The library code doesn't call `setlocale (LC_ALL, "")'. It's the - responsibility of the main program to set the locale. The - library's documentation should mention this fact, so that - developers of programs using the library are aware of it. - - 2. The library code doesn't call `textdomain (PACKAGE)', because it - would interfere with the text domain set by the main program. - - 3. The initialization code for a program was - - setlocale (LC_ALL, ""); - bindtextdomain (PACKAGE, LOCALEDIR); - textdomain (PACKAGE); - - For a library it is reduced to - - bindtextdomain (PACKAGE, LOCALEDIR); - - If your library's API doesn't already have an initialization - function, you need to create one, containing at least the - `bindtextdomain' invocation. However, you usually don't need to - export and document this initialization function: It is sufficient - that all entry points of the library call the initialization - function if it hasn't been called before. The typical idiom used - to achieve this is a static boolean variable that indicates - whether the initialization function has been called. Like this: - - static bool libfoo_initialized; - - static void - libfoo_initialize (void) - { - bindtextdomain (PACKAGE, LOCALEDIR); - libfoo_initialized = true; - } - - /* This function is part of the exported API. */ - struct foo * - create_foo (...) - { - /* Must ensure the initialization is performed. */ - if (!libfoo_initialized) - libfoo_initialize (); - ... - } - - /* This function is part of the exported API. The argument must be - non-NULL and have been created through create_foo(). */ - int - foo_refcount (struct foo *argument) - { - /* No need to invoke the initialization function here, because - create_foo() must already have been called before. */ - ... - } - - 4. The usual declaration of the `_' macro in each source file was - - #include <libintl.h> - #define _(String) gettext (String) - - for a program. For a library, which has its own translation - domain, it reads like this: - - #include <libintl.h> - #define _(String) dgettext (PACKAGE, String) - - In other words, `dgettext' is used instead of `gettext'. - Similarly, the `dngettext' function should be used in place of the - `ngettext' function. - - -File: gettext.info, Node: Template, Next: Creating, Prev: Sources, Up: Top - -5 Making the PO Template File -***************************** - - After preparing the sources, the programmer creates a PO template -file. This section explains how to use `xgettext' for this purpose. - - `xgettext' creates a file named `DOMAINNAME.po'. You should then -rename it to `DOMAINNAME.pot'. (Why doesn't `xgettext' create it under -the name `DOMAINNAME.pot' right away? The answer is: for historical -reasons. When `xgettext' was specified, the distinction between a PO -file and PO file template was fuzzy, and the suffix `.pot' wasn't in -use at that time.) - -* Menu: - -* xgettext Invocation:: Invoking the `xgettext' Program - - -File: gettext.info, Node: xgettext Invocation, Prev: Template, Up: Template - -5.1 Invoking the `xgettext' Program -=================================== - - xgettext [OPTION] [INPUTFILE] ... - - The `xgettext' program extracts translatable strings from given -input files. - -5.1.1 Input file location -------------------------- - -`INPUTFILE ...' - Input files. - -`-f FILE' -`--files-from=FILE' - Read the names of the input files from FILE instead of getting - them from the command line. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - - - If INPUTFILE is `-', standard input is read. - -5.1.2 Output file location --------------------------- - -`-d NAME' -`--default-domain=NAME' - Use `NAME.po' for output (instead of `messages.po'). - -`-o FILE' -`--output=FILE' - Write output to specified file (instead of `NAME.po' or - `messages.po'). - -`-p DIR' -`--output-dir=DIR' - Output files will be placed in directory DIR. - - - If the output FILE is `-' or `/dev/stdout', the output is written to -standard output. - -5.1.3 Choice of input file language ------------------------------------ - -`-L NAME' -`--language=NAME' - Specifies the language of the input files. The supported languages - are `C', `C++', `ObjectiveC', `PO', `Python', `Lisp', `EmacsLisp', - `librep', `Scheme', `Smalltalk', `Java', `JavaProperties', `C#', - `awk', `YCP', `Tcl', `Perl', `PHP', `GCC-source', `NXStringTable', - `RST', `Glade'. - -`-C' -`--c++' - This is a shorthand for `--language=C++'. - - - By default the language is guessed depending on the input file name -extension. - -5.1.4 Input file interpretation -------------------------------- - -`--from-code=NAME' - Specifies the encoding of the input files. This option is needed - only if some untranslated message strings or their corresponding - comments contain non-ASCII characters. Note that Tcl and Glade - input files are always assumed to be in UTF-8, regardless of this - option. - - - By default the input files are assumed to be in ASCII. - -5.1.5 Operation mode --------------------- - -`-j' -`--join-existing' - Join messages with existing file. - -`-x FILE' -`--exclude-file=FILE' - Entries from FILE are not extracted. FILE should be a PO or POT - file. - -`-c[TAG]' -`--add-comments[=TAG]' - Place comment blocks starting with TAG and preceding keyword lines - in the output file. Without a TAG, the option means to put _all_ - comment blocks preceding keyword lines in the output file. - - -5.1.6 Language specific options -------------------------------- - -`-a' -`--extract-all' - Extract all strings. - - This option has an effect with most languages, namely C, C++, - ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, - Tcl, Perl, PHP, GCC-source, Glade. - -`-k[KEYWORDSPEC]' -`--keyword[=KEYWORDSPEC]' - Specify KEYWORDSPEC as an additional keyword to be looked for. - Without a KEYWORDSPEC, the option means to not use default - keywords. - - If KEYWORDSPEC is a C identifier ID, `xgettext' looks for strings - in the first argument of each call to the function or macro ID. - If KEYWORDSPEC is of the form `ID:ARGNUM', `xgettext' looks for - strings in the ARGNUMth argument of the call. If KEYWORDSPEC is - of the form `ID:ARGNUM1,ARGNUM2', `xgettext' looks for strings in - the ARGNUM1st argument and in the ARGNUM2nd argument of the call, - and treats them as singular/plural variants for a message with - plural handling. Also, if KEYWORDSPEC is of the form - `ID:CONTEXTARGNUMc,ARGNUM' or `ID:ARGNUM,CONTEXTARGNUMc', - `xgettext' treats strings in the CONTEXTARGNUMth argument as a - context specifier. And, as a special-purpose support for GNOME, - if KEYWORDSPEC is of the form `ID:ARGNUMg', `xgettext' recognizes - the ARGNUMth argument as a string with context, using the GNOME - `glib' syntax `"msgctxt|msgid"'. - Furthermore, if KEYWORDSPEC is of the form `ID:...,TOTALNUMARGSt', - `xgettext' recognizes this argument specification only if the - number of actual arguments is equal to TOTALNUMARGS. This is - useful for disambiguating overloaded function calls in C++. - Finally, if KEYWORDSPEC is of the form `ID:ARGNUM...,"XCOMMENT"', - `xgettext', when extracting a message from the specified argument - strings, adds an extracted comment XCOMMENT to the message. Note - that when used through a normal shell command line, the - double-quotes around the XCOMMENT need to be escaped. - - This option has an effect with most languages, namely C, C++, - ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, - Tcl, Perl, PHP, GCC-source, Glade. - - The default keyword specifications, which are always looked for if - not explicitly disabled, are language dependent. They are: - - * For C, C++, and GCC-source: `gettext', `dgettext:2', - `dcgettext:2', `ngettext:1,2', `dngettext:2,3', - `dcngettext:2,3', `gettext_noop', and `pgettext:1c,2', - `dpgettext:2c,3', `dcpgettext:2c,3', `npgettext:1c,2,3', - `dnpgettext:2c,3,4', `dcnpgettext:2c,3,4'. - - * For Objective C: Like for C, and also `NSLocalizedString', - `_', `NSLocalizedStaticString', `__'. - - * For Shell scripts: `gettext', `ngettext:1,2', `eval_gettext', - `eval_ngettext:1,2'. - - * For Python: `gettext', `ugettext', `dgettext:2', - `ngettext:1,2', `ungettext:1,2', `dngettext:2,3', `_'. - - * For Lisp: `gettext', `ngettext:1,2', `gettext-noop'. - - * For EmacsLisp: `_'. - - * For librep: `_'. - - * For Scheme: `gettext', `ngettext:1,2', `gettext-noop'. - - * For Java: `GettextResource.gettext:2', - `GettextResource.ngettext:2,3', - `GettextResource.pgettext:2c,3', - `GettextResource.npgettext:2c,3,4', `gettext', `ngettext:1,2', - `pgettext:1c,2', `npgettext:1c,2,3', `getString'. - - * For C#: `GetString', `GetPluralString:1,2', - `GetParticularString:1c,2', - `GetParticularPluralString:1c,2,3'. - - * For awk: `dcgettext', `dcngettext:1,2'. - - * For Tcl: `::msgcat::mc'. - - * For Perl: `gettext', `%gettext', `$gettext', `dgettext:2', - `dcgettext:2', `ngettext:1,2', `dngettext:2,3', - `dcngettext:2,3', `gettext_noop'. - - * For PHP: `_', `gettext', `dgettext:2', `dcgettext:2', - `ngettext:1,2', `dngettext:2,3', `dcngettext:2,3'. - - * For Glade 1: `label', `title', `text', `format', `copyright', - `comments', `preview_text', `tooltip'. - - To disable the default keyword specifications, the option `-k' or - `--keyword' or `--keyword=', without a KEYWORDSPEC, can be used. - -`--flag=WORD:ARG:FLAG' - Specifies additional flags for strings occurring as part of the - ARGth argument of the function WORD. The possible flags are the - possible format string indicators, such as `c-format', and their - negations, such as `no-c-format', possibly prefixed with `pass-'. - The meaning of `--flag=FUNCTION:ARG:LANG-format' is that in - language LANG, the specified FUNCTION expects as ARGth argument a - format string. (For those of you familiar with GCC function - attributes, `--flag=FUNCTION:ARG:c-format' is roughly equivalent - to the declaration `__attribute__ ((__format__ (__printf__, ARG, - ...)))' attached to FUNCTION in a C source file.) For example, if - you use the `error' function from GNU libc, you can specify its - behaviour through `--flag=error:3:c-format'. The effect of this - specification is that `xgettext' will mark as format strings all - `gettext' invocations that occur as ARGth argument of FUNCTION. - This is useful when such strings contain no format string - directives: together with the checks done by `msgfmt -c' it will - ensure that translators cannot accidentally use format string - directives that would lead to a crash at runtime. - The meaning of `--flag=FUNCTION:ARG:pass-LANG-format' is that in - language LANG, if the FUNCTION call occurs in a position that must - yield a format string, then its ARGth argument must yield a format - string of the same type as well. (If you know GCC function - attributes, the `--flag=FUNCTION:ARG:pass-c-format' option is - roughly equivalent to the declaration `__attribute__ - ((__format_arg__ (ARG)))' attached to FUNCTION in a C source file.) - For example, if you use the `_' shortcut for the `gettext' - function, you should use `--flag=_:1:pass-c-format'. The effect - of this specification is that `xgettext' will propagate a format - string requirement for a `_("string")' call to its first argument, - the literal `"string"', and thus mark it as a format string. This - is useful when such strings contain no format string directives: - together with the checks done by `msgfmt -c' it will ensure that - translators cannot accidentally use format string directives that - would lead to a crash at runtime. - This option has an effect with most languages, namely C, C++, - ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, - C#, awk, YCP, Tcl, Perl, PHP, GCC-source. - -`-T' -`--trigraphs' - Understand ANSI C trigraphs for input. - This option has an effect only with the languages C, C++, - ObjectiveC. - -`--qt' - Recognize Qt format strings. - This option has an effect only with the language C++. - -`--kde' - Recognize KDE 4 format strings. - This option has an effect only with the language C++. - -`--boost' - Recognize Boost format strings. - This option has an effect only with the language C++. - -`--debug' - Use the flags `c-format' and `possible-c-format' to show who was - responsible for marking a message as a format string. The latter - form is used if the `xgettext' program decided, the format form is - used if the programmer prescribed it. - - By default only the `c-format' form is used. The translator should - not have to care about these details. - - - This implementation of `xgettext' is able to process a few awkward -cases, like strings in preprocessor macros, ANSI concatenation of -adjacent strings, and escaped end of lines for continued strings. - -5.1.7 Output details --------------------- - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`--force-po' - Always write an output file even if no message is defined. - -`-i' -`--indent' - Write the .po file using indented style. - -`--no-location' - Do not write `#: FILENAME:LINE' lines. Note that using this - option makes it harder for technically skilled translators to - understand each message's context. - -`-n' -`--add-location' - Generate `#: FILENAME:LINE' lines (default). - -`--strict' - Write out a strict Uniforum conforming PO file. Note that this - Uniforum format should be avoided because it doesn't support the - GNU extensions. - -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - -`-s' -`--sort-output' - Generate sorted output. Note that using this option makes it much - harder for the translator to understand each message's context. - -`-F' -`--sort-by-file' - Sort output by file location. - -`--omit-header' - Don't write header with `msgid ""' entry. - - This is useful for testing purposes because it eliminates a source - of variance for generated `.gmo' files. With `--omit-header', two - invocations of `xgettext' on the same files with the same options - at different times are guaranteed to produce the same results. - - Note that using this option will lead to an error if the resulting - file would not entirely be in ASCII. - -`--copyright-holder=STRING' - Set the copyright holder in the output. STRING should be the - copyright holder of the surrounding package. (Note that the msgstr - strings, extracted from the package's sources, belong to the - copyright holder of the package.) Translators are expected to - transfer or disclaim the copyright for their translations, so that - package maintainers can distribute them without legal risk. If - STRING is empty, the output files are marked as being in the - public domain; in this case, the translators are expected to - disclaim their copyright, again so that package maintainers can - distribute them without legal risk. - - The default value for STRING is the Free Software Foundation, Inc., - simply because `xgettext' was first used in the GNU project. - -`--foreign-user' - Omit FSF copyright in output. This option is equivalent to - `--copyright-holder='''. It can be useful for packages outside - the GNU project that want their translations to be in the public - domain. - -`--package-name=PACKAGE' - Set the package name in the header of the output. - -`--package-version=VERSION' - Set the package version in the header of the output. This option - has an effect only if the `--package-name' option is also used. - -`--msgid-bugs-address=EMAIL@ADDRESS' - Set the reporting address for msgid bugs. This is the email - address or URL to which the translators shall report bugs in the - untranslated strings: - - - Strings which are not entire sentences, see the maintainer - guidelines in *note Preparing Strings::. - - - Strings which use unclear terms or require additional context - to be understood. - - - Strings which make invalid assumptions about notation of - date, time or money. - - - Pluralisation problems. - - - Incorrect English spelling. - - - Incorrect formatting. - - It can be your email address, or a mailing list address where - translators can write to without being subscribed, or the URL of a - web page through which the translators can contact you. - - The default value is empty, which means that translators will be - clueless! Don't forget to specify this option. - -`-m[STRING]' -`--msgstr-prefix[=STRING]' - Use STRING (or "" if not specified) as prefix for msgstr values. - -`-M[STRING]' -`--msgstr-suffix[=STRING]' - Use STRING (or "" if not specified) as suffix for msgstr values. - - -5.1.8 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - - -File: gettext.info, Node: Creating, Next: Updating, Prev: Template, Up: Top - -6 Creating a New PO File -************************ - - When starting a new translation, the translator creates a file called -`LANG.po', as a copy of the `PACKAGE.pot' template file with -modifications in the initial comments (at the beginning of the file) -and in the header entry (the first entry, near the beginning of the -file). - - The easiest way to do so is by use of the `msginit' program. For -example: - - $ cd PACKAGE-VERSION - $ cd po - $ msginit - - The alternative way is to do the copy and modifications by hand. To -do so, the translator copies `PACKAGE.pot' to `LANG.po'. Then she -modifies the initial comments and the header entry of this file. - -* Menu: - -* msginit Invocation:: Invoking the `msginit' Program -* Header Entry:: Filling in the Header Entry - - -File: gettext.info, Node: msginit Invocation, Next: Header Entry, Prev: Creating, Up: Creating - -6.1 Invoking the `msginit' Program -================================== - - msginit [OPTION] - - The `msginit' program creates a new PO file, initializing the meta -information with values from the user's environment. - -6.1.1 Input file location -------------------------- - -`-i INPUTFILE' -`--input=INPUTFILE' - Input POT file. - - - If no INPUTFILE is given, the current directory is searched for the -POT file. If it is `-', standard input is read. - -6.1.2 Output file location --------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified PO file. - - - If no output file is given, it depends on the `--locale' option or -the user's locale setting. If it is `-', the results are written to -standard output. - -6.1.3 Input file syntax ------------------------ - -`-P' -`--properties-input' - Assume the input file is a Java ResourceBundle in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input file is a NeXTstep/GNUstep localized resource - file in `.strings' syntax, not in PO file syntax. - - -6.1.4 Output details --------------------- - -`-l LL_CC' -`--locale=LL_CC' - Set target locale. LL should be a language code, and CC should be - a country code. The command `locale -a' can be used to output a - list of all installed locales. The default is the user's locale - setting. - -`--no-translator' - Declares that the PO file will not have a human translator and is - instead automatically generated. - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`-p' -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - - -6.1.5 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - - -File: gettext.info, Node: Header Entry, Prev: msginit Invocation, Up: Creating - -6.2 Filling in the Header Entry -=============================== - - The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and "FIRST -AUTHOR <EMAIL@ADDRESS>, YEAR" ought to be replaced by sensible -information. This can be done in any text editor; if Emacs is used and -it switched to PO mode automatically (because it has recognized the -file's suffix), you can disable it by typing `M-x fundamental-mode'. - - Modifying the header entry can already be done using PO mode: in -Emacs, type `M-x po-mode RET' and then `RET' again to start editing the -entry. You should fill in the following fields. - -Project-Id-Version - This is the name and version of the package. Fill it in if it has - not already been filled in by `xgettext'. - -Report-Msgid-Bugs-To - This has already been filled in by `xgettext'. It contains an - email address or URL where you can report bugs in the untranslated - strings: - - - Strings which are not entire sentences, see the maintainer - guidelines in *note Preparing Strings::. - - - Strings which use unclear terms or require additional context - to be understood. - - - Strings which make invalid assumptions about notation of - date, time or money. - - - Pluralisation problems. - - - Incorrect English spelling. - - - Incorrect formatting. - -POT-Creation-Date - This has already been filled in by `xgettext'. - -PO-Revision-Date - You don't need to fill this in. It will be filled by the PO file - editor when you save the file. - -Last-Translator - Fill in your name and email address (without double quotes). - -Language-Team - Fill in the English name of the language, and the email address or - homepage URL of the language team you are part of. - - Before starting a translation, it is a good idea to get in touch - with your translation team, not only to make sure you don't do - duplicated work, but also to coordinate difficult linguistic - issues. - - In the Free Translation Project, each translation team has its own - mailing list. The up-to-date list of teams can be found at the - Free Translation Project's homepage, - `http://translationproject.org/', in the "Teams" area. - -Language - Fill in the language code of the language. This can be in one of - three forms: - - - `LL', an ISO 639 two-letter language code (lowercase). See - *note Language Codes:: for the list of codes. - - - `LL_CC', where `LL' is an ISO 639 two-letter language code - (lowercase) and `CC' is an ISO 3166 two-letter country code - (uppercase). The country code specification is not redundant: - Some languages have dialects in different countries. For - example, `de_AT' is used for Austria, and `pt_BR' for Brazil. - The country code serves to distinguish the dialects. See - *note Language Codes:: and *note Country Codes:: for the - lists of codes. - - - `LL_CC@VARIANT', where `LL' is an ISO 639 two-letter language - code (lowercase), `CC' is an ISO 3166 two-letter country code - (uppercase), and `VARIANT' is a variant designator. The - variant designator (lowercase) can be a script designator, - such as `latin' or `cyrillic'. - - The naming convention `LL_CC' is also the way locales are named on - systems based on GNU libc. But there are three important - differences: - - * In this PO file field, but not in locale names, `LL_CC' - combinations denoting a language's main dialect are - abbreviated as `LL'. For example, `de' is equivalent to - `de_DE' (German as spoken in Germany), and `pt' to `pt_PT' - (Portuguese as spoken in Portugal) in this context. - - * In this PO file field, suffixes like `.ENCODING' are not used. - - * In this PO file field, variant designators that are not - relevant to message translation, such as `@euro', are not - used. - - So, if your locale name is `de_DE.UTF-8', the language - specification in PO files is just `de'. - -Content-Type - Replace `CHARSET' with the character encoding used for your - language, in your locale, or UTF-8. This field is needed for - correct operation of the `msgmerge' and `msgfmt' programs, as well - as for users whose locale's character encoding differs from yours - (see *note Charset conversion::). - - You get the character encoding of your locale by running the shell - command `locale charmap'. If the result is `C' or - `ANSI_X3.4-1968', which is equivalent to `ASCII' (= `US-ASCII'), - it means that your locale is not correctly configured. In this - case, ask your translation team which charset to use. `ASCII' is - not usable for any language except Latin. - - Because the PO files must be portable to operating systems with - less advanced internationalization facilities, the character - encodings that can be used are limited to those supported by both - GNU `libc' and GNU `libiconv'. These are: `ASCII', `ISO-8859-1', - `ISO-8859-2', `ISO-8859-3', `ISO-8859-4', `ISO-8859-5', - `ISO-8859-6', `ISO-8859-7', `ISO-8859-8', `ISO-8859-9', - `ISO-8859-13', `ISO-8859-14', `ISO-8859-15', `KOI8-R', `KOI8-U', - `KOI8-T', `CP850', `CP866', `CP874', `CP932', `CP949', `CP950', - `CP1250', `CP1251', `CP1252', `CP1253', `CP1254', `CP1255', - `CP1256', `CP1257', `GB2312', `EUC-JP', `EUC-KR', `EUC-TW', - `BIG5', `BIG5-HKSCS', `GBK', `GB18030', `SHIFT_JIS', `JOHAB', - `TIS-620', `VISCII', `GEORGIAN-PS', `UTF-8'. - - In the GNU system, the following encodings are frequently used for - the corresponding languages. - - * `ISO-8859-1' for Afrikaans, Albanian, Basque, Breton, - Catalan, Cornish, Danish, Dutch, English, Estonian, Faroese, - Finnish, French, Galician, German, Greenlandic, Icelandic, - Indonesian, Irish, Italian, Malay, Manx, Norwegian, Occitan, - Portuguese, Spanish, Swedish, Tagalog, Uzbek, Walloon, - - * `ISO-8859-2' for Bosnian, Croatian, Czech, Hungarian, Polish, - Romanian, Serbian, Slovak, Slovenian, - - * `ISO-8859-3' for Maltese, - - * `ISO-8859-5' for Macedonian, Serbian, - - * `ISO-8859-6' for Arabic, - - * `ISO-8859-7' for Greek, - - * `ISO-8859-8' for Hebrew, - - * `ISO-8859-9' for Turkish, - - * `ISO-8859-13' for Latvian, Lithuanian, Maori, - - * `ISO-8859-14' for Welsh, - - * `ISO-8859-15' for Basque, Catalan, Dutch, English, Finnish, - French, Galician, German, Irish, Italian, Portuguese, - Spanish, Swedish, Walloon, - - * `KOI8-R' for Russian, - - * `KOI8-U' for Ukrainian, - - * `KOI8-T' for Tajik, - - * `CP1251' for Bulgarian, Belarusian, - - * `GB2312', `GBK', `GB18030' for simplified writing of Chinese, - - * `BIG5', `BIG5-HKSCS' for traditional writing of Chinese, - - * `EUC-JP' for Japanese, - - * `EUC-KR' for Korean, - - * `TIS-620' for Thai, - - * `GEORGIAN-PS' for Georgian, - - * `UTF-8' for any language, including those listed above. - - When single quote characters or double quote characters are used in - translations for your language, and your locale's encoding is one - of the ISO-8859-* charsets, it is best if you create your PO files - in UTF-8 encoding, instead of your locale's encoding. This is - because in UTF-8 the real quote characters can be represented - (single quote characters: U+2018, U+2019, double quote characters: - U+201C, U+201D), whereas none of ISO-8859-* charsets has them all. - Users in UTF-8 locales will see the real quote characters, whereas - users in ISO-8859-* locales will see the vertical apostrophe and - the vertical double quote instead (because that's what the - character set conversion will transliterate them to). - - To enter such quote characters under X11, you can change your - keyboard mapping using the `xmodmap' program. The X11 names of - the quote characters are "leftsinglequotemark", - "rightsinglequotemark", "leftdoublequotemark", - "rightdoublequotemark", "singlelowquotemark", "doublelowquotemark". - - Note that only recent versions of GNU Emacs support the UTF-8 - encoding: Emacs 20 with Mule-UCS, and Emacs 21. As of January - 2001, XEmacs doesn't support the UTF-8 encoding. - - The character encoding name can be written in either upper or - lower case. Usually upper case is preferred. - -Content-Transfer-Encoding - Set this to `8bit'. - -Plural-Forms - This field is optional. It is only needed if the PO file has - plural forms. You can find them by searching for the - `msgid_plural' keyword. The format of the plural forms field is - described in *note Plural forms:: and *note Translating plural - forms::. - - -File: gettext.info, Node: Updating, Next: Editing, Prev: Creating, Up: Top - -7 Updating Existing PO Files -**************************** - -* Menu: - -* msgmerge Invocation:: Invoking the `msgmerge' Program - - -File: gettext.info, Node: msgmerge Invocation, Prev: Updating, Up: Updating - -7.1 Invoking the `msgmerge' Program -=================================== - - msgmerge [OPTION] DEF.po REF.pot - - The `msgmerge' program merges two Uniforum style .po files together. -The DEF.po file is an existing PO file with translations which will be -taken over to the newly created file as long as they still match; -comments will be preserved, but extracted comments and file positions -will be discarded. The REF.pot file is the last created PO file with -up-to-date source references but old translations, or a PO Template file -(generally created by `xgettext'); any translations or comments in the -file will be discarded, however dot comments and file positions will be -preserved. Where an exact match cannot be found, fuzzy matching is -used to produce better results. - -7.1.1 Input file location -------------------------- - -`DEF.po' - Translations referring to old sources. - -`REF.pot' - References to the new sources. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - -`-C FILE' -`--compendium=FILE' - Specify an additional library of message translations. *Note - Compendium::. This option may be specified more than once. - - -7.1.2 Operation mode --------------------- - -`-U' -`--update' - Update DEF.po. Do nothing if DEF.po is already up to date. - - -7.1.3 Output file location --------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified file. - - - The results are written to standard output if no output file is -specified or if it is `-'. - -7.1.4 Output file location in update mode ------------------------------------------ - - The result is written back to DEF.po. - -`--backup=CONTROL' - Make a backup of DEF.po - -`--suffix=SUFFIX' - Override the usual backup suffix. - - - The version control method may be selected via the `--backup' option -or through the `VERSION_CONTROL' environment variable. Here are the -values: - -`none' -`off' - Never make backups (even if `--backup' is given). - -`numbered' -`t' - Make numbered backups. - -`existing' -`nil' - Make numbered backups if numbered backups for this file already - exist, otherwise make simple backups. - -`simple' -`never' - Always make simple backups. - - - The backup suffix is `~', unless set with `--suffix' or the -`SIMPLE_BACKUP_SUFFIX' environment variable. - -7.1.5 Operation modifiers -------------------------- - -`-m' -`--multi-domain' - Apply REF.pot to each of the domains in DEF.po. - -`-N' -`--no-fuzzy-matching' - Do not use fuzzy matching when an exact match is not found. This - may speed up the operation considerably. - -`--previous' - Keep the previous msgids of translated messages, marked with `#|', - when adding the fuzzy marker to such messages. - -7.1.6 Input file syntax ------------------------ - -`-P' -`--properties-input' - Assume the input files are Java ResourceBundles in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input files are NeXTstep/GNUstep localized resource - files in `.strings' syntax, not in PO file syntax. - - -7.1.7 Output details --------------------- - -`--lang=CATALOGNAME' - Specify the `Language' field to be used in the header entry. See - *note Header Entry:: for the meaning of this field. Note: The - `Language-Team' and `Plural-Forms' fields are left unchanged. If - this option is not specified, the `Language' field is inferred, as - best as possible, from the `Language-Team' field. - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`--force-po' - Always write an output file even if it contains no message. - -`-i' -`--indent' - Write the .po file using indented style. - -`--no-location' - Do not write `#: FILENAME:LINE' lines. - -`--add-location' - Generate `#: FILENAME:LINE' lines (default). - -`--strict' - Write out a strict Uniforum conforming PO file. Note that this - Uniforum format should be avoided because it doesn't support the - GNU extensions. - -`-p' -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - -`-s' -`--sort-output' - Generate sorted output. Note that using this option makes it much - harder for the translator to understand each message's context. - -`-F' -`--sort-by-file' - Sort output by file location. - - -7.1.8 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - -`-v' -`--verbose' - Increase verbosity level. - -`-q' -`--quiet' -`--silent' - Suppress progress indicators. - - - -File: gettext.info, Node: Editing, Next: Manipulating, Prev: Updating, Up: Top - -8 Editing PO Files -****************** - -* Menu: - -* KBabel:: KDE's PO File Editor -* Gtranslator:: GNOME's PO File Editor -* PO Mode:: Emacs's PO File Editor -* Compendium:: Using Translation Compendia - - -File: gettext.info, Node: KBabel, Next: Gtranslator, Prev: Editing, Up: Editing - -8.1 KDE's PO File Editor -======================== - - -File: gettext.info, Node: Gtranslator, Next: PO Mode, Prev: KBabel, Up: Editing - -8.2 GNOME's PO File Editor -========================== - - -File: gettext.info, Node: PO Mode, Next: Compendium, Prev: Gtranslator, Up: Editing - -8.3 Emacs's PO File Editor -========================== - - For those of you being the lucky users of Emacs, PO mode has been -specifically created for providing a cozy environment for editing or -modifying PO files. While editing a PO file, PO mode allows for the -easy browsing of auxiliary and compendium PO files, as well as for -following references into the set of C program sources from which PO -files have been derived. It has a few special features, among which -are the interactive marking of program strings as translatable, and the -validation of PO files with easy repositioning to PO file lines showing -errors. - - For the beginning, besides main PO mode commands (*note Main PO -Commands::), you should know how to move between entries (*note Entry -Positioning::), and how to handle untranslated entries (*note -Untranslated Entries::). - -* Menu: - -* Installation:: Completing GNU `gettext' Installation -* Main PO Commands:: Main Commands -* Entry Positioning:: Entry Positioning -* Normalizing:: Normalizing Strings in Entries -* Translated Entries:: Translated Entries -* Fuzzy Entries:: Fuzzy Entries -* Untranslated Entries:: Untranslated Entries -* Obsolete Entries:: Obsolete Entries -* Modifying Translations:: Modifying Translations -* Modifying Comments:: Modifying Comments -* Subedit:: Mode for Editing Translations -* C Sources Context:: C Sources Context -* Auxiliary:: Consulting Auxiliary PO Files - - -File: gettext.info, Node: Installation, Next: Main PO Commands, Prev: PO Mode, Up: PO Mode - -8.3.1 Completing GNU `gettext' Installation -------------------------------------------- - - Once you have received, unpacked, configured and compiled the GNU -`gettext' distribution, the `make install' command puts in place the -programs `xgettext', `msgfmt', `gettext', and `msgmerge', as well as -their available message catalogs. To top off a comfortable -installation, you might also want to make the PO mode available to your -Emacs users. - - During the installation of the PO mode, you might want to modify your -file `.emacs', once and for all, so it contains a few lines looking -like: - - (setq auto-mode-alist - (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist)) - (autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t) - - Later, whenever you edit some `.po' file, or any file having the -string `.po.' within its name, Emacs loads `po-mode.elc' (or -`po-mode.el') as needed, and automatically activates PO mode commands -for the associated buffer. The string _PO_ appears in the mode line -for any buffer for which PO mode is active. Many PO files may be -active at once in a single Emacs session. - - If you are using Emacs version 20 or newer, and have already -installed the appropriate international fonts on your system, you may -also tell Emacs how to determine automatically the coding system of -every PO file. This will often (but not always) cause the necessary -fonts to be loaded and used for displaying the translations on your -Emacs screen. For this to happen, add the lines: - - (modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\." - 'po-find-file-coding-system) - (autoload 'po-find-file-coding-system "po-mode") - -to your `.emacs' file. If, with this, you still see boxes instead of -international characters, try a different font set (via Shift Mouse -button 1). - - -File: gettext.info, Node: Main PO Commands, Next: Entry Positioning, Prev: Installation, Up: PO Mode - -8.3.2 Main PO mode Commands ---------------------------- - - After setting up Emacs with something similar to the lines in *note -Installation::, PO mode is activated for a window when Emacs finds a PO -file in that window. This puts the window read-only and establishes a -po-mode-map, which is a genuine Emacs mode, in a way that is not derived -from text mode in any way. Functions found on `po-mode-hook', if any, -will be executed. - - When PO mode is active in a window, the letters `PO' appear in the -mode line for that window. The mode line also displays how many -entries of each kind are held in the PO file. For example, the string -`132t+3f+10u+2o' would tell the translator that the PO mode contains -132 translated entries (*note Translated Entries::, 3 fuzzy entries -(*note Fuzzy Entries::), 10 untranslated entries (*note Untranslated -Entries::) and 2 obsolete entries (*note Obsolete Entries::). -Zero-coefficients items are not shown. So, in this example, if the -fuzzy entries were unfuzzied, the untranslated entries were translated -and the obsolete entries were deleted, the mode line would merely -display `145t' for the counters. - - The main PO commands are those which do not fit into the other -categories of subsequent sections. These allow for quitting PO mode or -for managing windows in special ways. - -`_' - Undo last modification to the PO file (`po-undo'). - -`Q' - Quit processing and save the PO file (`po-quit'). - -`q' - Quit processing, possibly after confirmation - (`po-confirm-and-quit'). - -`0' - Temporary leave the PO file window (`po-other-window'). - -`?' -`h' - Show help about PO mode (`po-help'). - -`=' - Give some PO file statistics (`po-statistics'). - -`V' - Batch validate the format of the whole PO file (`po-validate'). - - - The command `_' (`po-undo') interfaces to the Emacs _undo_ facility. -*Note Undoing Changes: (emacs)Undo. Each time `_' is typed, -modifications which the translator did to the PO file are undone a -little more. For the purpose of undoing, each PO mode command is -atomic. This is especially true for the `<RET>' command: the whole -edition made by using a single use of this command is undone at once, -even if the edition itself implied several actions. However, while in -the editing window, one can undo the edition work quite parsimoniously. - - The commands `Q' (`po-quit') and `q' (`po-confirm-and-quit') are -used when the translator is done with the PO file. The former is a bit -less verbose than the latter. If the file has been modified, it is -saved to disk first. In both cases, and prior to all this, the -commands check if any untranslated messages remain in the PO file and, -if so, the translator is asked if she really wants to leave off working -with this PO file. This is the preferred way of getting rid of an -Emacs PO file buffer. Merely killing it through the usual command -`C-x k' (`kill-buffer') is not the tidiest way to proceed. - - The command `0' (`po-other-window') is another, softer way, to leave -PO mode, temporarily. It just moves the cursor to some other Emacs -window, and pops one if necessary. For example, if the translator just -got PO mode to show some source context in some other, she might -discover some apparent bug in the program source that needs correction. -This command allows the translator to change sex, become a programmer, -and have the cursor right into the window containing the program she -(or rather _he_) wants to modify. By later getting the cursor back in -the PO file window, or by asking Emacs to edit this file once again, PO -mode is then recovered. - - The command `h' (`po-help') displays a summary of all available PO -mode commands. The translator should then type any character to resume -normal PO mode operations. The command `?' has the same effect as `h'. - - The command `=' (`po-statistics') computes the total number of -entries in the PO file, the ordinal of the current entry (counted from -1), the number of untranslated entries, the number of obsolete entries, -and displays all these numbers. - - The command `V' (`po-validate') launches `msgfmt' in checking and -verbose mode over the current PO file. This command first offers to -save the current PO file on disk. The `msgfmt' tool, from GNU -`gettext', has the purpose of creating a MO file out of a PO file, and -PO mode uses the features of this program for checking the overall -format of a PO file, as well as all individual entries. - - The program `msgfmt' runs asynchronously with Emacs, so the -translator regains control immediately while her PO file is being -studied. Error output is collected in the Emacs `*compilation*' buffer, -displayed in another window. The regular Emacs command `C-x`' -(`next-error'), as well as other usual compile commands, allow the -translator to reposition quickly to the offending parts of the PO file. -Once the cursor is on the line in error, the translator may decide on -any PO mode action which would help correcting the error. - - -File: gettext.info, Node: Entry Positioning, Next: Normalizing, Prev: Main PO Commands, Up: PO Mode - -8.3.3 Entry Positioning ------------------------ - - The cursor in a PO file window is almost always part of an entry. -The only exceptions are the special case when the cursor is after the -last entry in the file, or when the PO file is empty. The entry where -the cursor is found to be is said to be the current entry. Many PO -mode commands operate on the current entry, so moving the cursor does -more than allowing the translator to browse the PO file, this also -selects on which entry commands operate. - - Some PO mode commands alter the position of the cursor in a -specialized way. A few of those special purpose positioning are -described here, the others are described in following sections (for a -complete list try `C-h m'): - -`.' - Redisplay the current entry (`po-current-entry'). - -`n' - Select the entry after the current one (`po-next-entry'). - -`p' - Select the entry before the current one (`po-previous-entry'). - -`<' - Select the first entry in the PO file (`po-first-entry'). - -`>' - Select the last entry in the PO file (`po-last-entry'). - -`m' - Record the location of the current entry for later use - (`po-push-location'). - -`r' - Return to a previously saved entry location (`po-pop-location'). - -`x' - Exchange the current entry location with the previously saved one - (`po-exchange-location'). - - - Any Emacs command able to reposition the cursor may be used to -select the current entry in PO mode, including commands which move by -characters, lines, paragraphs, screens or pages, and search commands. -However, there is a kind of standard way to display the current entry -in PO mode, which usual Emacs commands moving the cursor do not -especially try to enforce. The command `.' (`po-current-entry') has -the sole purpose of redisplaying the current entry properly, after the -current entry has been changed by means external to PO mode, or the -Emacs screen otherwise altered. - - It is yet to be decided if PO mode helps the translator, or otherwise -irritates her, by forcing a rigid window disposition while she is doing -her work. We originally had quite precise ideas about how windows -should behave, but on the other hand, anyone used to Emacs is often -happy to keep full control. Maybe a fixed window disposition might be -offered as a PO mode option that the translator might activate or -deactivate at will, so it could be offered on an experimental basis. -If nobody feels a real need for using it, or a compulsion for writing -it, we should drop this whole idea. The incentive for doing it should -come from translators rather than programmers, as opinions from an -experienced translator are surely more worth to me than opinions from -programmers _thinking_ about how _others_ should do translation. - - The commands `n' (`po-next-entry') and `p' (`po-previous-entry') -move the cursor the entry following, or preceding, the current one. If -`n' is given while the cursor is on the last entry of the PO file, or -if `p' is given while the cursor is on the first entry, no move is done. - - The commands `<' (`po-first-entry') and `>' (`po-last-entry') move -the cursor to the first entry, or last entry, of the PO file. When the -cursor is located past the last entry in a PO file, most PO mode -commands will return an error saying `After last entry'. Moreover, the -commands `<' and `>' have the special property of being able to work -even when the cursor is not into some PO file entry, and one may use -them for nicely correcting this situation. But even these commands -will fail on a truly empty PO file. There are development plans for -the PO mode for it to interactively fill an empty PO file from sources. -*Note Marking::. - - The translator may decide, before working at the translation of a -particular entry, that she needs to browse the remainder of the PO -file, maybe for finding the terminology or phraseology used in related -entries. She can of course use the standard Emacs idioms for saving -the current cursor location in some register, and use that register for -getting back, or else, use the location ring. - - PO mode offers another approach, by which cursor locations may be -saved onto a special stack. The command `m' (`po-push-location') -merely adds the location of current entry to the stack, pushing the -already saved locations under the new one. The command `r' -(`po-pop-location') consumes the top stack element and repositions the -cursor to the entry associated with that top element. This position is -then lost, for the next `r' will move the cursor to the previously -saved location, and so on until no locations remain on the stack. - - If the translator wants the position to be kept on the location -stack, maybe for taking a look at the entry associated with the top -element, then go elsewhere with the intent of getting back later, she -ought to use `m' immediately after `r'. - - The command `x' (`po-exchange-location') simultaneously repositions -the cursor to the entry associated with the top element of the stack of -saved locations, and replaces that top element with the location of the -current entry before the move. Consequently, repeating the `x' command -toggles alternatively between two entries. For achieving this, the -translator will position the cursor on the first entry, use `m', then -position to the second entry, and merely use `x' for making the switch. - - -File: gettext.info, Node: Normalizing, Next: Translated Entries, Prev: Entry Positioning, Up: PO Mode - -8.3.4 Normalizing Strings in Entries ------------------------------------- - - There are many different ways for encoding a particular string into a -PO file entry, because there are so many different ways to split and -quote multi-line strings, and even, to represent special characters by -backslashed escaped sequences. Some features of PO mode rely on the -ability for PO mode to scan an already existing PO file for a -particular string encoded into the `msgid' field of some entry. Even -if PO mode has internally all the built-in machinery for implementing -this recognition easily, doing it fast is technically difficult. To -facilitate a solution to this efficiency problem, we decided on a -canonical representation for strings. - - A conventional representation of strings in a PO file is currently -under discussion, and PO mode experiments with a canonical -representation. Having both `xgettext' and PO mode converging towards -a uniform way of representing equivalent strings would be useful, as -the internal normalization needed by PO mode could be automatically -satisfied when using `xgettext' from GNU `gettext'. An explicit PO -mode normalization should then be only necessary for PO files imported -from elsewhere, or for when the convention itself evolves. - - So, for achieving normalization of at least the strings of a given -PO file needing a canonical representation, the following PO mode -command is available: - -`M-x po-normalize' - Tidy the whole PO file by making entries more uniform. - - - The special command `M-x po-normalize', which has no associated -keys, revises all entries, ensuring that strings of both original and -translated entries use uniform internal quoting in the PO file. It -also removes any crumb after the last entry. This command may be -useful for PO files freshly imported from elsewhere, or if we ever -improve on the canonical quoting format we use. This canonical format -is not only meant for getting cleaner PO files, but also for greatly -speeding up `msgid' string lookup for some other PO mode commands. - - `M-x po-normalize' presently makes three passes over the entries. -The first implements heuristics for converting PO files for GNU -`gettext' 0.6 and earlier, in which `msgid' and `msgstr' fields were -using K&R style C string syntax for multi-line strings. These -heuristics may fail for comments not related to obsolete entries and -ending with a backslash; they also depend on subsequent passes for -finalizing the proper commenting of continued lines for obsolete -entries. This first pass might disappear once all oldish PO files -would have been adjusted. The second and third pass normalize all -`msgid' and `msgstr' strings respectively. They also clean out those -trailing backslashes used by XView's `msgfmt' for continued lines. - - Having such an explicit normalizing command allows for importing PO -files from other sources, but also eases the evolution of the current -convention, evolution driven mostly by aesthetic concerns, as of now. -It is easy to make suggested adjustments at a later time, as the -normalizing command and eventually, other GNU `gettext' tools should -greatly automate conformance. A description of the canonical string -format is given below, for the particular benefit of those not having -Emacs handy, and who would nevertheless want to handcraft their PO -files in nice ways. - - Right now, in PO mode, strings are single line or multi-line. A -string goes multi-line if and only if it has _embedded_ newlines, that -is, if it matches `[^\n]\n+[^\n]'. So, we would have: - - msgstr "\n\nHello, world!\n\n\n" - - but, replacing the space by a newline, this becomes: - - msgstr "" - "\n" - "\n" - "Hello,\n" - "world!\n" - "\n" - "\n" - - We are deliberately using a caricatural example, here, to make the -point clearer. Usually, multi-lines are not that bad looking. It is -probable that we will implement the following suggestion. We might -lump together all initial newlines into the empty string, and also all -newlines introducing empty lines (that is, for N > 1, the N-1'th last -newlines would go together on a separate string), so making the -previous example appear: - - msgstr "\n\n" - "Hello,\n" - "world!\n" - "\n\n" - - There are a few yet undecided little points about string -normalization, to be documented in this manual, once these questions -settle. - - -File: gettext.info, Node: Translated Entries, Next: Fuzzy Entries, Prev: Normalizing, Up: PO Mode - -8.3.5 Translated Entries ------------------------- - - Each PO file entry for which the `msgstr' field has been filled with -a translation, and which is not marked as fuzzy (*note Fuzzy Entries::), -is said to be a "translated" entry. Only translated entries will later -be compiled by GNU `msgfmt' and become usable in programs. Other entry -types will be excluded; translation will not occur for them. - - Some commands are more specifically related to translated entry -processing. - -`t' - Find the next translated entry (`po-next-translated-entry'). - -`T' - Find the previous translated entry - (`po-previous-translated-entry'). - - - The commands `t' (`po-next-translated-entry') and `T' -(`po-previous-translated-entry') move forwards or backwards, chasing -for an translated entry. If none is found, the search is extended and -wraps around in the PO file buffer. - - Translated entries usually result from the translator having edited -in a translation for them, *note Modifying Translations::. However, if -the variable `po-auto-fuzzy-on-edit' is not `nil', the entry having -received a new translation first becomes a fuzzy entry, which ought to -be later unfuzzied before becoming an official, genuine translated -entry. *Note Fuzzy Entries::. - - -File: gettext.info, Node: Fuzzy Entries, Next: Untranslated Entries, Prev: Translated Entries, Up: PO Mode - -8.3.6 Fuzzy Entries -------------------- - - Each PO file entry may have a set of "attributes", which are -qualities given a name and explicitly associated with the translation, -using a special system comment. One of these attributes has the name -`fuzzy', and entries having this attribute are said to have a fuzzy -translation. They are called fuzzy entries, for short. - - Fuzzy entries, even if they account for translated entries for most -other purposes, usually call for revision by the translator. Those may -be produced by applying the program `msgmerge' to update an older -translated PO files according to a new PO template file, when this tool -hypothesises that some new `msgid' has been modified only slightly out -of an older one, and chooses to pair what it thinks to be the old -translation for the new modified entry. The slight alteration in the -original string (the `msgid' string) should often be reflected in the -translated string, and this requires the intervention of the -translator. For this reason, `msgmerge' might mark some entries as -being fuzzy. - - Also, the translator may decide herself to mark an entry as fuzzy -for her own convenience, when she wants to remember that the entry has -to be later revisited. So, some commands are more specifically related -to fuzzy entry processing. - -`f' - Find the next fuzzy entry (`po-next-fuzzy-entry'). - -`F' - Find the previous fuzzy entry (`po-previous-fuzzy-entry'). - -`<TAB>' - Remove the fuzzy attribute of the current entry (`po-unfuzzy'). - - - The commands `f' (`po-next-fuzzy-entry') and `F' -(`po-previous-fuzzy-entry') move forwards or backwards, chasing for a -fuzzy entry. If none is found, the search is extended and wraps around -in the PO file buffer. - - The command `<TAB>' (`po-unfuzzy') removes the fuzzy attribute -associated with an entry, usually leaving it translated. Further, if -the variable `po-auto-select-on-unfuzzy' has not the `nil' value, the -`<TAB>' command will automatically chase for another interesting entry -to work on. The initial value of `po-auto-select-on-unfuzzy' is `nil'. - - The initial value of `po-auto-fuzzy-on-edit' is `nil'. However, if -the variable `po-auto-fuzzy-on-edit' is set to `t', any entry edited -through the `<RET>' command is marked fuzzy, as a way to ensure some -kind of double check, later. In this case, the usual paradigm is that -an entry becomes fuzzy (if not already) whenever the translator -modifies it. If she is satisfied with the translation, she then uses -`<TAB>' to pick another entry to work on, clearing the fuzzy attribute -on the same blow. If she is not satisfied yet, she merely uses `<SPC>' -to chase another entry, leaving the entry fuzzy. - - The translator may also use the `<DEL>' command -(`po-fade-out-entry') over any translated entry to mark it as being -fuzzy, when she wants to easily leave a trace she wants to later return -working at this entry. - - Also, when time comes to quit working on a PO file buffer with the -`q' command, the translator is asked for confirmation, if fuzzy string -still exists. - - -File: gettext.info, Node: Untranslated Entries, Next: Obsolete Entries, Prev: Fuzzy Entries, Up: PO Mode - -8.3.7 Untranslated Entries --------------------------- - - When `xgettext' originally creates a PO file, unless told otherwise, -it initializes the `msgid' field with the untranslated string, and -leaves the `msgstr' string to be empty. Such entries, having an empty -translation, are said to be "untranslated" entries. Later, when the -programmer slightly modifies some string right in the program, this -change is later reflected in the PO file by the appearance of a new -untranslated entry for the modified string. - - The usual commands moving from entry to entry consider untranslated -entries on the same level as active entries. Untranslated entries are -easily recognizable by the fact they end with `msgstr ""'. - - The work of the translator might be (quite naively) seen as the -process of seeking for an untranslated entry, editing a translation for -it, and repeating these actions until no untranslated entries remain. -Some commands are more specifically related to untranslated entry -processing. - -`u' - Find the next untranslated entry (`po-next-untranslated-entry'). - -`U' - Find the previous untranslated entry - (`po-previous-untransted-entry'). - -`k' - Turn the current entry into an untranslated one (`po-kill-msgstr'). - - - The commands `u' (`po-next-untranslated-entry') and `U' -(`po-previous-untransted-entry') move forwards or backwards, chasing -for an untranslated entry. If none is found, the search is extended -and wraps around in the PO file buffer. - - An entry can be turned back into an untranslated entry by merely -emptying its translation, using the command `k' (`po-kill-msgstr'). -*Note Modifying Translations::. - - Also, when time comes to quit working on a PO file buffer with the -`q' command, the translator is asked for confirmation, if some -untranslated string still exists. - - -File: gettext.info, Node: Obsolete Entries, Next: Modifying Translations, Prev: Untranslated Entries, Up: PO Mode - -8.3.8 Obsolete Entries ----------------------- - - By "obsolete" PO file entries, we mean those entries which are -commented out, usually by `msgmerge' when it found that the translation -is not needed anymore by the package being localized. - - The usual commands moving from entry to entry consider obsolete -entries on the same level as active entries. Obsolete entries are -easily recognizable by the fact that all their lines start with `#', -even those lines containing `msgid' or `msgstr'. - - Commands exist for emptying the translation or reinitializing it to -the original untranslated string. Commands interfacing with the kill -ring may force some previously saved text into the translation. The -user may interactively edit the translation. All these commands may -apply to obsolete entries, carefully leaving the entry obsolete after -the fact. - - Moreover, some commands are more specifically related to obsolete -entry processing. - -`o' - Find the next obsolete entry (`po-next-obsolete-entry'). - -`O' - Find the previous obsolete entry (`po-previous-obsolete-entry'). - -`<DEL>' - Make an active entry obsolete, or zap out an obsolete entry - (`po-fade-out-entry'). - - - The commands `o' (`po-next-obsolete-entry') and `O' -(`po-previous-obsolete-entry') move forwards or backwards, chasing for -an obsolete entry. If none is found, the search is extended and wraps -around in the PO file buffer. - - PO mode does not provide ways for un-commenting an obsolete entry -and making it active, because this would reintroduce an original -untranslated string which does not correspond to any marked string in -the program sources. This goes with the philosophy of never -introducing useless `msgid' values. - - However, it is possible to comment out an active entry, so making it -obsolete. GNU `gettext' utilities will later react to the -disappearance of a translation by using the untranslated string. The -command `<DEL>' (`po-fade-out-entry') pushes the current entry a little -further towards annihilation. If the entry is active (it is a -translated entry), then it is first made fuzzy. If it is already fuzzy, -then the entry is merely commented out, with confirmation. If the entry -is already obsolete, then it is completely deleted from the PO file. -It is easy to recycle the translation so deleted into some other PO file -entry, usually one which is untranslated. *Note Modifying -Translations::. - - Here is a quite interesting problem to solve for later development of -PO mode, for those nights you are not sleepy. The idea would be that -PO mode might become bright enough, one of these days, to make good -guesses at retrieving the most probable candidate, among all obsolete -entries, for initializing the translation of a newly appeared string. -I think it might be a quite hard problem to do this algorithmically, as -we have to develop good and efficient measures of string similarity. -Right now, PO mode completely lets the decision to the translator, when -the time comes to find the adequate obsolete translation, it merely -tries to provide handy tools for helping her to do so. - - -File: gettext.info, Node: Modifying Translations, Next: Modifying Comments, Prev: Obsolete Entries, Up: PO Mode - -8.3.9 Modifying Translations ----------------------------- - - PO mode prevents direct modification of the PO file, by the usual -means Emacs gives for altering a buffer's contents. By doing so, it -pretends helping the translator to avoid little clerical errors about -the overall file format, or the proper quoting of strings, as those -errors would be easily made. Other kinds of errors are still possible, -but some may be caught and diagnosed by the batch validation process, -which the translator may always trigger by the `V' command. For all -other errors, the translator has to rely on her own judgment, and also -on the linguistic reports submitted to her by the users of the -translated package, having the same mother tongue. - - When the time comes to create a translation, correct an error -diagnosed mechanically or reported by a user, the translators have to -resort to using the following commands for modifying the translations. - -`<RET>' - Interactively edit the translation (`po-edit-msgstr'). - -`<LFD>' -`C-j' - Reinitialize the translation with the original, untranslated string - (`po-msgid-to-msgstr'). - -`k' - Save the translation on the kill ring, and delete it - (`po-kill-msgstr'). - -`w' - Save the translation on the kill ring, without deleting it - (`po-kill-ring-save-msgstr'). - -`y' - Replace the translation, taking the new from the kill ring - (`po-yank-msgstr'). - - - The command `<RET>' (`po-edit-msgstr') opens a new Emacs window -meant to edit in a new translation, or to modify an already existing -translation. The new window contains a copy of the translation taken -from the current PO file entry, all ready for edition, expunged of all -quoting marks, fully modifiable and with the complete extent of Emacs -modifying commands. When the translator is done with her -modifications, she may use `C-c C-c' to close the subedit window with -the automatically requoted results, or `C-c C-k' to abort her -modifications. *Note Subedit::, for more information. - - The command `<LFD>' (`po-msgid-to-msgstr') initializes, or -reinitializes the translation with the original string. This command is -normally used when the translator wants to redo a fresh translation of -the original string, disregarding any previous work. - - It is possible to arrange so, whenever editing an untranslated -entry, the `<LFD>' command be automatically executed. If you set -`po-auto-edit-with-msgid' to `t', the translation gets initialised with -the original string, in case none exists already. The default value -for `po-auto-edit-with-msgid' is `nil'. - - In fact, whether it is best to start a translation with an empty -string, or rather with a copy of the original string, is a matter of -taste or habit. Sometimes, the source language and the target language -are so different that is simply best to start writing on an empty page. -At other times, the source and target languages are so close that it -would be a waste to retype a number of words already being written in -the original string. A translator may also like having the original -string right under her eyes, as she will progressively overwrite the -original text with the translation, even if this requires some extra -editing work to get rid of the original. - - The command `k' (`po-kill-msgstr') merely empties the translation -string, so turning the entry into an untranslated one. But while doing -so, its previous contents is put apart in a special place, known as the -kill ring. The command `w' (`po-kill-ring-save-msgstr') has also the -effect of taking a copy of the translation onto the kill ring, but it -otherwise leaves the entry alone, and does _not_ remove the translation -from the entry. Both commands use exactly the Emacs kill ring, which -is shared between buffers, and which is well known already to Emacs -lovers. - - The translator may use `k' or `w' many times in the course of her -work, as the kill ring may hold several saved translations. From the -kill ring, strings may later be reinserted in various Emacs buffers. -In particular, the kill ring may be used for moving translation strings -between different entries of a single PO file buffer, or if the -translator is handling many such buffers at once, even between PO files. - - To facilitate exchanges with buffers which are not in PO mode, the -translation string put on the kill ring by the `k' command is fully -unquoted before being saved: external quotes are removed, multi-line -strings are concatenated, and backslash escaped sequences are turned -into their corresponding characters. In the special case of obsolete -entries, the translation is also uncommented prior to saving. - - The command `y' (`po-yank-msgstr') completely replaces the -translation of the current entry by a string taken from the kill ring. -Following Emacs terminology, we then say that the replacement string is -"yanked" into the PO file buffer. *Note Yanking: (emacs)Yanking. The -first time `y' is used, the translation receives the value of the most -recent addition to the kill ring. If `y' is typed once again, -immediately, without intervening keystrokes, the translation just -inserted is taken away and replaced by the second most recent addition -to the kill ring. By repeating `y' many times in a row, the translator -may travel along the kill ring for saved strings, until she finds the -string she really wanted. - - When a string is yanked into a PO file entry, it is fully and -automatically requoted for complying with the format PO files should -have. Further, if the entry is obsolete, PO mode then appropriately -push the inserted string inside comments. Once again, translators -should not burden themselves with quoting considerations besides, of -course, the necessity of the translated string itself respective to the -program using it. - - Note that `k' or `w' are not the only commands pushing strings on -the kill ring, as almost any PO mode command replacing translation -strings (or the translator comments) automatically saves the old string -on the kill ring. The main exceptions to this general rule are the -yanking commands themselves. - - To better illustrate the operation of killing and yanking, let's use -an actual example, taken from a common situation. When the programmer -slightly modifies some string right in the program, his change is later -reflected in the PO file by the appearance of a new untranslated entry -for the modified string, and the fact that the entry translating the -original or unmodified string becomes obsolete. In many cases, the -translator might spare herself some work by retrieving the unmodified -translation from the obsolete entry, then initializing the untranslated -entry `msgstr' field with this retrieved translation. Once this done, -the obsolete entry is not wanted anymore, and may be safely deleted. - - When the translator finds an untranslated entry and suspects that a -slight variant of the translation exists, she immediately uses `m' to -mark the current entry location, then starts chasing obsolete entries -with `o', hoping to find some translation corresponding to the -unmodified string. Once found, she uses the `<DEL>' command for -deleting the obsolete entry, knowing that `<DEL>' also _kills_ the -translation, that is, pushes the translation on the kill ring. Then, -`r' returns to the initial untranslated entry, and `y' then _yanks_ the -saved translation right into the `msgstr' field. The translator is -then free to use `<RET>' for fine tuning the translation contents, and -maybe to later use `u', then `m' again, for going on with the next -untranslated string. - - When some sequence of keys has to be typed over and over again, the -translator may find it useful to become better acquainted with the Emacs -capability of learning these sequences and playing them back under -request. *Note Keyboard Macros: (emacs)Keyboard Macros. - - -File: gettext.info, Node: Modifying Comments, Next: Subedit, Prev: Modifying Translations, Up: PO Mode - -8.3.10 Modifying Comments -------------------------- - - Any translation work done seriously will raise many linguistic -difficulties, for which decisions have to be made, and the choices -further documented. These documents may be saved within the PO file in -form of translator comments, which the translator is free to create, -delete, or modify at will. These comments may be useful to herself -when she returns to this PO file after a while. - - Comments not having whitespace after the initial `#', for example, -those beginning with `#.' or `#:', are _not_ translator comments, they -are exclusively created by other `gettext' tools. So, the commands -below will never alter such system added comments, they are not meant -for the translator to modify. *Note PO Files::. - - The following commands are somewhat similar to those modifying -translations, so the general indications given for those apply here. -*Note Modifying Translations::. - -`#' - Interactively edit the translator comments (`po-edit-comment'). - -`K' - Save the translator comments on the kill ring, and delete it - (`po-kill-comment'). - -`W' - Save the translator comments on the kill ring, without deleting it - (`po-kill-ring-save-comment'). - -`Y' - Replace the translator comments, taking the new from the kill ring - (`po-yank-comment'). - - - These commands parallel PO mode commands for modifying the -translation strings, and behave much the same way as they do, except -that they handle this part of PO file comments meant for translator -usage, rather than the translation strings. So, if the descriptions -given below are slightly succinct, it is because the full details have -already been given. *Note Modifying Translations::. - - The command `#' (`po-edit-comment') opens a new Emacs window -containing a copy of the translator comments on the current PO file -entry. If there are no such comments, PO mode understands that the -translator wants to add a comment to the entry, and she is presented -with an empty screen. Comment marks (`#') and the space following them -are automatically removed before edition, and reinstated after. For -translator comments pertaining to obsolete entries, the uncommenting -and recommenting operations are done twice. Once in the editing -window, the keys `C-c C-c' allow the translator to tell she is finished -with editing the comment. *Note Subedit::, for further details. - - Functions found on `po-subedit-mode-hook', if any, are executed after -the string has been inserted in the edit buffer. - - The command `K' (`po-kill-comment') gets rid of all translator -comments, while saving those comments on the kill ring. The command -`W' (`po-kill-ring-save-comment') takes a copy of the translator -comments on the kill ring, but leaves them undisturbed in the current -entry. The command `Y' (`po-yank-comment') completely replaces the -translator comments by a string taken at the front of the kill ring. -When this command is immediately repeated, the comments just inserted -are withdrawn, and replaced by other strings taken along the kill ring. - - On the kill ring, all strings have the same nature. There is no -distinction between _translation_ strings and _translator comments_ -strings. So, for example, let's presume the translator has just -finished editing a translation, and wants to create a new translator -comment to document why the previous translation was not good, just to -remember what was the problem. Foreseeing that she will do that in her -documentation, the translator may want to quote the previous -translation in her translator comments. To do so, she may initialize -the translator comments with the previous translation, still at the -head of the kill ring. Because editing already pushed the previous -translation on the kill ring, she merely has to type `M-w' prior to -`#', and the previous translation will be right there, all ready for -being introduced by some explanatory text. - - On the other hand, presume there are some translator comments already -and that the translator wants to add to those comments, instead of -wholly replacing them. Then, she should edit the comment right away -with `#'. Once inside the editing window, she can use the regular -Emacs commands `C-y' (`yank') and `M-y' (`yank-pop') to get the -previous translation where she likes. - - -File: gettext.info, Node: Subedit, Next: C Sources Context, Prev: Modifying Comments, Up: PO Mode - -8.3.11 Details of Sub Edition ------------------------------ - - The PO subedit minor mode has a few peculiarities worth being -described in fuller detail. It installs a few commands over the usual -editing set of Emacs, which are described below. - -`C-c C-c' - Complete edition (`po-subedit-exit'). - -`C-c C-k' - Abort edition (`po-subedit-abort'). - -`C-c C-a' - Consult auxiliary PO files (`po-subedit-cycle-auxiliary'). - - - The window's contents represents a translation for a given message, -or a translator comment. The translator may modify this window to her -heart's content. Once this is done, the command `C-c C-c' -(`po-subedit-exit') may be used to return the edited translation into -the PO file, replacing the original translation, even if it moved out of -sight or if buffers were switched. - - If the translator becomes unsatisfied with her translation or -comment, to the extent she prefers keeping what was existent prior to -the `<RET>' or `#' command, she may use the command `C-c C-k' -(`po-subedit-abort') to merely get rid of edition, while preserving the -original translation or comment. Another way would be for her to exit -normally with `C-c C-c', then type `U' once for undoing the whole -effect of last edition. - - The command `C-c C-a' (`po-subedit-cycle-auxiliary') allows for -glancing through translations already achieved in other languages, -directly while editing the current translation. This may be quite -convenient when the translator is fluent at many languages, but of -course, only makes sense when such completed auxiliary PO files are -already available to her (*note Auxiliary::). - - Functions found on `po-subedit-mode-hook', if any, are executed after -the string has been inserted in the edit buffer. - - While editing her translation, the translator should pay attention -to not inserting unwanted `<RET>' (newline) characters at the end of -the translated string if those are not meant to be there, or to removing -such characters when they are required. Since these characters are not -visible in the editing buffer, they are easily introduced by mistake. -To help her, `<RET>' automatically puts the character `<' at the end of -the string being edited, but this `<' is not really part of the string. -On exiting the editing window with `C-c C-c', PO mode automatically -removes such `<' and all whitespace added after it. If the translator -adds characters after the terminating `<', it looses its delimiting -property and integrally becomes part of the string. If she removes the -delimiting `<', then the edited string is taken _as is_, with all -trailing newlines, even if invisible. Also, if the translated string -ought to end itself with a genuine `<', then the delimiting `<' may not -be removed; so the string should appear, in the editing window, as -ending with two `<' in a row. - - When a translation (or a comment) is being edited, the translator -may move the cursor back into the PO file buffer and freely move to -other entries, browsing at will. If, with an edition pending, the -translator wanders in the PO file buffer, she may decide to start -modifying another entry. Each entry being edited has its own subedit -buffer. It is possible to simultaneously edit the translation _and_ -the comment of a single entry, or to edit entries in different PO -files, all at once. Typing `<RET>' on a field already being edited -merely resumes that particular edit. Yet, the translator should better -be comfortable at handling many Emacs windows! - - Pending subedits may be completed or aborted in any order, regardless -of how or when they were started. When many subedits are pending and -the translator asks for quitting the PO file (with the `q' command), -subedits are automatically resumed one at a time, so she may decide for -each of them. - - -File: gettext.info, Node: C Sources Context, Next: Auxiliary, Prev: Subedit, Up: PO Mode - -8.3.12 C Sources Context ------------------------- - - PO mode is particularly powerful when used with PO files created -through GNU `gettext' utilities, as those utilities insert special -comments in the PO files they generate. Some of these special comments -relate the PO file entry to exactly where the untranslated string -appears in the program sources. - - When the translator gets to an untranslated entry, she is fairly -often faced with an original string which is not as informative as it -normally should be, being succinct, cryptic, or otherwise ambiguous. -Before choosing how to translate the string, she needs to understand -better what the string really means and how tight the translation has -to be. Most of the time, when problems arise, the only way left to make -her judgment is looking at the true program sources from where this -string originated, searching for surrounding comments the programmer -might have put in there, and looking around for helping clues of _any_ -kind. - - Surely, when looking at program sources, the translator will receive -more help if she is a fluent programmer. However, even if she is not -versed in programming and feels a little lost in C code, the translator -should not be shy at taking a look, once in a while. It is most -probable that she will still be able to find some of the hints she -needs. She will learn quickly to not feel uncomfortable in program -code, paying more attention to programmer's comments, variable and -function names (if he dared choosing them well), and overall -organization, than to the program code itself. - - The following commands are meant to help the translator at getting -program source context for a PO file entry. - -`s' - Resume the display of a program source context, or cycle through - them (`po-cycle-source-reference'). - -`M-s' - Display of a program source context selected by menu - (`po-select-source-reference'). - -`S' - Add a directory to the search path for source files - (`po-consider-source-path'). - -`M-S' - Delete a directory from the search path for source files - (`po-ignore-source-path'). - - - The commands `s' (`po-cycle-source-reference') and `M-s' -(`po-select-source-reference') both open another window displaying some -source program file, and already positioned in such a way that it shows -an actual use of the string to be translated. By doing so, the command -gives source program context for the string. But if the entry has no -source context references, or if all references are unresolved along -the search path for program sources, then the command diagnoses this as -an error. - - Even if `s' (or `M-s') opens a new window, the cursor stays in the -PO file window. If the translator really wants to get into the program -source window, she ought to do it explicitly, maybe by using command -`O'. - - When `s' is typed for the first time, or for a PO file entry which -is different of the last one used for getting source context, then the -command reacts by giving the first context available for this entry, if -any. If some context has already been recently displayed for the -current PO file entry, and the translator wandered off to do other -things, typing `s' again will merely resume, in another window, the -context last displayed. In particular, if the translator moved the -cursor away from the context in the source file, the command will bring -the cursor back to the context. By using `s' many times in a row, with -no other commands intervening, PO mode will cycle to the next available -contexts for this particular entry, getting back to the first context -once the last has been shown. - - The command `M-s' behaves differently. Instead of cycling through -references, it lets the translator choose a particular reference among -many, and displays that reference. It is best used with completion, if -the translator types `<TAB>' immediately after `M-s', in response to -the question, she will be offered a menu of all possible references, as -a reminder of which are the acceptable answers. This command is useful -only where there are really many contexts available for a single string -to translate. - - Program source files are usually found relative to where the PO file -stands. As a special provision, when this fails, the file is also -looked for, but relative to the directory immediately above it. Those -two cases take proper care of most PO files. However, it might happen -that a PO file has been moved, or is edited in a different place than -its normal location. When this happens, the translator should tell PO -mode in which directory normally sits the genuine PO file. Many such -directories may be specified, and all together, they constitute what is -called the "search path" for program sources. The command `S' -(`po-consider-source-path') is used to interactively enter a new -directory at the front of the search path, and the command `M-S' -(`po-ignore-source-path') is used to select, with completion, one of -the directories she does not want anymore on the search path. - - -File: gettext.info, Node: Auxiliary, Prev: C Sources Context, Up: PO Mode - -8.3.13 Consulting Auxiliary PO Files ------------------------------------- - - PO mode is able to help the knowledgeable translator, being fluent in -many languages, at taking advantage of translations already achieved in -other languages she just happens to know. It provides these other -language translations as additional context for her own work. Moreover, -it has features to ease the production of translations for many -languages at once, for translators preferring to work in this way. - - An "auxiliary" PO file is an existing PO file meant for the same -package the translator is working on, but targeted to a different mother -tongue language. Commands exist for declaring and handling auxiliary -PO files, and also for showing contexts for the entry under work. - - Here are the auxiliary file commands available in PO mode. - -`a' - Seek auxiliary files for another translation for the same entry - (`po-cycle-auxiliary'). - -`C-c C-a' - Switch to a particular auxiliary file (`po-select-auxiliary'). - -`A' - Declare this PO file as an auxiliary file - (`po-consider-as-auxiliary'). - -`M-A' - Remove this PO file from the list of auxiliary files - (`po-ignore-as-auxiliary'). - - - Command `A' (`po-consider-as-auxiliary') adds the current PO file to -the list of auxiliary files, while command `M-A' -(`po-ignore-as-auxiliary' just removes it. - - The command `a' (`po-cycle-auxiliary') seeks all auxiliary PO files, -round-robin, searching for a translated entry in some other language -having an `msgid' field identical as the one for the current entry. -The found PO file, if any, takes the place of the current PO file in -the display (its window gets on top). Before doing so, the current PO -file is also made into an auxiliary file, if not already. So, `a' in -this newly displayed PO file will seek another PO file, and so on, so -repeating `a' will eventually yield back the original PO file. - - The command `C-c C-a' (`po-select-auxiliary') asks the translator -for her choice of a particular auxiliary file, with completion, and -then switches to that selected PO file. The command also checks if the -selected file has an `msgid' field identical as the one for the current -entry, and if yes, this entry becomes current. Otherwise, the cursor -of the selected file is left undisturbed. - - For all this to work fully, auxiliary PO files will have to be -normalized, in that way that `msgid' fields should be written _exactly_ -the same way. It is possible to write `msgid' fields in various ways -for representing the same string, different writing would break the -proper behaviour of the auxiliary file commands of PO mode. This is not -expected to be much a problem in practice, as most existing PO files -have their `msgid' entries written by the same GNU `gettext' tools. - - However, PO files initially created by PO mode itself, while marking -strings in source files, are normalised differently. So are PO files -resulting of the `M-x normalize' command. Until these discrepancies -between PO mode and other GNU `gettext' tools get fully resolved, the -translator should stay aware of normalisation issues. - - -File: gettext.info, Node: Compendium, Prev: PO Mode, Up: Editing - -8.4 Using Translation Compendia -=============================== - - A "compendium" is a special PO file containing a set of translations -recurring in many different packages. The translator can use gettext -tools to build a new compendium, to add entries to her compendium, and -to initialize untranslated entries, or to update already translated -entries, from translations kept in the compendium. - -* Menu: - -* Creating Compendia:: Merging translations for later use -* Using Compendia:: Using older translations if they fit - - -File: gettext.info, Node: Creating Compendia, Next: Using Compendia, Prev: Compendium, Up: Compendium - -8.4.1 Creating Compendia ------------------------- - - Basically every PO file consisting of translated entries only can be -declared as a valid compendium. Often the translator wants to have -special compendia; let's consider two cases: `concatenating PO files' -and `extracting a message subset from a PO file'. - -8.4.1.1 Concatenate PO Files -............................ - - To concatenate several valid PO files into one compendium file you -can use `msgcomm' or `msgcat' (the latter preferred): - - msgcat -o compendium.po file1.po file2.po - - By default, `msgcat' will accumulate divergent translations for the -same string. Those occurrences will be marked as `fuzzy' and highly -visible decorated; calling `msgcat' on `file1.po': - - #: src/hello.c:200 - #, c-format - msgid "Report bugs to <%s>.\n" - msgstr "Comunicar `bugs' a <%s>.\n" - -and `file2.po': - - #: src/bye.c:100 - #, c-format - msgid "Report bugs to <%s>.\n" - msgstr "Comunicar \"bugs\" a <%s>.\n" - -will result in: - - #: src/hello.c:200 src/bye.c:100 - #, fuzzy, c-format - msgid "Report bugs to <%s>.\n" - msgstr "" - "#-#-#-#-# file1.po #-#-#-#-#\n" - "Comunicar `bugs' a <%s>.\n" - "#-#-#-#-# file2.po #-#-#-#-#\n" - "Comunicar \"bugs\" a <%s>.\n" - -The translator will have to resolve this "conflict" manually; she has -to decide whether the first or the second version is appropriate (or -provide a new translation), to delete the "marker lines", and finally -to remove the `fuzzy' mark. - - If the translator knows in advance the first found translation of a -message is always the best translation she can make use to the -`--use-first' switch: - - msgcat --use-first -o compendium.po file1.po file2.po - - A good compendium file must not contain `fuzzy' or untranslated -entries. If input files are "dirty" you must preprocess the input -files or postprocess the result using `msgattrib --translated ---no-fuzzy'. - -8.4.1.2 Extract a Message Subset from a PO File -............................................... - - Nobody wants to translate the same messages again and again; thus you -may wish to have a compendium file containing `getopt.c' messages. - - To extract a message subset (e.g., all `getopt.c' messages) from an -existing PO file into one compendium file you can use `msggrep': - - msggrep --location src/getopt.c -o compendium.po file.po - - -File: gettext.info, Node: Using Compendia, Prev: Creating Compendia, Up: Compendium - -8.4.2 Using Compendia ---------------------- - - You can use a compendium file to initialize a translation from -scratch or to update an already existing translation. - -8.4.2.1 Initialize a New Translation File -......................................... - - Since a PO file with translations does not exist the translator can -merely use `/dev/null' to fake the "old" translation file. - - msgmerge --compendium compendium.po -o file.po /dev/null file.pot - -8.4.2.2 Update an Existing Translation File -........................................... - - Concatenate the compendium file(s) and the existing PO, merge the -result with the POT file and remove the obsolete entries (optional, -here done using `sed'): - - msgcat --use-first -o update.po compendium1.po compendium2.po file.po - msgmerge update.po file.pot | msgattrib --no-obsolete > file.po - - -File: gettext.info, Node: Manipulating, Next: Binaries, Prev: Editing, Up: Top - -9 Manipulating PO Files -*********************** - - Sometimes it is necessary to manipulate PO files in a way that is -better performed automatically than by hand. GNU `gettext' includes a -complete set of tools for this purpose. - - When merging two packages into a single package, the resulting POT -file will be the concatenation of the two packages' POT files. Thus the -maintainer must concatenate the two existing package translations into -a single translation catalog, for each language. This is best performed -using `msgcat'. It is then the translators' duty to deal with any -possible conflicts that arose during the merge. - - When a translator takes over the translation job from another -translator, but she uses a different character encoding in her locale, -she will convert the catalog to her character encoding. This is best -done through the `msgconv' program. - - When a maintainer takes a source file with tagged messages from -another package, he should also take the existing translations for this -source file (and not let the translators do the same job twice). One -way to do this is through `msggrep', another is to create a POT file for -that source file and use `msgmerge'. - - When a translator wants to adjust some translation catalog for a -special dialect or orthography -- for example, German as written in -Switzerland versus German as written in Germany -- she needs to apply -some text processing to every message in the catalog. The tool for -doing this is `msgfilter'. - - Another use of `msgfilter' is to produce approximately the POT file -for which a given PO file was made. This can be done through a filter -command like `msgfilter sed -e d | sed -e '/^# /d''. Note that the -original POT file may have had different comments and different plural -message counts, that's why it's better to use the original POT file if -available. - - When a translator wants to check her translations, for example -according to orthography rules or using a non-interactive spell -checker, she can do so using the `msgexec' program. - - When third party tools create PO or POT files, sometimes duplicates -cannot be avoided. But the GNU `gettext' tools give an error when they -encounter duplicate msgids in the same file and in the same domain. To -merge duplicates, the `msguniq' program can be used. - - `msgcomm' is a more general tool for keeping or throwing away -duplicates, occurring in different files. - - `msgcmp' can be used to check whether a translation catalog is -completely translated. - - `msgattrib' can be used to select and extract only the fuzzy or -untranslated messages of a translation catalog. - - `msgen' is useful as a first step for preparing English translation -catalogs. It copies each message's msgid to its msgstr. - - Finally, for those applications where all these various programs are -not sufficient, a library `libgettextpo' is provided that can be used to -write other specialized programs that process PO files. - -* Menu: - -* msgcat Invocation:: Invoking the `msgcat' Program -* msgconv Invocation:: Invoking the `msgconv' Program -* msggrep Invocation:: Invoking the `msggrep' Program -* msgfilter Invocation:: Invoking the `msgfilter' Program -* msguniq Invocation:: Invoking the `msguniq' Program -* msgcomm Invocation:: Invoking the `msgcomm' Program -* msgcmp Invocation:: Invoking the `msgcmp' Program -* msgattrib Invocation:: Invoking the `msgattrib' Program -* msgen Invocation:: Invoking the `msgen' Program -* msgexec Invocation:: Invoking the `msgexec' Program -* Colorizing:: Highlighting parts of PO files -* libgettextpo:: Writing your own programs that process PO files - - -File: gettext.info, Node: msgcat Invocation, Next: msgconv Invocation, Prev: Manipulating, Up: Manipulating - -9.1 Invoking the `msgcat' Program -================================= - - msgcat [OPTION] [INPUTFILE]... - - The `msgcat' program concatenates and merges the specified PO files. -It finds messages which are common to two or more of the specified PO -files. By using the `--more-than' option, greater commonality may be -requested before messages are printed. Conversely, the `--less-than' -option may be used to specify less commonality before messages are -printed (i.e. `--less-than=2' will only print the unique messages). -Translations, comments and extract comments will be cumulated, except -that if `--use-first' is specified, they will be taken from the first -PO file to define them. File positions from all PO files will be -cumulated. - -9.1.1 Input file location -------------------------- - -`INPUTFILE ...' - Input files. - -`-f FILE' -`--files-from=FILE' - Read the names of the input files from FILE instead of getting - them from the command line. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - - - If INPUTFILE is `-', standard input is read. - -9.1.2 Output file location --------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified file. - - - The results are written to standard output if no output file is -specified or if it is `-'. - -9.1.3 Message selection ------------------------ - -`-< NUMBER' -`--less-than=NUMBER' - Print messages with less than NUMBER definitions, defaults to - infinite if not set. - -`-> NUMBER' -`--more-than=NUMBER' - Print messages with more than NUMBER definitions, defaults to 0 if - not set. - -`-u' -`--unique' - Shorthand for `--less-than=2'. Requests that only unique messages - be printed. - - -9.1.4 Input file syntax ------------------------ - -`-P' -`--properties-input' - Assume the input files are Java ResourceBundles in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input files are NeXTstep/GNUstep localized resource - files in `.strings' syntax, not in PO file syntax. - - -9.1.5 Output details --------------------- - -`-t' -`--to-code=NAME' - Specify encoding for output. - -`--use-first' - Use first available translation for each message. Don't merge - several translations into one. - -`--lang=CATALOGNAME' - Specify the `Language' field to be used in the header entry. See - *note Header Entry:: for the meaning of this field. Note: The - `Language-Team' and `Plural-Forms' fields are left unchanged. - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`--force-po' - Always write an output file even if it contains no message. - -`-i' -`--indent' - Write the .po file using indented style. - -`--no-location' - Do not write `#: FILENAME:LINE' lines. - -`-n' -`--add-location' - Generate `#: FILENAME:LINE' lines (default). - -`--strict' - Write out a strict Uniforum conforming PO file. Note that this - Uniforum format should be avoided because it doesn't support the - GNU extensions. - -`-p' -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - -`-s' -`--sort-output' - Generate sorted output. Note that using this option makes it much - harder for the translator to understand each message's context. - -`-F' -`--sort-by-file' - Sort output by file location. - - -9.1.6 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - - -File: gettext.info, Node: msgconv Invocation, Next: msggrep Invocation, Prev: msgcat Invocation, Up: Manipulating - -9.2 Invoking the `msgconv' Program -================================== - - msgconv [OPTION] [INPUTFILE] - - The `msgconv' program converts a translation catalog to a different -character encoding. - -9.2.1 Input file location -------------------------- - -`INPUTFILE' - Input PO file. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - - - If no INPUTFILE is given or if it is `-', standard input is read. - -9.2.2 Output file location --------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified file. - - - The results are written to standard output if no output file is -specified or if it is `-'. - -9.2.3 Conversion target ------------------------ - -`-t' -`--to-code=NAME' - Specify encoding for output. - - - The default encoding is the current locale's encoding. - -9.2.4 Input file syntax ------------------------ - -`-P' -`--properties-input' - Assume the input file is a Java ResourceBundle in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input file is a NeXTstep/GNUstep localized resource - file in `.strings' syntax, not in PO file syntax. - - -9.2.5 Output details --------------------- - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`--force-po' - Always write an output file even if it contains no message. - -`-i' -`--indent' - Write the .po file using indented style. - -`--no-location' - Do not write `#: FILENAME:LINE' lines. - -`--add-location' - Generate `#: FILENAME:LINE' lines (default). - -`--strict' - Write out a strict Uniforum conforming PO file. Note that this - Uniforum format should be avoided because it doesn't support the - GNU extensions. - -`-p' -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - -`-s' -`--sort-output' - Generate sorted output. Note that using this option makes it much - harder for the translator to understand each message's context. - -`-F' -`--sort-by-file' - Sort output by file location. - - -9.2.6 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - - -File: gettext.info, Node: msggrep Invocation, Next: msgfilter Invocation, Prev: msgconv Invocation, Up: Manipulating - -9.3 Invoking the `msggrep' Program -================================== - - msggrep [OPTION] [INPUTFILE] - - The `msggrep' program extracts all messages of a translation catalog -that match a given pattern or belong to some given source files. - -9.3.1 Input file location -------------------------- - -`INPUTFILE' - Input PO file. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - - - If no INPUTFILE is given or if it is `-', standard input is read. - -9.3.2 Output file location --------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified file. - - - The results are written to standard output if no output file is -specified or if it is `-'. - -9.3.3 Message selection ------------------------ - - [-N SOURCEFILE]... [-M DOMAINNAME]... - [-J MSGCTXT-PATTERN] [-K MSGID-PATTERN] [-T MSGSTR-PATTERN] - [-C COMMENT-PATTERN] - - A message is selected if - * it comes from one of the specified source files, - - * or if it comes from one of the specified domains, - - * or if `-J' is given and its context (msgctxt) matches - MSGCTXT-PATTERN, - - * or if `-K' is given and its key (msgid or msgid_plural) matches - MSGID-PATTERN, - - * or if `-T' is given and its translation (msgstr) matches - MSGSTR-PATTERN, - - * or if `-C' is given and the translator's comment matches - COMMENT-PATTERN. - - When more than one selection criterion is specified, the set of -selected messages is the union of the selected messages of each -criterion. - - MSGCTXT-PATTERN or MSGID-PATTERN or MSGSTR-PATTERN syntax: - [-E | -F] [-e PATTERN | -f FILE]... - PATTERNs are basic regular expressions by default, or extended -regular expressions if -E is given, or fixed strings if -F is given. - -`-N SOURCEFILE' -`--location=SOURCEFILE' - Select messages extracted from SOURCEFILE. SOURCEFILE can be - either a literal file name or a wildcard pattern. - -`-M DOMAINNAME' -`--domain=DOMAINNAME' - Select messages belonging to domain DOMAINNAME. - -`-J' -`--msgctxt' - Start of patterns for the msgctxt. - -`-K' -`--msgid' - Start of patterns for the msgid. - -`-T' -`--msgstr' - Start of patterns for the msgstr. - -`-C' -`--comment' - Start of patterns for the translator's comment. - -`-X' -`--extracted-comment' - Start of patterns for the extracted comments. - -`-E' -`--extended-regexp' - Specify that PATTERN is an extended regular expression. - -`-F' -`--fixed-strings' - Specify that PATTERN is a set of newline-separated strings. - -`-e PATTERN' -`--regexp=PATTERN' - Use PATTERN as a regular expression. - -`-f FILE' -`--file=FILE' - Obtain PATTERN from FILE. - -`-i' -`--ignore-case' - Ignore case distinctions. - -`-v' -`--invert-match' - Output only the messages that do not match any selection - criterion, instead of the messages that match a selection - criterion. - - -9.3.4 Input file syntax ------------------------ - -`-P' -`--properties-input' - Assume the input file is a Java ResourceBundle in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input file is a NeXTstep/GNUstep localized resource - file in `.strings' syntax, not in PO file syntax. - - -9.3.5 Output details --------------------- - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`--force-po' - Always write an output file even if it contains no message. - -`--indent' - Write the .po file using indented style. - -`--no-location' - Do not write `#: FILENAME:LINE' lines. - -`--add-location' - Generate `#: FILENAME:LINE' lines (default). - -`--strict' - Write out a strict Uniforum conforming PO file. Note that this - Uniforum format should be avoided because it doesn't support the - GNU extensions. - -`-p' -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - -`--sort-output' - Generate sorted output. Note that using this option makes it much - harder for the translator to understand each message's context. - -`--sort-by-file' - Sort output by file location. - - -9.3.6 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - -9.3.7 Examples --------------- - - To extract the messages that come from the source files -`gnulib-lib/error.c' and `gnulib-lib/getopt.c': - - msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po - - To extract the messages that contain the string "Please specify" in -the original string: - - msggrep --msgid -F -e 'Please specify' input.po - - To extract the messages that have a context specifier of either -"Menu>File" or "Menu>Edit" or a submenu of them: - - msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po - - To extract the messages whose translation contains one of the -strings in the file `wordlist.txt': - - msggrep --msgstr -F -f wordlist.txt input.po - - -File: gettext.info, Node: msgfilter Invocation, Next: msguniq Invocation, Prev: msggrep Invocation, Up: Manipulating - -9.4 Invoking the `msgfilter' Program -==================================== - - msgfilter [OPTION] FILTER [FILTER-OPTION] - - The `msgfilter' program applies a filter to all translations of a -translation catalog. - - During each FILTER invocation, the environment variable -`MSGFILTER_MSGID' is bound to the message's msgid, and the environment -variable `MSGFILTER_LOCATION' is bound to the location in the PO file -of the message. If the message has a context, the environment variable -`MSGFILTER_MSGCTXT' is bound to the message's msgctxt, otherwise it is -unbound. - -9.4.1 Input file location -------------------------- - -`-i INPUTFILE' -`--input=INPUTFILE' - Input PO file. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - - - If no INPUTFILE is given or if it is `-', standard input is read. - -9.4.2 Output file location --------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified file. - - - The results are written to standard output if no output file is -specified or if it is `-'. - -9.4.3 The filter ----------------- - - The FILTER can be any program that reads a translation from standard -input and writes a modified translation to standard output. A -frequently used filter is `sed'. A few particular built-in filters are -also recognized. - - Note: If the filter is not a built-in filter, you have to care about -encodings: It is your responsibility to ensure that the FILTER can cope -with input encoded in the translation catalog's encoding. If the -FILTER wants input in a particular encoding, you can in a first step -convert the translation catalog to that encoding using the `msgconv' -program, before invoking `msgfilter'. If the FILTER wants input in the -locale's encoding, but you want to avoid the locale's encoding, then -you can first convert the translation catalog to UTF-8 using the -`msgconv' program and then make `msgfilter' work in an UTF-8 locale, by -using the `LC_ALL' environment variable. - - Note: Most translations in a translation catalog don't end with a -newline character. For this reason, it is important that the FILTER -recognizes its last input line even if it ends without a newline, and -that it doesn't add an undesired trailing newline at the end. The `sed' -program on some platforms is known to ignore the last line of input if -it is not terminated with a newline. You can use GNU `sed' instead; it -does not have this limitation. - -9.4.4 Useful FILTER-OPTIONs when the FILTER is `sed' ----------------------------------------------------- - -`-e SCRIPT' -`--expression=SCRIPT' - Add SCRIPT to the commands to be executed. - -`-f SCRIPTFILE' -`--file=SCRIPTFILE' - Add the contents of SCRIPTFILE to the commands to be executed. - -`-n' -`--quiet' -`--silent' - Suppress automatic printing of pattern space. - - -9.4.5 Built-in FILTERs ----------------------- - - The filter `recode-sr-latin' is recognized as a built-in filter. -The command `recode-sr-latin' converts Serbian text, written in the -Cyrillic script, to the Latin script. The command `msgfilter -recode-sr-latin' applies this conversion to the translations of a PO -file. Thus, it can be used to convert an `sr.po' file to an -`sr@latin.po' file. - - The use of built-in filters is not sensitive to the current locale's -encoding. Moreover, when used with a built-in filter, `msgfilter' can -automatically convert the message catalog to the UTF-8 encoding when -needed. - -9.4.6 Input file syntax ------------------------ - -`-P' -`--properties-input' - Assume the input file is a Java ResourceBundle in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input file is a NeXTstep/GNUstep localized resource - file in `.strings' syntax, not in PO file syntax. - - -9.4.7 Output details --------------------- - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`--force-po' - Always write an output file even if it contains no message. - -`--indent' - Write the .po file using indented style. - -`--keep-header' - Keep the header entry, i.e. the message with `msgid ""', - unmodified, instead of filtering it. By default, the header entry - is subject to filtering like any other message. - -`--no-location' - Do not write `#: FILENAME:LINE' lines. - -`--add-location' - Generate `#: FILENAME:LINE' lines (default). - -`--strict' - Write out a strict Uniforum conforming PO file. Note that this - Uniforum format should be avoided because it doesn't support the - GNU extensions. - -`-p' -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - -`-s' -`--sort-output' - Generate sorted output. Note that using this option makes it much - harder for the translator to understand each message's context. - -`-F' -`--sort-by-file' - Sort output by file location. - - -9.4.8 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - -9.4.9 Examples --------------- - - To convert German translations to Swiss orthography (in an UTF-8 -locale): - - msgconv -t UTF-8 de.po | msgfilter sed -e 's/ß/ss/g' - - To convert Serbian translations in Cyrillic script to Latin script: - - msgfilter recode-sr-latin < sr.po - - -File: gettext.info, Node: msguniq Invocation, Next: msgcomm Invocation, Prev: msgfilter Invocation, Up: Manipulating - -9.5 Invoking the `msguniq' Program -================================== - - msguniq [OPTION] [INPUTFILE] - - The `msguniq' program unifies duplicate translations in a translation -catalog. It finds duplicate translations of the same message ID. Such -duplicates are invalid input for other programs like `msgfmt', -`msgmerge' or `msgcat'. By default, duplicates are merged together. -When using the `--repeated' option, only duplicates are output, and all -other messages are discarded. Comments and extracted comments will be -cumulated, except that if `--use-first' is specified, they will be -taken from the first translation. File positions will be cumulated. -When using the `--unique' option, duplicates are discarded. - -9.5.1 Input file location -------------------------- - -`INPUTFILE' - Input PO file. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - - - If no INPUTFILE is given or if it is `-', standard input is read. - -9.5.2 Output file location --------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified file. - - - The results are written to standard output if no output file is -specified or if it is `-'. - -9.5.3 Message selection ------------------------ - -`-d' -`--repeated' - Print only duplicates. - -`-u' -`--unique' - Print only unique messages, discard duplicates. - - -9.5.4 Input file syntax ------------------------ - -`-P' -`--properties-input' - Assume the input file is a Java ResourceBundle in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input file is a NeXTstep/GNUstep localized resource - file in `.strings' syntax, not in PO file syntax. - - -9.5.5 Output details --------------------- - -`-t' -`--to-code=NAME' - Specify encoding for output. - -`--use-first' - Use first available translation for each message. Don't merge - several translations into one. - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`--force-po' - Always write an output file even if it contains no message. - -`-i' -`--indent' - Write the .po file using indented style. - -`--no-location' - Do not write `#: FILENAME:LINE' lines. - -`-n' -`--add-location' - Generate `#: FILENAME:LINE' lines (default). - -`--strict' - Write out a strict Uniforum conforming PO file. Note that this - Uniforum format should be avoided because it doesn't support the - GNU extensions. - -`-p' -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - -`-s' -`--sort-output' - Generate sorted output. Note that using this option makes it much - harder for the translator to understand each message's context. - -`-F' -`--sort-by-file' - Sort output by file location. - - -9.5.6 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - - -File: gettext.info, Node: msgcomm Invocation, Next: msgcmp Invocation, Prev: msguniq Invocation, Up: Manipulating - -9.6 Invoking the `msgcomm' Program -================================== - - msgcomm [OPTION] [INPUTFILE]... - - The `msgcomm' program finds messages which are common to two or more -of the specified PO files. By using the `--more-than' option, greater -commonality may be requested before messages are printed. Conversely, -the `--less-than' option may be used to specify less commonality before -messages are printed (i.e. `--less-than=2' will only print the unique -messages). Translations, comments and extract comments will be -preserved, but only from the first PO file to define them. File -positions from all PO files will be cumulated. - -9.6.1 Input file location -------------------------- - -`INPUTFILE ...' - Input files. - -`-f FILE' -`--files-from=FILE' - Read the names of the input files from FILE instead of getting - them from the command line. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - - - If INPUTFILE is `-', standard input is read. - -9.6.2 Output file location --------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified file. - - - The results are written to standard output if no output file is -specified or if it is `-'. - -9.6.3 Message selection ------------------------ - -`-< NUMBER' -`--less-than=NUMBER' - Print messages with less than NUMBER definitions, defaults to - infinite if not set. - -`-> NUMBER' -`--more-than=NUMBER' - Print messages with more than NUMBER definitions, defaults to 1 if - not set. - -`-u' -`--unique' - Shorthand for `--less-than=2'. Requests that only unique messages - be printed. - - -9.6.4 Input file syntax ------------------------ - -`-P' -`--properties-input' - Assume the input files are Java ResourceBundles in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input files are NeXTstep/GNUstep localized resource - files in `.strings' syntax, not in PO file syntax. - - -9.6.5 Output details --------------------- - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`--force-po' - Always write an output file even if it contains no message. - -`-i' -`--indent' - Write the .po file using indented style. - -`--no-location' - Do not write `#: FILENAME:LINE' lines. - -`-n' -`--add-location' - Generate `#: FILENAME:LINE' lines (default). - -`--strict' - Write out a strict Uniforum conforming PO file. Note that this - Uniforum format should be avoided because it doesn't support the - GNU extensions. - -`-p' -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - -`-s' -`--sort-output' - Generate sorted output. Note that using this option makes it much - harder for the translator to understand each message's context. - -`-F' -`--sort-by-file' - Sort output by file location. - -`--omit-header' - Don't write header with `msgid ""' entry. - - -9.6.6 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - - -File: gettext.info, Node: msgcmp Invocation, Next: msgattrib Invocation, Prev: msgcomm Invocation, Up: Manipulating - -9.7 Invoking the `msgcmp' Program -================================= - - msgcmp [OPTION] DEF.po REF.pot - - The `msgcmp' program compares two Uniforum style .po files to check -that both contain the same set of msgid strings. The DEF.po file is an -existing PO file with the translations. The REF.pot file is the last -created PO file, or a PO Template file (generally created by -`xgettext'). This is useful for checking that you have translated each -and every message in your program. Where an exact match cannot be -found, fuzzy matching is used to produce better diagnostics. - -9.7.1 Input file location -------------------------- - -`DEF.po' - Translations. - -`REF.pot' - References to the sources. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. - - -9.7.2 Operation modifiers -------------------------- - -`-m' -`--multi-domain' - Apply REF.pot to each of the domains in DEF.po. - -`-N' -`--no-fuzzy-matching' - Do not use fuzzy matching when an exact match is not found. This - may speed up the operation considerably. - -`--use-fuzzy' - Consider fuzzy messages in the DEF.po file like translated - messages. Note that using this option is usually wrong, because - fuzzy messages are exactly those which have not been validated by - a human translator. - -`--use-untranslated' - Consider untranslated messages in the DEF.po file like translated - messages. Note that using this option is usually wrong. - - -9.7.3 Input file syntax ------------------------ - -`-P' -`--properties-input' - Assume the input files are Java ResourceBundles in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input files are NeXTstep/GNUstep localized resource - files in `.strings' syntax, not in PO file syntax. - - -9.7.4 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - - -File: gettext.info, Node: msgattrib Invocation, Next: msgen Invocation, Prev: msgcmp Invocation, Up: Manipulating - -9.8 Invoking the `msgattrib' Program -==================================== - - msgattrib [OPTION] [INPUTFILE] - - The `msgattrib' program filters the messages of a translation catalog -according to their attributes, and manipulates the attributes. - -9.8.1 Input file location -------------------------- - -`INPUTFILE' - Input PO file. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - - - If no INPUTFILE is given or if it is `-', standard input is read. - -9.8.2 Output file location --------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified file. - - - The results are written to standard output if no output file is -specified or if it is `-'. - -9.8.3 Message selection ------------------------ - -`--translated' - Keep translated messages, remove untranslated messages. - -`--untranslated' - Keep untranslated messages, remove translated messages. - -`--no-fuzzy' - Remove `fuzzy' marked messages. - -`--only-fuzzy' - Keep `fuzzy' marked messages, remove all other messages. - -`--no-obsolete' - Remove obsolete #~ messages. - -`--only-obsolete' - Keep obsolete #~ messages, remove all other messages. - - -9.8.4 Attribute manipulation ----------------------------- - - Attributes are modified after the message selection/removal has been -performed. If the `--only-file' or `--ignore-file' option is -specified, the attribute modification is applied only to those messages -that are listed in the ONLY-FILE and not listed in the IGNORE-FILE. - -`--set-fuzzy' - Set all messages `fuzzy'. - -`--clear-fuzzy' - Set all messages non-`fuzzy'. - -`--set-obsolete' - Set all messages obsolete. - -`--clear-obsolete' - Set all messages non-obsolete. - -`--clear-previous' - Remove the "previous msgid" (`#|') comments from all messages. - -`--only-file=FILE' - Limit the attribute changes to entries that are listed in FILE. - FILE should be a PO or POT file. - -`--ignore-file=FILE' - Limit the attribute changes to entries that are not listed in FILE. - FILE should be a PO or POT file. - -`--fuzzy' - Synonym for `--only-fuzzy --clear-fuzzy': It keeps only the fuzzy - messages and removes their `fuzzy' mark. - -`--obsolete' - Synonym for `--only-obsolete --clear-obsolete': It keeps only the - obsolete messages and makes them non-obsolete. - - -9.8.5 Input file syntax ------------------------ - -`-P' -`--properties-input' - Assume the input file is a Java ResourceBundle in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input file is a NeXTstep/GNUstep localized resource - file in `.strings' syntax, not in PO file syntax. - - -9.8.6 Output details --------------------- - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`--force-po' - Always write an output file even if it contains no message. - -`-i' -`--indent' - Write the .po file using indented style. - -`--no-location' - Do not write `#: FILENAME:LINE' lines. - -`-n' -`--add-location' - Generate `#: FILENAME:LINE' lines (default). - -`--strict' - Write out a strict Uniforum conforming PO file. Note that this - Uniforum format should be avoided because it doesn't support the - GNU extensions. - -`-p' -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - -`-s' -`--sort-output' - Generate sorted output. Note that using this option makes it much - harder for the translator to understand each message's context. - -`-F' -`--sort-by-file' - Sort output by file location. - - -9.8.7 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - - -File: gettext.info, Node: msgen Invocation, Next: msgexec Invocation, Prev: msgattrib Invocation, Up: Manipulating - -9.9 Invoking the `msgen' Program -================================ - - msgen [OPTION] INPUTFILE - - The `msgen' program creates an English translation catalog. The -input file is the last created English PO file, or a PO Template file -(generally created by xgettext). Untranslated entries are assigned a -translation that is identical to the msgid. - - Note: `msginit --no-translator --locale=en' performs a very similar -task. The main difference is that `msginit' cares specially about the -header entry, whereas `msgen' doesn't. - -9.9.1 Input file location -------------------------- - -`INPUTFILE' - Input PO or POT file. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - - - If INPUTFILE is `-', standard input is read. - -9.9.2 Output file location --------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified file. - - - The results are written to standard output if no output file is -specified or if it is `-'. - -9.9.3 Input file syntax ------------------------ - -`-P' -`--properties-input' - Assume the input file is a Java ResourceBundle in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input file is a NeXTstep/GNUstep localized resource - file in `.strings' syntax, not in PO file syntax. - - -9.9.4 Output details --------------------- - -`--lang=CATALOGNAME' - Specify the `Language' field to be used in the header entry. See - *note Header Entry:: for the meaning of this field. Note: The - `Language-Team' and `Plural-Forms' fields are not set by this - option. - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`--force-po' - Always write an output file even if it contains no message. - -`-i' -`--indent' - Write the .po file using indented style. - -`--no-location' - Do not write `#: FILENAME:LINE' lines. - -`--add-location' - Generate `#: FILENAME:LINE' lines (default). - -`--strict' - Write out a strict Uniforum conforming PO file. Note that this - Uniforum format should be avoided because it doesn't support the - GNU extensions. - -`-p' -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - -`-s' -`--sort-output' - Generate sorted output. Note that using this option makes it much - harder for the translator to understand each message's context. - -`-F' -`--sort-by-file' - Sort output by file location. - - -9.9.5 Informative output ------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - - -File: gettext.info, Node: msgexec Invocation, Next: Colorizing, Prev: msgen Invocation, Up: Manipulating - -9.10 Invoking the `msgexec' Program -=================================== - - msgexec [OPTION] COMMAND [COMMAND-OPTION] - - The `msgexec' program applies a command to all translations of a -translation catalog. The COMMAND can be any program that reads a -translation from standard input. It is invoked once for each -translation. Its output becomes msgexec's output. `msgexec''s return -code is the maximum return code across all invocations. - - A special builtin command called `0' outputs the translation, -followed by a null byte. The output of `msgexec 0' is suitable as -input for `xargs -0'. - - During each COMMAND invocation, the environment variable -`MSGEXEC_MSGID' is bound to the message's msgid, and the environment -variable `MSGEXEC_LOCATION' is bound to the location in the PO file of -the message. If the message has a context, the environment variable -`MSGEXEC_MSGCTXT' is bound to the message's msgctxt, otherwise it is -unbound. - - Note: It is your responsibility to ensure that the COMMAND can cope -with input encoded in the translation catalog's encoding. If the -COMMAND wants input in a particular encoding, you can in a first step -convert the translation catalog to that encoding using the `msgconv' -program, before invoking `msgexec'. If the COMMAND wants input in the -locale's encoding, but you want to avoid the locale's encoding, then -you can first convert the translation catalog to UTF-8 using the -`msgconv' program and then make `msgexec' work in an UTF-8 locale, by -using the `LC_ALL' environment variable. - -9.10.1 Input file location --------------------------- - -`-i INPUTFILE' -`--input=INPUTFILE' - Input PO file. - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - - - If no INPUTFILE is given or if it is `-', standard input is read. - -9.10.2 Input file syntax ------------------------- - -`-P' -`--properties-input' - Assume the input file is a Java ResourceBundle in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input file is a NeXTstep/GNUstep localized resource - file in `.strings' syntax, not in PO file syntax. - - -9.10.3 Informative output -------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - - -File: gettext.info, Node: Colorizing, Next: libgettextpo, Prev: msgexec Invocation, Up: Manipulating - -9.11 Highlighting parts of PO files -=================================== - - Translators are usually only interested in seeing the untranslated -and fuzzy messages of a PO file. Also, when a message is set fuzzy -because the msgid changed, they want to see the differences between the -previous msgid and the current one (especially if the msgid is long and -only few words in it have changed). Finally, it's always welcome to -highlight the different sections of a message in a PO file (comments, -msgid, msgstr, etc.). - - Such highlighting is possible through the `msgcat' options `--color' -and `--style'. - -* Menu: - -* The --color option:: Triggering colorized output -* The TERM variable:: The environment variable `TERM' -* The --style option:: The `--style' option -* Style rules:: Style rules for PO files -* Customizing less:: Customizing `less' for viewing PO files - - -File: gettext.info, Node: The --color option, Next: The TERM variable, Up: Colorizing - -9.11.1 The `--color' option ---------------------------- - - The `--color=WHEN' option specifies under which conditions colorized -output should be generated. The WHEN part can be one of the following: - -`always' -`yes' - The output will be colorized. - -`never' -`no' - The output will not be colorized. - -`auto' -`tty' - The output will be colorized if the output device is a tty, i.e. - when the output goes directly to a text screen or terminal - emulator window. - -`html' - The output will be colorized and be in HTML format. - -`--color' is equivalent to `--color=yes'. The default is -`--color=auto'. - - Thus, a command like `msgcat vi.po' will produce colorized output -when called by itself in a command window. Whereas in a pipe, such as -`msgcat vi.po | less -R', it will not produce colorized output. To get -colorized output in this situation nevertheless, use the command -`msgcat --color vi.po | less -R'. - - The `--color=html' option will produce output that can be viewed in -a browser. This can be useful, for example, for Indic languages, -because the renderic of Indic scripts in browser is usually better than -in terminal emulators. - - Note that the output produced with the `--color' option is _not_ a -valid PO file in itself. It contains additional terminal-specific -escape sequences or HTML tags. A PO file reader will give a syntax -error when confronted with such content. Except for the `--color=html' -case, you therefore normally don't need to save output produced with the -`--color' option in a file. - - -File: gettext.info, Node: The TERM variable, Next: The --style option, Prev: The --color option, Up: Colorizing - -9.11.2 The environment variable `TERM' --------------------------------------- - - The environment variable `TERM' contains a identifier for the text -window's capabilities. You can get a detailed list of these -cababilities by using the `infocmp' command, using `man 5 terminfo' as a -reference. - - When producing text with embedded color directives, `msgcat' looks -at the `TERM' variable. Text windows today typically support at least -8 colors. Often, however, the text window supports 16 or more colors, -even though the `TERM' variable is set to a identifier denoting only 8 -supported colors. It can be worth setting the `TERM' variable to a -different value in these cases: - -`xterm' - `xterm' is in most cases built with support for 16 colors. It can - also be built with support for 88 or 256 colors (but not both). - You can try to set `TERM' to either `xterm-16color', - `xterm-88color', or `xterm-256color'. - -`rxvt' - `rxvt' is often built with support for 16 colors. You can try to - set `TERM' to `rxvt-16color'. - -`konsole' - `konsole' too is often built with support for 16 colors. You can - try to set `TERM' to `konsole-16color' or `xterm-16color'. - - After setting `TERM', you can verify it by invoking `msgcat ---color=test' and seeing whether the output looks like a reasonable -color map. - - -File: gettext.info, Node: The --style option, Next: Style rules, Prev: The TERM variable, Up: Colorizing - -9.11.3 The `--style' option ---------------------------- - - The `--style=STYLE_FILE' option specifies the style file to use when -colorizing. It has an effect only when the `--color' option is -effective. - - If the `--style' option is not specified, the environment variable -`PO_STYLE' is considered. It is meant to point to the user's preferred -style for PO files. - - The default style file is -`$prefix/share/gettext/styles/po-default.css', where `$prefix' is the -installation location. - - A few style files are predefined: -`po-vim.css' - This style imitates the look used by vim 7. - -`po-emacs-x.css' - This style imitates the look used by GNU Emacs 21 and 22 in an X11 - window. - -`po-emacs-xterm.css' -`po-emacs-xterm16.css' -`po-emacs-xterm256.css' - This style imitates the look used by GNU Emacs 22 in a terminal of - type `xterm' (8 colors) or `xterm-16color' (16 colors) or - `xterm-256color' (256 colors), respectively. - -You can use these styles without specifying a directory. They are -actually located in `$prefix/share/gettext/styles/', where `$prefix' is -the installation location. - - You can also design your own styles. This is described in the next -section. - - -File: gettext.info, Node: Style rules, Next: Customizing less, Prev: The --style option, Up: Colorizing - -9.11.4 Style rules for PO files -------------------------------- - - The same style file can be used for styling of a PO file, for -terminal output and for HTML output. It is written in CSS (Cascading -Style Sheet) syntax. See `http://www.w3.org/TR/css2/cover.html' for a -formal definition of CSS. Many HTML authoring tutorials also contain -explanations of CSS. - - In the case of HTML output, the style file is embedded in the HTML -output. In the case of text output, the style file is interpreted by -the `msgcat' program. This means, in particular, that when `@import' -is used with relative file names, the file names are - - - relative to the resulting HTML file, in the case of HTML output, - - - relative to the style sheet containing the `@import', in the case - of text output. (Actually, `@import's are not yet supported in - this case, due to a limitation in `libcroco'.) - - CSS rules are built up from selectors and declarations. The -declarations specify graphical properties; the selectors specify -specify when they apply. - - In PO files, the following simple selectors (based on "CSS classes", -see the CSS2 spec, section 5.8.3) are supported. - - * Selectors that apply to entire messages: - - `.header' - This matches the header entry of a PO file. - - `.translated' - This matches a translated message. - - `.untranslated' - This matches an untranslated message (i.e. a message with - empty translation). - - `.fuzzy' - This matches a fuzzy message (i.e. a message which has a - translation that needs review by the translator). - - `.obsolete' - This matches an obsolete message (i.e. a message that was - translated but is not needed by the current POT file any - more). - - * Selectors that apply to parts of a message in PO syntax. Recall - the general structure of a message in PO syntax: - - WHITE-SPACE - # TRANSLATOR-COMMENTS - #. EXTRACTED-COMMENTS - #: REFERENCE... - #, FLAG... - #| msgid PREVIOUS-UNTRANSLATED-STRING - msgid UNTRANSLATED-STRING - msgstr TRANSLATED-STRING - - `.comment' - This matches all comments (translator comments, extracted - comments, source file reference comments, flag comments, - previous message comments, as well as the entire obsolete - messages). - - `.translator-comment' - This matches the translator comments. - - `.extracted-comment' - This matches the extracted comments, i.e. the comments placed - by the programmer at the attention of the translator. - - `.reference-comment' - This matches the source file reference comments (entire - lines). - - `.reference' - This matches the individual source file references inside the - source file reference comment lines. - - `.flag-comment' - This matches the flag comment lines (entire lines). - - `.flag' - This matches the individual flags inside flag comment lines. - - `.fuzzy-flag' - This matches the `fuzzy' flag inside flag comment lines. - - `.previous-comment' - This matches the comments containing the previous - untranslated string (entire lines). - - `.previous' - This matches the previous untranslated string including the - string delimiters, the associated keywords (`msgid' etc.) and - the spaces between them. - - `.msgid' - This matches the untranslated string including the string - delimiters, the associated keywords (`msgid' etc.) and the - spaces between them. - - `.msgstr' - This matches the translated string including the string - delimiters, the associated keywords (`msgstr' etc.) and the - spaces between them. - - `.keyword' - This matches the keywords (`msgid', `msgstr', etc.). - - `.string' - This matches strings, including the string delimiters (double - quotes). - - * Selectors that apply to parts of strings: - - `.text' - This matches the entire contents of a string (excluding the - string delimiters, i.e. the double quotes). - - `.escape-sequence' - This matches an escape sequence (starting with a backslash). - - `.format-directive' - This matches a format string directive (starting with a `%' - sign in the case of most programming languages, with a `{' in - the case of `java-format' and `csharp-format', with a `~' in - the case of `lisp-format' and `scheme-format', or with `$' in - the case of `sh-format'). - - `.invalid-format-directive' - This matches an invalid format string directive. - - `.added' - In an untranslated string, this matches a part of the string - that was not present in the previous untranslated string. - (Not yet implemented in this release.) - - `.changed' - In an untranslated string or in a previous untranslated - string, this matches a part of the string that is changed or - replaced. (Not yet implemented in this release.) - - `.removed' - In a previous untranslated string, this matches a part of the - string that is not present in the current untranslated - string. (Not yet implemented in this release.) - - These selectors can be combined to hierarchical selectors. For -example, - - .msgstr .invalid-format-directive { color: red; } - -will highlight the invalid format directives in the translated strings. - - In text mode, pseudo-classes (CSS2 spec, section 5.11) and -pseudo-elements (CSS2 spec, section 5.12) are not supported. - - The declarations in HTML mode are not limited; any graphical -attribute supported by the browsers can be used. - - The declarations in text mode are limited to the following -properties. Other properties will be silently ignored. - -`color' (CSS2 spec, section 14.1) -`background-color' (CSS2 spec, section 14.2.1) - These properties is supported. Colors will be adjusted to match - the terminal's capabilities. Note that many terminals support - only 8 colors. - -`font-weight' (CSS2 spec, section 15.2.3) - This property is supported, but most terminals can only render two - different weights: `normal' and `bold'. Values >= 600 are - rendered as `bold'. - -`font-style' (CSS2 spec, section 15.2.3) - This property is supported. The values `italic' and `oblique' are - rendered the same way. - -`text-decoration' (CSS2 spec, section 16.3.1) - This property is supported, limited to the values `none' and - `underline'. - - -File: gettext.info, Node: Customizing less, Prev: Style rules, Up: Colorizing - -9.11.5 Customizing `less' for viewing PO files ----------------------------------------------- - - The `less' program is a popular text file browser for use in a text -screen or terminal emulator. It also supports text with embedded escape -sequences for colors and text decorations. - - You can use `less' to view a PO file like this (assuming an UTF-8 -environment): - - msgcat --to-code=UTF-8 --color xyz.po | less -R - - You can simplify this to this simple command: - - less xyz.po - -after these three preparations: - - 1. Add the options `-R' and `-f' to the `LESS' environment variable. - In sh shells: - $ LESS="$LESS -R -f" - $ export LESS - - 2. If your system does not already have the `lessopen.sh' and - `lessclose.sh' scripts, create them and set the `LESSOPEN' and - `LESSCLOSE' environment variables, as indicated in the manual page - (`man less'). - - 3. Add to `lessopen.sh' a piece of script that recognizes PO files - through their file extension and invokes `msgcat' on them, - producing a temporary file. Like this: - - case "$1" in - *.po) - tmpfile=`mktemp "${TMPDIR-/tmp}/less.XXXXXX"` - msgcat --to-code=UTF-8 --color "$1" > "$tmpfile" - echo "$tmpfile" - exit 0 - ;; - esac - - -File: gettext.info, Node: libgettextpo, Prev: Colorizing, Up: Manipulating - -9.12 Writing your own programs that process PO files -==================================================== - - For the tasks for which a combination of `msgattrib', `msgcat' etc. -is not sufficient, a set of C functions is provided in a library, to -make it possible to process PO files in your own programs. When you -use this library, you don't need to write routines to parse the PO -file; instead, you retrieve a pointer in memory to each of messages -contained in the PO file. Functions for writing PO files are not -provided at this time. - - The functions are declared in the header file `<gettext-po.h>', and -are defined in a library called `libgettextpo'. - - -- Data Type: po_file_t - This is a pointer type that refers to the contents of a PO file, - after it has been read into memory. - - -- Data Type: po_message_iterator_t - This is a pointer type that refers to an iterator that produces a - sequence of messages. - - -- Data Type: po_message_t - This is a pointer type that refers to a message of a PO file, - including its translation. - - -- Function: po_file_t po_file_read (const char *FILENAME) - The `po_file_read' function reads a PO file into memory. The file - name is given as argument. The return value is a handle to the PO - file's contents, valid until `po_file_free' is called on it. In - case of error, the return value is `NULL', and `errno' is set. - - -- Function: void po_file_free (po_file_t FILE) - The `po_file_free' function frees a PO file's contents from memory, - including all messages that are only implicitly accessible through - iterators. - - -- Function: const char * const * po_file_domains (po_file_t FILE) - The `po_file_domains' function returns the domains for which the - given PO file has messages. The return value is a `NULL' - terminated array which is valid as long as the FILE handle is - valid. For PO files which contain no `domain' directive, the - return value contains only one domain, namely the default domain - `"messages"'. - - -- Function: po_message_iterator_t po_message_iterator (po_file_t - FILE, const char *DOMAIN) - The `po_message_iterator' returns an iterator that will produce the - messages of FILE that belong to the given DOMAIN. If DOMAIN is - `NULL', the default domain is used instead. To list the messages, - use the function `po_next_message' repeatedly. - - -- Function: void po_message_iterator_free (po_message_iterator_t - ITERATOR) - The `po_message_iterator_free' function frees an iterator - previously allocated through the `po_message_iterator' function. - - -- Function: po_message_t po_next_message (po_message_iterator_t - ITERATOR) - The `po_next_message' function returns the next message from - ITERATOR and advances the iterator. It returns `NULL' when the - iterator has reached the end of its message list. - - The following functions returns details of a `po_message_t'. Recall -that the results are valid as long as the FILE handle is valid. - - -- Function: const char * po_message_msgid (po_message_t MESSAGE) - The `po_message_msgid' function returns the `msgid' (untranslated - English string) of a message. This is guaranteed to be non-`NULL'. - - -- Function: const char * po_message_msgid_plural (po_message_t - MESSAGE) - The `po_message_msgid_plural' function returns the `msgid_plural' - (untranslated English plural string) of a message with plurals, or - `NULL' for a message without plural. - - -- Function: const char * po_message_msgstr (po_message_t MESSAGE) - The `po_message_msgstr' function returns the `msgstr' (translation) - of a message. For an untranslated message, the return value is an - empty string. - - -- Function: const char * po_message_msgstr_plural (po_message_t - MESSAGE, int INDEX) - The `po_message_msgstr_plural' function returns the - `msgstr[INDEX]' of a message with plurals, or `NULL' when the - INDEX is out of range or for a message without plural. - - Here is an example code how these functions can be used. - - const char *filename = ...; - po_file_t file = po_file_read (filename); - - if (file == NULL) - error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename); - { - const char * const *domains = po_file_domains (file); - const char * const *domainp; - - for (domainp = domains; *domainp; domainp++) - { - const char *domain = *domainp; - po_message_iterator_t iterator = po_message_iterator (file, domain); - - for (;;) - { - po_message_t *message = po_next_message (iterator); - - if (message == NULL) - break; - { - const char *msgid = po_message_msgid (message); - const char *msgstr = po_message_msgstr (message); - - ... - } - } - po_message_iterator_free (iterator); - } - } - po_file_free (file); - - -File: gettext.info, Node: Binaries, Next: Programmers, Prev: Manipulating, Up: Top - -10 Producing Binary MO Files -**************************** - -* Menu: - -* msgfmt Invocation:: Invoking the `msgfmt' Program -* msgunfmt Invocation:: Invoking the `msgunfmt' Program -* MO Files:: The Format of GNU MO Files - - -File: gettext.info, Node: msgfmt Invocation, Next: msgunfmt Invocation, Prev: Binaries, Up: Binaries - -10.1 Invoking the `msgfmt' Program -================================== - - msgfmt [OPTION] FILENAME.po ... - - The `msgfmt' programs generates a binary message catalog from a -textual translation description. - -10.1.1 Input file location --------------------------- - -`FILENAME.po ...' - -`-D DIRECTORY' -`--directory=DIRECTORY' - Add DIRECTORY to the list of directories. Source files are - searched relative to this list of directories. The resulting `.po' - file will be written relative to the current directory, though. - - - If an input file is `-', standard input is read. - -10.1.2 Operation mode ---------------------- - -`-j' -`--java' - Java mode: generate a Java `ResourceBundle' class. - -`--java2' - Like -java, and assume Java2 (JDK 1.2 or higher). - -`--csharp' - C# mode: generate a .NET .dll file containing a subclass of - `GettextResourceSet'. - -`--csharp-resources' - C# resources mode: generate a .NET `.resources' file. - -`--tcl' - Tcl mode: generate a tcl/msgcat `.msg' file. - -`--qt' - Qt mode: generate a Qt `.qm' file. - - -10.1.3 Output file location ---------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified file. - -`--strict' - Direct the program to work strictly following the Uniforum/Sun - implementation. Currently this only affects the naming of the - output file. If this option is not given the name of the output - file is the same as the domain name. If the strict Uniforum mode - is enabled the suffix `.mo' is added to the file name if it is not - already present. - - We find this behaviour of Sun's implementation rather silly and so - by default this mode is _not_ selected. - - - If the output FILE is `-', output is written to standard output. - -10.1.4 Output file location in Java mode ----------------------------------------- - -`-r RESOURCE' -`--resource=RESOURCE' - Specify the resource name. - -`-l LOCALE' -`--locale=LOCALE' - Specify the locale name, either a language specification of the - form LL or a combined language and country specification of the - form LL_CC. - -`-d DIRECTORY' - Specify the base directory of classes directory hierarchy. - - - The class name is determined by appending the locale name to the -resource name, separated with an underscore. The `-d' option is -mandatory. The class is written under the specified directory. - -10.1.5 Output file location in C# mode --------------------------------------- - -`-r RESOURCE' -`--resource=RESOURCE' - Specify the resource name. - -`-l LOCALE' -`--locale=LOCALE' - Specify the locale name, either a language specification of the - form LL or a combined language and country specification of the - form LL_CC. - -`-d DIRECTORY' - Specify the base directory for locale dependent `.dll' files. - - - The `-l' and `-d' options are mandatory. The `.dll' file is written -in a subdirectory of the specified directory whose name depends on the -locale. - -10.1.6 Output file location in Tcl mode ---------------------------------------- - -`-l LOCALE' -`--locale=LOCALE' - Specify the locale name, either a language specification of the - form LL or a combined language and country specification of the - form LL_CC. - -`-d DIRECTORY' - Specify the base directory of `.msg' message catalogs. - - - The `-l' and `-d' options are mandatory. The `.msg' file is written -in the specified directory. - -10.1.7 Input file syntax ------------------------- - -`-P' -`--properties-input' - Assume the input files are Java ResourceBundles in Java - `.properties' syntax, not in PO file syntax. - -`--stringtable-input' - Assume the input files are NeXTstep/GNUstep localized resource - files in `.strings' syntax, not in PO file syntax. - - -10.1.8 Input file interpretation --------------------------------- - -`-c' -`--check' - Perform all the checks implied by `--check-format', - `--check-header', `--check-domain'. - -`--check-format' - Check language dependent format strings. - - If the string represents a format string used in a `printf'-like - function both strings should have the same number of `%' format - specifiers, with matching types. If the flag `c-format' or - `possible-c-format' appears in the special comment <#,> for this - entry a check is performed. For example, the check will diagnose - using `%.*s' against `%s', or `%d' against `%s', or `%d' against - `%x'. It can even handle positional parameters. - - Normally the `xgettext' program automatically decides whether a - string is a format string or not. This algorithm is not perfect, - though. It might regard a string as a format string though it is - not used in a `printf'-like function and so `msgfmt' might report - errors where there are none. - - To solve this problem the programmer can dictate the decision to - the `xgettext' program (*note c-format::). The translator should - not consider removing the flag from the <#,> line. This "fix" - would be reversed again as soon as `msgmerge' is called the next - time. - -`--check-header' - Verify presence and contents of the header entry. *Note Header - Entry::, for a description of the various fields in the header - entry. - -`--check-domain' - Check for conflicts between domain directives and the - `--output-file' option - -`-C' -`--check-compatibility' - Check that GNU msgfmt behaves like X/Open msgfmt. This will give - an error when attempting to use the GNU extensions. - -`--check-accelerators[=CHAR]' - Check presence of keyboard accelerators for menu items. This is - based on the convention used in some GUIs that a keyboard - accelerator in a menu item string is designated by an immediately - preceding `&' character. Sometimes a keyboard accelerator is also - called "keyboard mnemonic". This check verifies that if the - untranslated string has exactly one `&' character, the translated - string has exactly one `&' as well. If this option is given with - a CHAR argument, this CHAR should be a non-alphanumeric character - and is used as keyboard accelerator mark instead of `&'. - -`-f' -`--use-fuzzy' - Use fuzzy entries in output. Note that using this option is - usually wrong, because fuzzy messages are exactly those which have - not been validated by a human translator. - - -10.1.9 Output details ---------------------- - -`-a NUMBER' -`--alignment=NUMBER' - Align strings to NUMBER bytes (default: 1). - -`--no-hash' - Don't include a hash table in the binary file. Lookup will be - more expensive at run time (binary search instead of hash table - lookup). - - -10.1.10 Informative output --------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - -`--statistics' - Print statistics about translations. When the option `--verbose' - is used in combination with `--statistics', the input file name is - printed in front of the statistics line. - -`-v' -`--verbose' - Increase verbosity level. - - - -File: gettext.info, Node: msgunfmt Invocation, Next: MO Files, Prev: msgfmt Invocation, Up: Binaries - -10.2 Invoking the `msgunfmt' Program -==================================== - - msgunfmt [OPTION] [FILE]... - - The `msgunfmt' program converts a binary message catalog to a -Uniforum style .po file. - -10.2.1 Operation mode ---------------------- - -`-j' -`--java' - Java mode: input is a Java `ResourceBundle' class. - -`--csharp' - C# mode: input is a .NET .dll file containing a subclass of - `GettextResourceSet'. - -`--csharp-resources' - C# resources mode: input is a .NET `.resources' file. - -`--tcl' - Tcl mode: input is a tcl/msgcat `.msg' file. - - -10.2.2 Input file location --------------------------- - -`FILE ...' - Input .mo files. - - - If no input FILE is given or if it is `-', standard input is read. - -10.2.3 Input file location in Java mode ---------------------------------------- - -`-r RESOURCE' -`--resource=RESOURCE' - Specify the resource name. - -`-l LOCALE' -`--locale=LOCALE' - Specify the locale name, either a language specification of the - form LL or a combined language and country specification of the - form LL_CC. - - - The class name is determined by appending the locale name to the -resource name, separated with an underscore. The class is located -using the `CLASSPATH'. - -10.2.4 Input file location in C# mode -------------------------------------- - -`-r RESOURCE' -`--resource=RESOURCE' - Specify the resource name. - -`-l LOCALE' -`--locale=LOCALE' - Specify the locale name, either a language specification of the - form LL or a combined language and country specification of the - form LL_CC. - -`-d DIRECTORY' - Specify the base directory for locale dependent `.dll' files. - - - The `-l' and `-d' options are mandatory. The `.msg' file is located -in a subdirectory of the specified directory whose name depends on the -locale. - -10.2.5 Input file location in Tcl mode --------------------------------------- - -`-l LOCALE' -`--locale=LOCALE' - Specify the locale name, either a language specification of the - form LL or a combined language and country specification of the - form LL_CC. - -`-d DIRECTORY' - Specify the base directory of `.msg' message catalogs. - - - The `-l' and `-d' options are mandatory. The `.msg' file is located -in the specified directory. - -10.2.6 Output file location ---------------------------- - -`-o FILE' -`--output-file=FILE' - Write output to specified file. - - - The results are written to standard output if no output file is -specified or if it is `-'. - -10.2.7 Output details ---------------------- - -`--color' -`--color=WHEN' - Specify whether or when to use colors and other text attributes. - See *note The --color option:: for details. - -`--style=STYLE_FILE' - Specify the CSS style rule file to use for `--color'. See *note - The --style option:: for details. - -`--force-po' - Always write an output file even if it contains no message. - -`-i' -`--indent' - Write the .po file using indented style. - -`--strict' - Write out a strict Uniforum conforming PO file. Note that this - Uniforum format should be avoided because it doesn't support the - GNU extensions. - -`-p' -`--properties-output' - Write out a Java ResourceBundle in Java `.properties' syntax. Note - that this file format doesn't support plural forms and silently - drops obsolete messages. - -`--stringtable-output' - Write out a NeXTstep/GNUstep localized resource file in `.strings' - syntax. Note that this file format doesn't support plural forms. - -`-w NUMBER' -`--width=NUMBER' - Set the output page width. Long strings in the output files will - be split across multiple lines in order to ensure that each line's - width (= number of screen columns) is less or equal to the given - NUMBER. - -`--no-wrap' - Do not break long message lines. Message lines whose width - exceeds the output page width will not be split into several - lines. Only file reference lines which are wider than the output - page width will be split. - -`-s' -`--sort-output' - Generate sorted output. Note that using this option makes it much - harder for the translator to understand each message's context. - - -10.2.8 Informative output -------------------------- - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - -`-v' -`--verbose' - Increase verbosity level. - - - -File: gettext.info, Node: MO Files, Prev: msgunfmt Invocation, Up: Binaries - -10.3 The Format of GNU MO Files -=============================== - - The format of the generated MO files is best described by a picture, -which appears below. - - The first two words serve the identification of the file. The magic -number will always signal GNU MO files. The number is stored in the -byte order of the generating machine, so the magic number really is two -numbers: `0x950412de' and `0xde120495'. - - The second word describes the current revision of the file format, -composed of a major and a minor revision number. The revision numbers -ensure that the readers of MO files can distinguish new formats from -old ones and handle their contents, as far as possible. For now the -major revision is 0 or 1, and the minor revision is also 0 or 1. More -revisions might be added in the future. A program seeing an unexpected -major revision number should stop reading the MO file entirely; whereas -an unexpected minor revision number means that the file can be read but -will not reveal its full contents, when parsed by a program that -supports only smaller minor revision numbers. - - The version is kept separate from the magic number, instead of using -different magic numbers for different formats, mainly because -`/etc/magic' is not updated often. - - Follow a number of pointers to later tables in the file, allowing -for the extension of the prefix part of MO files without having to -recompile programs reading them. This might become useful for later -inserting a few flag bits, indication about the charset used, new -tables, or other things. - - Then, at offset O and offset T in the picture, two tables of string -descriptors can be found. In both tables, each string descriptor uses -two 32 bits integers, one for the string length, another for the offset -of the string in the MO file, counting in bytes from the start of the -file. The first table contains descriptors for the original strings, -and is sorted so the original strings are in increasing lexicographical -order. The second table contains descriptors for the translated -strings, and is parallel to the first table: to find the corresponding -translation one has to access the array slot in the second array with -the same index. - - Having the original strings sorted enables the use of simple binary -search, for when the MO file does not contain an hashing table, or for -when it is not practical to use the hashing table provided in the MO -file. This also has another advantage, as the empty string in a PO -file GNU `gettext' is usually _translated_ into some system information -attached to that particular MO file, and the empty string necessarily -becomes the first in both the original and translated tables, making -the system information very easy to find. - - The size S of the hash table can be zero. In this case, the hash -table itself is not contained in the MO file. Some people might prefer -this because a precomputed hashing table takes disk space, and does not -win _that_ much speed. The hash table contains indices to the sorted -array of strings in the MO file. Conflict resolution is done by double -hashing. The precise hashing algorithm used is fairly dependent on GNU -`gettext' code, and is not documented here. - - As for the strings themselves, they follow the hash file, and each -is terminated with a <NUL>, and this <NUL> is not counted in the length -which appears in the string descriptor. The `msgfmt' program has an -option selecting the alignment for MO file strings. With this option, -each string is separately aligned so it starts at an offset which is a -multiple of the alignment value. On some RISC machines, a correct -alignment will speed things up. - - Contexts are stored by storing the concatenation of the context, a -<EOT> byte, and the original string, instead of the original string. - - Plural forms are stored by letting the plural of the original string -follow the singular of the original string, separated through a <NUL> -byte. The length which appears in the string descriptor includes both. -However, only the singular of the original string takes part in the -hash table lookup. The plural variants of the translation are all -stored consecutively, separated through a <NUL> byte. Here also, the -length in the string descriptor includes all of them. - - Nothing prevents a MO file from having embedded <NUL>s in strings. -However, the program interface currently used already presumes that -strings are <NUL> terminated, so embedded <NUL>s are somewhat useless. -But the MO file format is general enough so other interfaces would be -later possible, if for example, we ever want to implement wide -characters right in MO files, where <NUL> bytes may accidentally -appear. (No, we don't want to have wide characters in MO files. They -would make the file unnecessarily large, and the `wchar_t' type being -platform dependent, MO files would be platform dependent as well.) - - This particular issue has been strongly debated in the GNU `gettext' -development forum, and it is expectable that MO file format will evolve -or change over time. It is even possible that many formats may later -be supported concurrently. But surely, we have to start somewhere, and -the MO file format described here is a good start. Nothing is cast in -concrete, and the format may later evolve fairly easily, so we should -feel comfortable with the current approach. - - byte - +------------------------------------------+ - 0 | magic number = 0x950412de | - | | - 4 | file format revision = 0 | - | | - 8 | number of strings | == N - | | - 12 | offset of table with original strings | == O - | | - 16 | offset of table with translation strings | == T - | | - 20 | size of hashing table | == S - | | - 24 | offset of hashing table | == H - | | - . . - . (possibly more entries later) . - . . - | | - O | length & offset 0th string ----------------. - O + 8 | length & offset 1st string ------------------. - ... ... | | - O + ((N-1)*8)| length & offset (N-1)th string | | | - | | | | - T | length & offset 0th translation ---------------. - T + 8 | length & offset 1st translation -----------------. - ... ... | | | | - T + ((N-1)*8)| length & offset (N-1)th translation | | | | | - | | | | | | - H | start hash table | | | | | - ... ... | | | | - H + S * 4 | end hash table | | | | | - | | | | | | - | NUL terminated 0th string <----------------' | | | - | | | | | - | NUL terminated 1st string <------------------' | | - | | | | - ... ... | | - | | | | - | NUL terminated 0th translation <---------------' | - | | | - | NUL terminated 1st translation <-----------------' - | | - ... ... - | | - +------------------------------------------+ - - -File: gettext.info, Node: Programmers, Next: Translators, Prev: Binaries, Up: Top - -11 The Programmer's View -************************ - - One aim of the current message catalog implementation provided by -GNU `gettext' was to use the system's message catalog handling, if the -installer wishes to do so. So we perhaps should first take a look at -the solutions we know about. The people in the POSIX committee did not -manage to agree on one of the semi-official standards which we'll -describe below. In fact they couldn't agree on anything, so they -decided only to include an example of an interface. The major Unix -vendors are split in the usage of the two most important -specifications: X/Open's catgets vs. Uniforum's gettext interface. -We'll describe them both and later explain our solution of this dilemma. - -* Menu: - -* catgets:: About `catgets' -* gettext:: About `gettext' -* Comparison:: Comparing the two interfaces -* Using libintl.a:: Using libintl.a in own programs -* gettext grok:: Being a `gettext' grok -* Temp Programmers:: Temporary Notes for the Programmers Chapter - - -File: gettext.info, Node: catgets, Next: gettext, Prev: Programmers, Up: Programmers - -11.1 About `catgets' -==================== - - The `catgets' implementation is defined in the X/Open Portability -Guide, Volume 3, XSI Supplementary Definitions, Chapter 5. But the -process of creating this standard seemed to be too slow for some of the -Unix vendors so they created their implementations on preliminary -versions of the standard. Of course this leads again to problems while -writing platform independent programs: even the usage of `catgets' does -not guarantee a unique interface. - - Another, personal comment on this that only a bunch of committee -members could have made this interface. They never really tried to -program using this interface. It is a fast, memory-saving -implementation, an user can happily live with it. But programmers hate -it (at least I and some others do...) - - But we must not forget one point: after all the trouble with -transferring the rights on Unix(tm) they at last came to X/Open, the -very same who published this specification. This leads me to making -the prediction that this interface will be in future Unix standards -(e.g. Spec1170) and therefore part of all Unix implementation -(implementations, which are _allowed_ to wear this name). - -* Menu: - -* Interface to catgets:: The interface -* Problems with catgets:: Problems with the `catgets' interface?! - - -File: gettext.info, Node: Interface to catgets, Next: Problems with catgets, Prev: catgets, Up: catgets - -11.1.1 The Interface --------------------- - - The interface to the `catgets' implementation consists of three -functions which correspond to those used in file access: `catopen' to -open the catalog for using, `catgets' for accessing the message tables, -and `catclose' for closing after work is done. Prototypes for the -functions and the needed definitions are in the `<nl_types.h>' header -file. - - `catopen' is used like in this: - - nl_catd catd = catopen ("catalog_name", 0); - - The function takes as the argument the name of the catalog. This -usual refers to the name of the program or the package. The second -parameter is not further specified in the standard. I don't even know -whether it is implemented consistently among various systems. So the -common advice is to use `0' as the value. The return value is a handle -to the message catalog, equivalent to handles to file returned by -`open'. - - This handle is of course used in the `catgets' function which can be -used like this: - - char *translation = catgets (catd, set_no, msg_id, "original string"); - - The first parameter is this catalog descriptor. The second parameter -specifies the set of messages in this catalog, in which the message -described by `msg_id' is obtained. `catgets' therefore uses a -three-stage addressing: - - catalog name => set number => message ID => translation - - The fourth argument is not used to address the translation. It is -given as a default value in case when one of the addressing stages -fail. One important thing to remember is that although the return type -of catgets is `char *' the resulting string _must not_ be changed. It -should better be `const char *', but the standard is published in 1988, -one year before ANSI C. - -The last of these functions is used and behaves as expected: - - catclose (catd); - - After this no `catgets' call using the descriptor is legal anymore. - - -File: gettext.info, Node: Problems with catgets, Prev: Interface to catgets, Up: catgets - -11.1.2 Problems with the `catgets' Interface?! ----------------------------------------------- - - Now that this description seemed to be really easy -- where are the -problems we speak of? In fact the interface could be used in a -reasonable way, but constructing the message catalogs is a pain. The -reason for this lies in the third argument of `catgets': the unique -message ID. This has to be a numeric value for all messages in a single -set. Perhaps you could imagine the problems keeping such a list while -changing the source code. Add a new message here, remove one there. Of -course there have been developed a lot of tools helping to organize this -chaos but one as the other fails in one aspect or the other. We don't -want to say that the other approach has no problems but they are far -more easy to manage. - - -File: gettext.info, Node: gettext, Next: Comparison, Prev: catgets, Up: Programmers - -11.2 About `gettext' -==================== - - The definition of the `gettext' interface comes from a Uniforum -proposal. It was submitted there by Sun, who had implemented the -`gettext' function in SunOS 4, around 1990. Nowadays, the `gettext' -interface is specified by the OpenI18N standard. - - The main point about this solution is that it does not follow the -method of normal file handling (open-use-close) and that it does not -burden the programmer with so many tasks, especially the unique key -handling. Of course here also a unique key is needed, but this key is -the message itself (how long or short it is). See *note Comparison:: -for a more detailed comparison of the two methods. - - The following section contains a rather detailed description of the -interface. We make it that detailed because this is the interface we -chose for the GNU `gettext' Library. Programmers interested in using -this library will be interested in this description. - -* Menu: - -* Interface to gettext:: The interface -* Ambiguities:: Solving ambiguities -* Locating Catalogs:: Locating message catalog files -* Charset conversion:: How to request conversion to Unicode -* Contexts:: Solving ambiguities in GUI programs -* Plural forms:: Additional functions for handling plurals -* Optimized gettext:: Optimization of the *gettext functions - - -File: gettext.info, Node: Interface to gettext, Next: Ambiguities, Prev: gettext, Up: gettext - -11.2.1 The Interface --------------------- - - The minimal functionality an interface must have is a) to select a -domain the strings are coming from (a single domain for all programs is -not reasonable because its construction and maintenance is difficult, -perhaps impossible) and b) to access a string in a selected domain. - - This is principally the description of the `gettext' interface. It -has a global domain which unqualified usages reference. Of course this -domain is selectable by the user. - - char *textdomain (const char *domain_name); - - This provides the possibility to change or query the current status -of the current global domain of the `LC_MESSAGE' category. The -argument is a null-terminated string, whose characters must be legal in -the use in filenames. If the DOMAIN_NAME argument is `NULL', the -function returns the current value. If no value has been set before, -the name of the default domain is returned: _messages_. Please note -that although the return value of `textdomain' is of type `char *' no -changing is allowed. It is also important to know that no checks of -the availability are made. If the name is not available you will see -this by the fact that no translations are provided. - -To use a domain set by `textdomain' the function - - char *gettext (const char *msgid); - -is to be used. This is the simplest reasonable form one can imagine. -The translation of the string MSGID is returned if it is available in -the current domain. If it is not available, the argument itself is -returned. If the argument is `NULL' the result is undefined. - - One thing which should come into mind is that no explicit dependency -to the used domain is given. The current value of the domain is used. -If this changes between two executions of the same `gettext' call in -the program, both calls reference a different message catalog. - - For the easiest case, which is normally used in internationalized -packages, once at the beginning of execution a call to `textdomain' is -issued, setting the domain to a unique name, normally the package name. -In the following code all strings which have to be translated are -filtered through the gettext function. That's all, the package speaks -your language. - - -File: gettext.info, Node: Ambiguities, Next: Locating Catalogs, Prev: Interface to gettext, Up: gettext - -11.2.2 Solving Ambiguities --------------------------- - - While this single name domain works well for most applications there -might be the need to get translations from more than one domain. Of -course one could switch between different domains with calls to -`textdomain', but this is really not convenient nor is it fast. A -possible situation could be one case subject to discussion during this -writing: all error messages of functions in the set of common used -functions should go into a separate domain `error'. By this mean we -would only need to translate them once. Another case are messages from -a library, as these _have_ to be independent of the current domain set -by the application. - -For this reasons there are two more functions to retrieve strings: - - char *dgettext (const char *domain_name, const char *msgid); - char *dcgettext (const char *domain_name, const char *msgid, - int category); - - Both take an additional argument at the first place, which -corresponds to the argument of `textdomain'. The third argument of -`dcgettext' allows to use another locale category but `LC_MESSAGES'. -But I really don't know where this can be useful. If the DOMAIN_NAME -is `NULL' or CATEGORY has an value beside the known ones, the result is -undefined. It should also be noted that this function is not part of -the second known implementation of this function family, the one found -in Solaris. - - A second ambiguity can arise by the fact, that perhaps more than one -domain has the same name. This can be solved by specifying where the -needed message catalog files can be found. - - char *bindtextdomain (const char *domain_name, - const char *dir_name); - - Calling this function binds the given domain to a file in the -specified directory (how this file is determined follows below). -Especially a file in the systems default place is not favored against -the specified file anymore (as it would be by solely using -`textdomain'). A `NULL' pointer for the DIR_NAME parameter returns the -binding associated with DOMAIN_NAME. If DOMAIN_NAME itself is `NULL' -nothing happens and a `NULL' pointer is returned. Here again as for -all the other functions is true that none of the return value must be -changed! - - It is important to remember that relative path names for the -DIR_NAME parameter can be trouble. Since the path is always computed -relative to the current directory different results will be achieved -when the program executes a `chdir' command. Relative paths should -always be avoided to avoid dependencies and unreliabilities. - - -File: gettext.info, Node: Locating Catalogs, Next: Charset conversion, Prev: Ambiguities, Up: gettext - -11.2.3 Locating Message Catalog Files -------------------------------------- - - Because many different languages for many different packages have to -be stored we need some way to add these information to file message -catalog files. The way usually used in Unix environments is have this -encoding in the file name. This is also done here. The directory name -given in `bindtextdomain's second argument (or the default directory), -followed by the name of the locale, the locale category, and the domain -name are concatenated: - - DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo - - The default value for DIR_NAME is system specific. For the GNU -library, and for packages adhering to its conventions, it's: - /usr/local/share/locale - -LOCALE is the name of the locale category which is designated by -`LC_CATEGORY'. For `gettext' and `dgettext' this `LC_CATEGORY' is -always `LC_MESSAGES'.(1) The name of the locale category is determined -through `setlocale (LC_CATEGORY, NULL)'. (2) When using the function -`dcgettext', you can specify the locale category through the third -argument. - - ---------- Footnotes ---------- - - (1) Some system, e.g. mingw, don't have `LC_MESSAGES'. Here we use -a more or less arbitrary value for it, namely 1729, the smallest -positive integer which can be represented in two different ways as the -sum of two cubes. - - (2) When the system does not support `setlocale' its behavior in -setting the locale values is simulated by looking at the environment -variables. - - -File: gettext.info, Node: Charset conversion, Next: Contexts, Prev: Locating Catalogs, Up: gettext - -11.2.4 How to specify the output character set `gettext' uses -------------------------------------------------------------- - - `gettext' not only looks up a translation in a message catalog. It -also converts the translation on the fly to the desired output character -set. This is useful if the user is working in a different character set -than the translator who created the message catalog, because it avoids -distributing variants of message catalogs which differ only in the -character set. - - The output character set is, by default, the value of `nl_langinfo -(CODESET)', which depends on the `LC_CTYPE' part of the current locale. -But programs which store strings in a locale independent way (e.g. -UTF-8) can request that `gettext' and related functions return the -translations in that encoding, by use of the `bind_textdomain_codeset' -function. - - Note that the MSGID argument to `gettext' is not subject to -character set conversion. Also, when `gettext' does not find a -translation for MSGID, it returns MSGID unchanged - independently of -the current output character set. It is therefore recommended that all -MSGIDs be US-ASCII strings. - - -- Function: char * bind_textdomain_codeset (const char *DOMAINNAME, - const char *CODESET) - The `bind_textdomain_codeset' function can be used to specify the - output character set for message catalogs for domain DOMAINNAME. - The CODESET argument must be a valid codeset name which can be used - for the `iconv_open' function, or a null pointer. - - If the CODESET parameter is the null pointer, - `bind_textdomain_codeset' returns the currently selected codeset - for the domain with the name DOMAINNAME. It returns `NULL' if no - codeset has yet been selected. - - The `bind_textdomain_codeset' function can be used several times. - If used multiple times with the same DOMAINNAME argument, the - later call overrides the settings made by the earlier one. - - The `bind_textdomain_codeset' function returns a pointer to a - string containing the name of the selected codeset. The string is - allocated internally in the function and must not be changed by the - user. If the system went out of core during the execution of - `bind_textdomain_codeset', the return value is `NULL' and the - global variable ERRNO is set accordingly. - - -File: gettext.info, Node: Contexts, Next: Plural forms, Prev: Charset conversion, Up: gettext - -11.2.5 Using contexts for solving ambiguities ---------------------------------------------- - - One place where the `gettext' functions, if used normally, have big -problems is within programs with graphical user interfaces (GUIs). The -problem is that many of the strings which have to be translated are very -short. They have to appear in pull-down menus which restricts the -length. But strings which are not containing entire sentences or at -least large fragments of a sentence may appear in more than one -situation in the program but might have different translations. This is -especially true for the one-word strings which are frequently used in -GUI programs. - - As a consequence many people say that the `gettext' approach is -wrong and instead `catgets' should be used which indeed does not have -this problem. But there is a very simple and powerful method to handle -this kind of problems with the `gettext' functions. - - Contexts can be added to strings to be translated. A context -dependent translation lookup is when a translation for a given string -is searched, that is limited to a given context. The translation for -the same string in a different context can be different. The different -translations of the same string in different contexts can be stored in -the in the same MO file, and can be edited by the translator in the -same PO file. - - The `gettext.h' include file contains the lookup macros for strings -with contexts. They are implemented as thin macros and inline functions -over the functions from `<libintl.h>'. - - const char *pgettext (const char *msgctxt, const char *msgid); - - In a call of this macro, MSGCTXT and MSGID must be string literals. -The macro returns the translation of MSGID, restricted to the context -given by MSGCTXT. - - The MSGCTXT string is visible in the PO file to the translator. You -should try to make it somehow canonical and never changing. Because -every time you change an MSGCTXT, the translator will have to review -the translation of MSGID. - - Finding a canonical MSGCTXT string that doesn't change over time can -be hard. But you shouldn't use the file name or class name containing -the `pgettext' call - because it is a common development task to rename -a file or a class, and it shouldn't cause translator work. Also you -shouldn't use a comment in the form of a complete English sentence as -MSGCTXT - because orthography or grammar changes are often applied to -such sentences, and again, it shouldn't force the translator to do a -review. - - The `p' in `pgettext' stands for "particular": `pgettext' fetches a -particular translation of the MSGID. - - const char *dpgettext (const char *domain_name, - const char *msgctxt, const char *msgid); - const char *dcpgettext (const char *domain_name, - const char *msgctxt, const char *msgid, - int category); - - These are generalizations of `pgettext'. They behave similarly to -`dgettext' and `dcgettext', respectively. The DOMAIN_NAME argument -defines the translation domain. The CATEGORY argument allows to use -another locale category than `LC_MESSAGES'. - - As as example consider the following fictional situation. A GUI -program has a menu bar with the following entries: - - +------------+------------+--------------------------------------+ - | File | Printer | | - +------------+------------+--------------------------------------+ - | Open | | Select | - | New | | Open | - +----------+ | Connect | - +----------+ - - To have the strings `File', `Printer', `Open', `New', `Select', and -`Connect' translated there has to be at some point in the code a call -to a function of the `gettext' family. But in two places the string -passed into the function would be `Open'. The translations might not -be the same and therefore we are in the dilemma described above. - - What distinguishes the two places is the menu path from the menu -root to the particular menu entries: - - Menu|File - Menu|Printer - Menu|File|Open - Menu|File|New - Menu|Printer|Select - Menu|Printer|Open - Menu|Printer|Connect - - The context is thus the menu path without its last part. So, the -calls look like this: - - pgettext ("Menu|", "File") - pgettext ("Menu|", "Printer") - pgettext ("Menu|File|", "Open") - pgettext ("Menu|File|", "New") - pgettext ("Menu|Printer|", "Select") - pgettext ("Menu|Printer|", "Open") - pgettext ("Menu|Printer|", "Connect") - - Whether or not to use the `|' character at the end of the context is -a matter of style. - - For more complex cases, where the MSGCTXT or MSGID are not string -literals, more general macros are available: - - const char *pgettext_expr (const char *msgctxt, const char *msgid); - const char *dpgettext_expr (const char *domain_name, - const char *msgctxt, const char *msgid); - const char *dcpgettext_expr (const char *domain_name, - const char *msgctxt, const char *msgid, - int category); - - Here MSGCTXT and MSGID can be arbitrary string-valued expressions. -These macros are more general. But in the case that both argument -expressions are string literals, the macros without the `_expr' suffix -are more efficient. - - -File: gettext.info, Node: Plural forms, Next: Optimized gettext, Prev: Contexts, Up: gettext - -11.2.6 Additional functions for plural forms --------------------------------------------- - - The functions of the `gettext' family described so far (and all the -`catgets' functions as well) have one problem in the real world which -have been neglected completely in all existing approaches. What is -meant here is the handling of plural forms. - - Looking through Unix source code before the time anybody thought -about internationalization (and, sadly, even afterwards) one can often -find code similar to the following: - - printf ("%d file%s deleted", n, n == 1 ? "" : "s"); - -After the first complaints from people internationalizing the code -people either completely avoided formulations like this or used strings -like `"file(s)"'. Both look unnatural and should be avoided. First -tries to solve the problem correctly looked like this: - - if (n == 1) - printf ("%d file deleted", n); - else - printf ("%d files deleted", n); - - But this does not solve the problem. It helps languages where the -plural form of a noun is not simply constructed by adding an `s' but -that is all. Once again people fell into the trap of believing the -rules their language is using are universal. But the handling of plural -forms differs widely between the language families. For example, Rafal -Maszkowski `<rzm@mat.uni.torun.pl>' reports: - - In Polish we use e.g. plik (file) this way: - 1 plik - 2,3,4 pliki - 5-21 pliko'w - 22-24 pliki - 25-31 pliko'w - and so on (o' means 8859-2 oacute which should be rather okreska, - similar to aogonek). - - There are two things which can differ between languages (and even -inside language families); - - * The form how plural forms are built differs. This is a problem - with languages which have many irregularities. German, for - instance, is a drastic case. Though English and German are part - of the same language family (Germanic), the almost regular forming - of plural noun forms (appending an `s') is hardly found in German. - - * The number of plural forms differ. This is somewhat surprising for - those who only have experiences with Romanic and Germanic languages - since here the number is the same (there are two). - - But other language families have only one form or many forms. More - information on this in an extra section. - - The consequence of this is that application writers should not try to -solve the problem in their code. This would be localization since it is -only usable for certain, hardcoded language environments. Instead the -extended `gettext' interface should be used. - - These extra functions are taking instead of the one key string two -strings and a numerical argument. The idea behind this is that using -the numerical argument and the first string as a key, the implementation -can select using rules specified by the translator the right plural -form. The two string arguments then will be used to provide a return -value in case no message catalog is found (similar to the normal -`gettext' behavior). In this case the rules for Germanic language is -used and it is assumed that the first string argument is the singular -form, the second the plural form. - - This has the consequence that programs without language catalogs can -display the correct strings only if the program itself is written using -a Germanic language. This is a limitation but since the GNU C library -(as well as the GNU `gettext' package) are written as part of the GNU -package and the coding standards for the GNU project require program -being written in English, this solution nevertheless fulfills its -purpose. - - -- Function: char * ngettext (const char *MSGID1, const char *MSGID2, - unsigned long int N) - The `ngettext' function is similar to the `gettext' function as it - finds the message catalogs in the same way. But it takes two - extra arguments. The MSGID1 parameter must contain the singular - form of the string to be converted. It is also used as the key - for the search in the catalog. The MSGID2 parameter is the plural - form. The parameter N is used to determine the plural form. If no - message catalog is found MSGID1 is returned if `n == 1', otherwise - `msgid2'. - - An example for the use of this function is: - - printf (ngettext ("%d file removed", "%d files removed", n), n); - - Please note that the numeric value N has to be passed to the - `printf' function as well. It is not sufficient to pass it only to - `ngettext'. - - In the English singular case, the number - always 1 - can be - replaced with "one": - - printf (ngettext ("One file removed", "%d files removed", n), n); - - This works because the `printf' function discards excess arguments - that are not consumed by the format string. - - If this function is meant to yield a format string that takes two - or more arguments, you can not use it like this: - - printf (ngettext ("%d file removed from directory %s", - "%d files removed from directory %s", - n, dir), - n); - - because in many languages the translators want to replace the `%d' - with an explicit word in the singular case, just like "one" in - English, and C format strings cannot consume the second argument - but skip the first argument. Instead, you have to reorder the - arguments so that `n' comes last: - - printf (ngettext ("%$2d file removed from directory %$1s", - "%$2d files removed from directory %$1s", - dir, n), - n); - - See *note c-format:: for details about this argument reordering - syntax. - - When you know that the value of `n' is within a given range, you - can specify it as a comment directed to the `xgettext' tool. This - information may help translators to use more adequate - translations. Like this: - - if (days > 7 && days < 14) - /* xgettext: range: 1..6 */ - printf (ngettext ("one week and one day", "one week and %d days", - days - 7), - days - 7); - - It is also possible to use this function when the strings don't - contain a cardinal number: - - puts (ngettext ("Delete the selected file?", - "Delete the selected files?", - n)); - - In this case the number N is only used to choose the plural form. - - -- Function: char * dngettext (const char *DOMAIN, const char *MSGID1, - const char *MSGID2, unsigned long int N) - The `dngettext' is similar to the `dgettext' function in the way - the message catalog is selected. The difference is that it takes - two extra parameter to provide the correct plural form. These two - parameters are handled in the same way `ngettext' handles them. - - -- Function: char * dcngettext (const char *DOMAIN, const char - *MSGID1, const char *MSGID2, unsigned long int N, int - CATEGORY) - The `dcngettext' is similar to the `dcgettext' function in the way - the message catalog is selected. The difference is that it takes - two extra parameter to provide the correct plural form. These two - parameters are handled in the same way `ngettext' handles them. - - Now, how do these functions solve the problem of the plural forms? -Without the input of linguists (which was not available) it was not -possible to determine whether there are only a few different forms in -which plural forms are formed or whether the number can increase with -every new supported language. - - Therefore the solution implemented is to allow the translator to -specify the rules of how to select the plural form. Since the formula -varies with every language this is the only viable solution except for -hardcoding the information in the code (which still would require the -possibility of extensions to not prevent the use of new languages). - - The information about the plural form selection has to be stored in -the header entry of the PO file (the one with the empty `msgid' string). -The plural form information looks like this: - - Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1; - - The `nplurals' value must be a decimal number which specifies how -many different plural forms exist for this language. The string -following `plural' is an expression which is using the C language -syntax. Exceptions are that no negative numbers are allowed, numbers -must be decimal, and the only variable allowed is `n'. Spaces are -allowed in the expression, but backslash-newlines are not; in the -examples below the backslash-newlines are present for formatting -purposes only. This expression will be evaluated whenever one of the -functions `ngettext', `dngettext', or `dcngettext' is called. The -numeric value passed to these functions is then substituted for all uses -of the variable `n' in the expression. The resulting value then must -be greater or equal to zero and smaller than the value given as the -value of `nplurals'. - -The following rules are known at this point. The language with families -are listed. But this does not necessarily mean the information can be -generalized for the whole family (as can be easily seen in the table -below).(1) - -Only one form: - Some languages only require one single form. There is no - distinction between the singular and plural form. An appropriate - header entry would look like this: - - Plural-Forms: nplurals=1; plural=0; - - Languages with this property include: - - Asian family - Japanese, Vietnamese, Korean - -Two forms, singular used for one only - This is the form used in most existing programs since it is what - English is using. A header entry would look like this: - - Plural-Forms: nplurals=2; plural=n != 1; - - (Note: this uses the feature of C expressions that boolean - expressions have to value zero or one.) - - Languages with this property include: - - Germanic family - English, German, Dutch, Swedish, Danish, Norwegian, Faroese - - Romanic family - Spanish, Portuguese, Italian, Bulgarian - - Latin/Greek family - Greek - - Finno-Ugric family - Finnish, Estonian - - Semitic family - Hebrew - - Artificial - Esperanto - - Other languages using the same header entry are: - - Finno-Ugric family - Hungarian - - Turkic/Altaic family - Turkish - - Hungarian does not appear to have a plural if you look at - sentences involving cardinal numbers. For example, "1 apple" is - "1 alma", and "123 apples" is "123 alma". But when the number is - not explicit, the distinction between singular and plural exists: - "the apple" is "az alma", and "the apples" is "az almák". Since - `ngettext' has to support both types of sentences, it is - classified here, under "two forms". - - The same holds for Turkish: "1 apple" is "1 elma", and "123 - apples" is "123 elma". But when the number is omitted, the - distinction between singular and plural exists: "the apple" is - "elma", and "the apples" is "elmalar". - -Two forms, singular used for zero and one - Exceptional case in the language family. The header entry would - be: - - Plural-Forms: nplurals=2; plural=n>1; - - Languages with this property include: - - Romanic family - Brazilian Portuguese, French - -Three forms, special case for zero - The header entry would be: - - Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2; - - Languages with this property include: - - Baltic family - Latvian - -Three forms, special cases for one and two - The header entry would be: - - Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2; - - Languages with this property include: - - Celtic - Gaeilge (Irish) - -Three forms, special case for numbers ending in 00 or [2-9][0-9] - The header entry would be: - - Plural-Forms: nplurals=3; \ - plural=n==1 ? 0 : (n==0 || (n%100 > 0 && n%100 < 20)) ? 1 : 2; - - Languages with this property include: - - Romanic family - Romanian - -Three forms, special case for numbers ending in 1[2-9] - The header entry would look like this: - - Plural-Forms: nplurals=3; \ - plural=n%10==1 && n%100!=11 ? 0 : \ - n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2; - - Languages with this property include: - - Baltic family - Lithuanian - -Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4] - The header entry would look like this: - - Plural-Forms: nplurals=3; \ - plural=n%10==1 && n%100!=11 ? 0 : \ - n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2; - - Languages with this property include: - - Slavic family - Russian, Ukrainian, Serbian, Croatian - -Three forms, special cases for 1 and 2, 3, 4 - The header entry would look like this: - - Plural-Forms: nplurals=3; \ - plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2; - - Languages with this property include: - - Slavic family - Czech, Slovak - -Three forms, special case for one and some numbers ending in 2, 3, or 4 - The header entry would look like this: - - Plural-Forms: nplurals=3; \ - plural=n==1 ? 0 : \ - n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2; - - Languages with this property include: - - Slavic family - Polish - -Four forms, special case for one and all numbers ending in 02, 03, or 04 - The header entry would look like this: - - Plural-Forms: nplurals=4; \ - plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3; - - Languages with this property include: - - Slavic family - Slovenian - - You might now ask, `ngettext' handles only numbers N of type -`unsigned long'. What about larger integer types? What about negative -numbers? What about floating-point numbers? - - About larger integer types, such as `uintmax_t' or `unsigned long -long': they can be handled by reducing the value to a range that fits -in an `unsigned long'. Simply casting the value to `unsigned long' -would not do the right thing, since it would treat `ULONG_MAX + 1' like -zero, `ULONG_MAX + 2' like singular, and the like. Here you can -exploit the fact that all mentioned plural form formulas eventually -become periodic, with a period that is a divisor of 100 (or 1000 or -1000000). So, when you reduce a large value to another one in the -range [1000000, 1999999] that ends in the same 6 decimal digits, you -can assume that it will lead to the same plural form selection. This -code does this: - - #include <inttypes.h> - uintmax_t nbytes = ...; - printf (ngettext ("The file has %"PRIuMAX" byte.", - "The file has %"PRIuMAX" bytes.", - (nbytes > ULONG_MAX - ? (nbytes % 1000000) + 1000000 - : nbytes)), - nbytes); - - Negative and floating-point values usually represent physical -entities for which singular and plural don't clearly apply. In such -cases, there is no need to use `ngettext'; a simple `gettext' call with -a form suitable for all values will do. For example: - - printf (gettext ("Time elapsed: %.3f seconds"), - num_milliseconds * 0.001); - -Even if NUM_MILLISECONDS happens to be a multiple of 1000, the output - Time elapsed: 1.000 seconds - is acceptable in English, and similarly for other languages. - - The translators' perspective regarding plural forms is explained in -*note Translating plural forms::. - - ---------- Footnotes ---------- - - (1) Additions are welcome. Send appropriate information to -<bug-gnu-gettext@gnu.org> and <bug-glibc-manual@gnu.org>. - - -File: gettext.info, Node: Optimized gettext, Prev: Plural forms, Up: gettext - -11.2.7 Optimization of the *gettext functions ---------------------------------------------- - - At this point of the discussion we should talk about an advantage of -the GNU `gettext' implementation. Some readers might have pointed out -that an internationalized program might have a poor performance if some -string has to be translated in an inner loop. While this is unavoidable -when the string varies from one run of the loop to the other it is -simply a waste of time when the string is always the same. Take the -following example: - - { - while (...) - { - puts (gettext ("Hello world")); - } - } - -When the locale selection does not change between two runs the resulting -string is always the same. One way to use this is: - - { - str = gettext ("Hello world"); - while (...) - { - puts (str); - } - } - -But this solution is not usable in all situation (e.g. when the locale -selection changes) nor does it lead to legible code. - - For this reason, GNU `gettext' caches previous translation results. -When the same translation is requested twice, with no new message -catalogs being loaded in between, `gettext' will, the second time, find -the result through a single cache lookup. - - -File: gettext.info, Node: Comparison, Next: Using libintl.a, Prev: gettext, Up: Programmers - -11.3 Comparing the Two Interfaces -================================= - - The following discussion is perhaps a little bit colored. As said -above we implemented GNU `gettext' following the Uniforum proposal and -this surely has its reasons. But it should show how we came to this -decision. - - First we take a look at the developing process. When we write an -application using NLS provided by `gettext' we proceed as always. Only -when we come to a string which might be seen by the users and thus has -to be translated we use `gettext("...")' instead of `"..."'. At the -beginning of each source file (or in a central header file) we define - - #define gettext(String) (String) - - Even this definition can be avoided when the system supports the -`gettext' function in its C library. When we compile this code the -result is the same as if no NLS code is used. When you take a look at -the GNU `gettext' code you will see that we use `_("...")' instead of -`gettext("...")'. This reduces the number of additional characters per -translatable string to _3_ (in words: three). - - When now a production version of the program is needed we simply -replace the definition - - #define _(String) (String) - -by - - #include <libintl.h> - #define _(String) gettext (String) - -Additionally we run the program `xgettext' on all source code file -which contain translatable strings and that's it: we have a running -program which does not depend on translations to be available, but which -can use any that becomes available. - - The same procedure can be done for the `gettext_noop' invocations -(*note Special cases::). One usually defines `gettext_noop' as a no-op -macro. So you should consider the following code for your project: - - #define gettext_noop(String) String - #define N_(String) gettext_noop (String) - - `N_' is a short form similar to `_'. The `Makefile' in the `po/' -directory of GNU `gettext' knows by default both of the mentioned short -forms so you are invited to follow this proposal for your own ease. - - Now to `catgets'. The main problem is the work for the programmer. -Every time he comes to a translatable string he has to define a number -(or a symbolic constant) which has also be defined in the message -catalog file. He also has to take care for duplicate entries, -duplicate message IDs etc. If he wants to have the same quality in the -message catalog as the GNU `gettext' program provides he also has to -put the descriptive comments for the strings and the location in all -source code files in the message catalog. This is nearly a Mission: -Impossible. - - But there are also some points people might call advantages speaking -for `catgets'. If you have a single word in a string and this string -is used in different contexts it is likely that in one or the other -language the word has different translations. Example: - - printf ("%s: %d", gettext ("number"), number_of_errors) - - printf ("you should see %d %s", number_count, - number_count == 1 ? gettext ("number") : gettext ("numbers")) - - Here we have to translate two times the string `"number"'. Even if -you do not speak a language beside English it might be possible to -recognize that the two words have a different meaning. In German the -first appearance has to be translated to `"Anzahl"' and the second to -`"Zahl"'. - - Now you can say that this example is really esoteric. And you are -right! This is exactly how we felt about this problem and decide that -it does not weight that much. The solution for the above problem could -be very easy: - - printf ("%s %d", gettext ("number:"), number_of_errors) - - printf (number_count == 1 ? gettext ("you should see %d number") - : gettext ("you should see %d numbers"), - number_count) - - We believe that we can solve all conflicts with this method. If it -is difficult one can also consider changing one of the conflicting -string a little bit. But it is not impossible to overcome. - - `catgets' allows same original entry to have different translations, -but `gettext' has another, scalable approach for solving ambiguities of -this kind: *Note Ambiguities::. - - -File: gettext.info, Node: Using libintl.a, Next: gettext grok, Prev: Comparison, Up: Programmers - -11.4 Using libintl.a in own programs -==================================== - - Starting with version 0.9.4 the library `libintl.h' should be -self-contained. I.e., you can use it in your own programs without -providing additional functions. The `Makefile' will put the header and -the library in directories selected using the `$(prefix)'. - - -File: gettext.info, Node: gettext grok, Next: Temp Programmers, Prev: Using libintl.a, Up: Programmers - -11.5 Being a `gettext' grok -=========================== - - * NOTE: * This documentation section is outdated and needs to be -revised. - - To fully exploit the functionality of the GNU `gettext' library it -is surely helpful to read the source code. But for those who don't want -to spend that much time in reading the (sometimes complicated) code here -is a list comments: - - * Changing the language at runtime - - For interactive programs it might be useful to offer a selection - of the used language at runtime. To understand how to do this one - need to know how the used language is determined while executing - the `gettext' function. The method which is presented here only - works correctly with the GNU implementation of the `gettext' - functions. - - In the function `dcgettext' at every call the current setting of - the highest priority environment variable is determined and used. - Highest priority means here the following list with decreasing - priority: - - 1. `LANGUAGE' - - 2. `LC_ALL' - - 3. `LC_xxx', according to selected locale category - - 4. `LANG' - - Afterwards the path is constructed using the found value and the - translation file is loaded if available. - - What happens now when the value for, say, `LANGUAGE' changes? - According to the process explained above the new value of this - variable is found as soon as the `dcgettext' function is called. - But this also means the (perhaps) different message catalog file - is loaded. In other words: the used language is changed. - - But there is one little hook. The code for gcc-2.7.0 and up - provides some optimization. This optimization normally prevents - the calling of the `dcgettext' function as long as no new catalog - is loaded. But if `dcgettext' is not called the program also - cannot find the `LANGUAGE' variable be changed (*note Optimized - gettext::). A solution for this is very easy. Include the - following code in the language switching function. - - /* Change language. */ - setenv ("LANGUAGE", "fr", 1); - - /* Make change known. */ - { - extern int _nl_msg_cat_cntr; - ++_nl_msg_cat_cntr; - } - - The variable `_nl_msg_cat_cntr' is defined in `loadmsgcat.c'. You - don't need to know what this is for. But it can be used to detect - whether a `gettext' implementation is GNU gettext and not non-GNU - system's native gettext implementation. - - - -File: gettext.info, Node: Temp Programmers, Prev: gettext grok, Up: Programmers - -11.6 Temporary Notes for the Programmers Chapter -================================================ - - * NOTE: * This documentation section is outdated and needs to be -revised. - -* Menu: - -* Temp Implementations:: Temporary - Two Possible Implementations -* Temp catgets:: Temporary - About `catgets' -* Temp WSI:: Temporary - Why a single implementation -* Temp Notes:: Temporary - Notes - - -File: gettext.info, Node: Temp Implementations, Next: Temp catgets, Prev: Temp Programmers, Up: Temp Programmers - -11.6.1 Temporary - Two Possible Implementations ------------------------------------------------ - - There are two competing methods for language independent messages: -the X/Open `catgets' method, and the Uniforum `gettext' method. The -`catgets' method indexes messages by integers; the `gettext' method -indexes them by their English translations. The `catgets' method has -been around longer and is supported by more vendors. The `gettext' -method is supported by Sun, and it has been heard that the COSE -multi-vendor initiative is supporting it. Neither method is a POSIX -standard; the POSIX.1 committee had a lot of disagreement in this area. - - Neither one is in the POSIX standard. There was much disagreement -in the POSIX.1 committee about using the `gettext' routines vs. -`catgets' (XPG). In the end the committee couldn't agree on anything, -so no messaging system was included as part of the standard. I believe -the informative annex of the standard includes the XPG3 messaging -interfaces, "...as an example of a messaging system that has been -implemented..." - - They were very careful not to say anywhere that you should use one -set of interfaces over the other. For more on this topic please see -the Programming for Internationalization FAQ. - - -File: gettext.info, Node: Temp catgets, Next: Temp WSI, Prev: Temp Implementations, Up: Temp Programmers - -11.6.2 Temporary - About `catgets' ----------------------------------- - - There have been a few discussions of late on the use of `catgets' as -a base. I think it important to present both sides of the argument and -hence am opting to play devil's advocate for a little bit. - - I'll not deny the fact that `catgets' could have been designed a lot -better. It currently has quite a number of limitations and these have -already been pointed out. - - However there is a great deal to be said for consistency and -standardization. A common recurring problem when writing Unix software -is the myriad portability problems across Unix platforms. It seems as -if every Unix vendor had a look at the operating system and found parts -they could improve upon. Undoubtedly, these modifications are probably -innovative and solve real problems. However, software developers have -a hard time keeping up with all these changes across so many platforms. - - And this has prompted the Unix vendors to begin to standardize their -systems. Hence the impetus for Spec1170. Every major Unix vendor has -committed to supporting this standard and every Unix software developer -waits with glee the day they can write software to this standard and -simply recompile (without having to use autoconf) across different -platforms. - - As I understand it, Spec1170 is roughly based upon version 4 of the -X/Open Portability Guidelines (XPG4). Because `catgets' and friends -are defined in XPG4, I'm led to believe that `catgets' is a part of -Spec1170 and hence will become a standardized component of all Unix -systems. - - -File: gettext.info, Node: Temp WSI, Next: Temp Notes, Prev: Temp catgets, Up: Temp Programmers - -11.6.3 Temporary - Why a single implementation ----------------------------------------------- - - Now it seems kind of wasteful to me to have two different systems -installed for accessing message catalogs. If we do want to remedy -`catgets' deficiencies why don't we try to expand `catgets' (in a -compatible manner) rather than implement an entirely new system. -Otherwise, we'll end up with two message catalog access systems -installed with an operating system - one set of routines for packages -using GNU `gettext' for their internationalization, and another set of -routines (catgets) for all other software. Bloated? - - Supposing another catalog access system is implemented. Which do we -recommend? At least for Linux, we need to attract as many software -developers as possible. Hence we need to make it as easy for them to -port their software as possible. Which means supporting `catgets'. We -will be implementing the `libintl' code within our `libc', but does -this mean we also have to incorporate another message catalog access -scheme within our `libc' as well? And what about people who are going -to be using the `libintl' + non-`catgets' routines. When they port -their software to other platforms, they're now going to have to include -the front-end (`libintl') code plus the back-end code (the non-`catgets' -access routines) with their software instead of just including the -`libintl' code with their software. - - Message catalog support is however only the tip of the iceberg. -What about the data for the other locale categories? They also have a -number of deficiencies. Are we going to abandon them as well and -develop another duplicate set of routines (should `libintl' expand -beyond message catalog support)? - - Like many parts of Unix that can be improved upon, we're stuck with -balancing compatibility with the past with useful improvements and -innovations for the future. - - -File: gettext.info, Node: Temp Notes, Prev: Temp WSI, Up: Temp Programmers - -11.6.4 Temporary - Notes ------------------------- - - X/Open agreed very late on the standard form so that many -implementations differ from the final form. Both of my system (old -Linux catgets and Ultrix-4) have a strange variation. - - OK. After incorporating the last changes I have to spend some time -on making the GNU/Linux `libc' `gettext' functions. So in future -Solaris is not the only system having `gettext'. - - -File: gettext.info, Node: Translators, Next: Maintainers, Prev: Programmers, Up: Top - -12 The Translator's View -************************ - -* Menu: - -* Trans Intro 0:: Introduction 0 -* Trans Intro 1:: Introduction 1 -* Discussions:: Discussions -* Organization:: Organization -* Information Flow:: Information Flow -* Translating plural forms:: How to fill in `msgstr[0]', `msgstr[1]' -* Prioritizing messages:: How to find which messages to translate first - - -File: gettext.info, Node: Trans Intro 0, Next: Trans Intro 1, Prev: Translators, Up: Translators - -12.1 Introduction 0 -=================== - - * NOTE: * This documentation section is outdated and needs to be -revised. - - Free software is going international! The Translation Project is a -way to get maintainers, translators and users all together, so free -software will gradually become able to speak many native languages. - - The GNU `gettext' tool set contains _everything_ maintainers need -for internationalizing their packages for messages. It also contains -quite useful tools for helping translators at localizing messages to -their native language, once a package has already been -internationalized. - - To achieve the Translation Project, we need many interested people -who like their own language and write it well, and who are also able to -synergize with other translators speaking the same language. If you'd -like to volunteer to _work_ at translating messages, please send mail -to your translating team. - - Each team has its own mailing list, courtesy of Linux International. -You may reach your translating team at the address `LL@li.org', -replacing LL by the two-letter ISO 639 code for your language. -Language codes are _not_ the same as country codes given in ISO 3166. -The following translating teams exist: - - Chinese `zh', Czech `cs', Danish `da', Dutch `nl', Esperanto `eo', - Finnish `fi', French `fr', Irish `ga', German `de', Greek `el', - Italian `it', Japanese `ja', Indonesian `in', Norwegian `no', - Polish `pl', Portuguese `pt', Russian `ru', Spanish `es', Swedish - `sv' and Turkish `tr'. - -For example, you may reach the Chinese translating team by writing to -`zh@li.org'. When you become a member of the translating team for your -own language, you may subscribe to its list. For example, Swedish -people can send a message to `sv-request@li.org', having this message -body: - - subscribe - - Keep in mind that team members should be interested in _working_ at -translations, or at solving translational difficulties, rather than -merely lurking around. If your team does not exist yet and you want to -start one, please write to `coordinator@translationproject.org'; you -will then reach the coordinator for all translator teams. - - A handful of GNU packages have already been adapted and provided -with message translations for several languages. Translation teams -have begun to organize, using these packages as a starting point. But -there are many more packages and many languages for which we have no -volunteer translators. If you would like to volunteer to work at -translating messages, please send mail to -`coordinator@translationproject.org' indicating what language(s) you -can work on. - - -File: gettext.info, Node: Trans Intro 1, Next: Discussions, Prev: Trans Intro 0, Up: Translators - -12.2 Introduction 1 -=================== - - * NOTE: * This documentation section is outdated and needs to be -revised. - - This is now official, GNU is going international! Here is the -announcement submitted for the January 1995 GNU Bulletin: - - A handful of GNU packages have already been adapted and provided - with message translations for several languages. Translation - teams have begun to organize, using these packages as a starting - point. But there are many more packages and many languages for - which we have no volunteer translators. If you'd like to - volunteer to work at translating messages, please send mail to - `coordinator@translationproject.org' indicating what language(s) - you can work on. - - This document should answer many questions for those who are curious -about the process or would like to contribute. Please at least skim -over it, hoping to cut down a little of the high volume of e-mail -generated by this collective effort towards internationalization of -free software. - - Most free programming which is widely shared is done in English, and -currently, English is used as the main communicating language between -national communities collaborating to free software. This very document -is written in English. This will not change in the foreseeable future. - - However, there is a strong appetite from national communities for -having more software able to write using national language and habits, -and there is an on-going effort to modify free software in such a way -that it becomes able to do so. The experiments driven so far raised an -enthusiastic response from pretesters, so we believe that -internationalization of free software is dedicated to succeed. - - For suggestion clarifications, additions or corrections to this -document, please e-mail to `coordinator@translationproject.org'. - - -File: gettext.info, Node: Discussions, Next: Organization, Prev: Trans Intro 1, Up: Translators - -12.3 Discussions -================ - - * NOTE: * This documentation section is outdated and needs to be -revised. - - Facing this internationalization effort, a few users expressed their -concerns. Some of these doubts are presented and discussed, here. - - * Smaller groups - - Some languages are not spoken by a very large number of people, so - people speaking them sometimes consider that there may not be all - that much demand such versions of free software packages. - Moreover, many people being _into computers_, in some countries, - generally seem to prefer English versions of their software. - - On the other end, people might enjoy their own language a lot, and - be very motivated at providing to themselves the pleasure of - having their beloved free software speaking their mother tongue. - They do themselves a personal favor, and do not pay that much - attention to the number of people benefiting of their work. - - * Misinterpretation - - Other users are shy to push forward their own language, seeing in - this some kind of misplaced propaganda. Someone thought there - must be some users of the language over the networks pestering - other people with it. - - But any spoken language is worth localization, because there are - people behind the language for whom the language is important and - dear to their hearts. - - * Odd translations - - The biggest problem is to find the right translations so that - everybody can understand the messages. Translations are usually a - little odd. Some people get used to English, to the extent they - may find translations into their own language "rather pushy, - obnoxious and sometimes even hilarious." As a French speaking - man, I have the experience of those instruction manuals for goods, - so poorly translated in French in Korea or Taiwan... - - The fact is that we sometimes have to create a kind of national - computer culture, and this is not easy without the collaboration of - many people liking their mother tongue. This is why translations - are better achieved by people knowing and loving their own - language, and ready to work together at improving the results they - obtain. - - * Dependencies over the GPL or LGPL - - Some people wonder if using GNU `gettext' necessarily brings their - package under the protective wing of the GNU General Public - License or the GNU Library General Public License, when they do - not want to make their program free, or want other kinds of - freedom. The simplest answer is "normally not". - - The `gettext-runtime' part of GNU `gettext', i.e. the contents of - `libintl', is covered by the GNU Library General Public License. - The `gettext-tools' part of GNU `gettext', i.e. the rest of the - GNU `gettext' package, is covered by the GNU General Public - License. - - The mere marking of localizable strings in a package, or - conditional inclusion of a few lines for initialization, is not - really including GPL'ed or LGPL'ed code. However, since the - localization routines in `libintl' are under the LGPL, the LGPL - needs to be considered. It gives the right to distribute the - complete unmodified source of `libintl' even with non-free - programs. It also gives the right to use `libintl' as a shared - library, even for non-free programs. But it gives the right to - use `libintl' as a static library or to incorporate `libintl' into - another library only to free software. - - - -File: gettext.info, Node: Organization, Next: Information Flow, Prev: Discussions, Up: Translators - -12.4 Organization -================= - - * NOTE: * This documentation section is outdated and needs to be -revised. - - On a larger scale, the true solution would be to organize some kind -of fairly precise set up in which volunteers could participate. I gave -some thought to this idea lately, and realize there will be some touchy -points. I thought of writing to Richard Stallman to launch such a -project, but feel it might be good to shake out the ideas between -ourselves first. Most probably that Linux International has some -experience in the field already, or would like to orchestrate the -volunteer work, maybe. Food for thought, in any case! - - I guess we have to setup something early, somehow, that will help -many possible contributors of the same language to interlock and avoid -work duplication, and further be put in contact for solving together -problems particular to their tongue (in most languages, there are many -difficulties peculiar to translating technical English). My Swedish -contributor acknowledged these difficulties, and I'm well aware of them -for French. - - This is surely not a technical issue, but we should manage so the -effort of locale contributors be maximally useful, despite the national -team layer interface between contributors and maintainers. - - The Translation Project needs some setup for coordinating language -coordinators. Localizing evolving programs will surely become a -permanent and continuous activity in the free software community, once -well started. The setup should be minimally completed and tested -before GNU `gettext' becomes an official reality. The e-mail address -`coordinator@translationproject.org' has been set up for receiving -offers from volunteers and general e-mail on these topics. This address -reaches the Translation Project coordinator. - -* Menu: - -* Central Coordination:: Central Coordination -* National Teams:: National Teams -* Mailing Lists:: Mailing Lists - - -File: gettext.info, Node: Central Coordination, Next: National Teams, Prev: Organization, Up: Organization - -12.4.1 Central Coordination ---------------------------- - - I also think GNU will need sooner than it thinks, that someone set up -a way to organize and coordinate these groups. Some kind of group of -groups. My opinion is that it would be good that GNU delegates this -task to a small group of collaborating volunteers, shortly. Perhaps in -`gnu.announce' a list of this national committee's can be published. - - My role as coordinator would simply be to refer to Ulrich any German -speaking volunteer interested to localization of free software -packages, and maybe helping national groups to initially organize, -while maintaining national registries for until national groups are -ready to take over. In fact, the coordinator should ease volunteers to -get in contact with one another for creating national teams, which -should then select one coordinator per language, or country -(regionalized language). If well done, the coordination should be -useful without being an overwhelming task, the time to put delegations -in place. - - -File: gettext.info, Node: National Teams, Next: Mailing Lists, Prev: Central Coordination, Up: Organization - -12.4.2 National Teams ---------------------- - - I suggest we look for volunteer coordinators/editors for individual -languages. These people will scan contributions of translation files -for various programs, for their own languages, and will ensure high and -uniform standards of diction. - - From my current experience with other people in these days, those who -provide localizations are very enthusiastic about the process, and are -more interested in the localization process than in the program they -localize, and want to do many programs, not just one. This seems to -confirm that having a coordinator/editor for each language is a good -idea. - - We need to choose someone who is good at writing clear and concise -prose in the language in question. That is hard--we can't check it -ourselves. So we need to ask a few people to judge each others' -writing and select the one who is best. - - I announce my prerelease to a few dozen people, and you would not -believe all the discussions it generated already. I shudder to think -what will happen when this will be launched, for true, officially, -world wide. Who am I to arbitrate between two Czekolsovak users -contradicting each other, for example? - - I assume that your German is not much better than my French so that -I would not be able to judge about these formulations. What I would -suggest is that for each language there is a group for people who -maintain the PO files and judge about changes. I suspect there will be -cultural differences between how such groups of people will behave. -Some will have relaxed ways, reach consensus easily, and have anyone of -the group relate to the maintainers, while others will fight to death, -organize heavy administrations up to national standards, and use strict -channels. - - The German team is putting out a good example. Right now, they are -maybe half a dozen people revising translations of each other and -discussing the linguistic issues. I do not even have all the names. -Ulrich Drepper is taking care of coordinating the German team. He -subscribed to all my pretest lists, so I do not even have to warn him -specifically of incoming releases. - - I'm sure, that is a good idea to get teams for each language working -on translations. That will make the translations better and more -consistent. - -* Menu: - -* Sub-Cultures:: Sub-Cultures -* Organizational Ideas:: Organizational Ideas - - -File: gettext.info, Node: Sub-Cultures, Next: Organizational Ideas, Prev: National Teams, Up: National Teams - -12.4.2.1 Sub-Cultures -..................... - - Taking French for example, there are a few sub-cultures around -computers which developed diverging vocabularies. Picking volunteers -here and there without addressing this problem in an organized way, -soon in the project, might produce a distasteful mix of -internationalized programs, and possibly trigger endless quarrels among -those who really care. - - Keeping some kind of unity in the way French localization of -internationalized programs is achieved is a difficult (and delicate) -job. Knowing the latin character of French people (:-), if we take this -the wrong way, we could end up nowhere, or spoil a lot of energies. -Maybe we should begin to address this problem seriously _before_ GNU -`gettext' become officially published. And I suspect that this means -soon! - - -File: gettext.info, Node: Organizational Ideas, Prev: Sub-Cultures, Up: National Teams - -12.4.2.2 Organizational Ideas -............................. - - I expect the next big changes after the official release. Please -note that I use the German translation of the short GPL message. We -need to set a few good examples before the localization goes out for -true in the free software community. Here are a few points to discuss: - - * Each group should have one FTP server (at least one master). - - * The files on the server should reflect the latest version (of - course!) and it should also contain a RCS directory with the - corresponding archives (I don't have this now). - - * There should also be a ChangeLog file (this is more useful than the - RCS archive but can be generated automatically from the later by - Emacs). - - * A "core group" should judge about questionable changes (for now - this group consists solely by me but I ask some others - occasionally; this also seems to work). - - - -File: gettext.info, Node: Mailing Lists, Prev: National Teams, Up: Organization - -12.4.3 Mailing Lists --------------------- - - If we get any inquiries about GNU `gettext', send them on to: - - `coordinator@translationproject.org' - - The `*-pretest' lists are quite useful to me, maybe the idea could -be generalized to many GNU, and non-GNU packages. But each maintainer -his/her way! - - François, we have a mechanism in place here at `gnu.ai.mit.edu' to -track teams, support mailing lists for them and log members. We have a -slight preference that you use it. If this is OK with you, I can get -you clued in. - - Things are changing! A few years ago, when Daniel Fekete and I -asked for a mailing list for GNU localization, nested at the FSF, we -were politely invited to organize it anywhere else, and so did we. For -communicating with my pretesters, I later made a handful of mailing -lists located at iro.umontreal.ca and administrated by `majordomo'. -These lists have been _very_ dependable so far... - - I suspect that the German team will organize itself a mailing list -located in Germany, and so forth for other countries. But before they -organize for true, it could surely be useful to offer mailing lists -located at the FSF to each national team. So yes, please explain me -how I should proceed to create and handle them. - - We should create temporary mailing lists, one per country, to help -people organize. Temporary, because once regrouped and structured, it -would be fair the volunteers from country bring back _their_ list in -there and manage it as they want. My feeling is that, in the long run, -each team should run its own list, from within their country. There -also should be some central list to which all teams could subscribe as -they see fit, as long as each team is represented in it. - - -File: gettext.info, Node: Information Flow, Next: Translating plural forms, Prev: Organization, Up: Translators - -12.5 Information Flow -===================== - - * NOTE: * This documentation section is outdated and needs to be -revised. - - There will surely be some discussion about this messages after the -packages are finally released. If people now send you some proposals -for better messages, how do you proceed? Jim, please note that right -now, as I put forward nearly a dozen of localizable programs, I receive -both the translations and the coordination concerns about them. - - If I put one of my things to pretest, Ulrich receives the -announcement and passes it on to the German team, who make last minute -revisions. Then he submits the translation files to me _as the -maintainer_. For free packages I do not maintain, I would not even -hear about it. This scheme could be made to work for the whole -Translation Project, I think. For security reasons, maybe Ulrich -(national coordinators, in fact) should update central registry kept at -the Translation Project (Jim, me, or Len's recruits) once in a while. - - In December/January, I was aggressively ready to internationalize -all of GNU, giving myself the duty of one small GNU package per week or -so, taking many weeks or months for bigger packages. But it does not -work this way. I first did all the things I'm responsible for. I've -nothing against some missionary work on other maintainers, but I'm also -loosing a lot of energy over it--same debates over again. - - And when the first localized packages are released we'll get a lot of -responses about ugly translations :-). Surely, and we need to have -beforehand a fairly good idea about how to handle the information flow -between the national teams and the package maintainers. - - Please start saving somewhere a quick history of each PO file. I -know for sure that the file format will change, allowing for comments. -It would be nice that each file has a kind of log, and references for -those who want to submit comments or gripes, or otherwise contribute. -I sent a proposal for a fast and flexible format, but it is not -receiving acceptance yet by the GNU deciders. I'll tell you when I -have more information about this. - - -File: gettext.info, Node: Translating plural forms, Next: Prioritizing messages, Prev: Information Flow, Up: Translators - -12.6 Translating plural forms -============================= - - Suppose you are translating a PO file, and it contains an entry like -this: - - #, c-format - msgid "One file removed" - msgid_plural "%d files removed" - msgstr[0] "" - msgstr[1] "" - -What does this mean? How do you fill it in? - - Such an entry denotes a message with plural forms, that is, a -message where the text depends on a cardinal number. The general form -of the message, in English, is the `msgid_plural' line. The `msgid' -line is the English singular form, that is, the form for when the -number is equal to 1. More details about plural forms are explained in -*note Plural forms::. - - The first thing you need to look at is the `Plural-Forms' line in the -header entry of the PO file. It contains the number of plural forms -and a formula. If the PO file does not yet have such a line, you have -to add it. It only depends on the language into which you are -translating. You can get this info by using the `msginit' command (see -*note Creating::) - it contains a database of known plural formulas - -or by asking other members of your translation team. - - Suppose the line looks as follows: - - "Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && n" - "%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" - - It's logically one line; recall that the PO file formatting is -allowed to break long lines so that each physical line fits in 80 -monospaced columns. - - The value of `nplurals' here tells you that there are three plural -forms. The first thing you need to do is to ensure that the entry -contains an `msgstr' line for each of the forms: - - #, c-format - msgid "One file removed" - msgid_plural "%d files removed" - msgstr[0] "" - msgstr[1] "" - msgstr[2] "" - - Then translate the `msgid_plural' line and fill it in into each -`msgstr' line: - - #, c-format - msgid "One file removed" - msgid_plural "%d files removed" - msgstr[0] "%d slika uklonjenih" - msgstr[1] "%d slika uklonjenih" - msgstr[2] "%d slika uklonjenih" - - Now you can refine the translation so that it matches the plural -form. According to the formula above, `msgstr[0]' is used when the -number ends in 1 but does not end in 11; `msgstr[1]' is used when the -number ends in 2, 3, 4, but not in 12, 13, 14; and `msgstr[2]' is used -in all other cases. With this knowledge, you can refine the -translations: - - #, c-format - msgid "One file removed" - msgid_plural "%d files removed" - msgstr[0] "%d slika je uklonjena" - msgstr[1] "%d datoteke uklonjenih" - msgstr[2] "%d slika uklonjenih" - - You noticed that in the English singular form (`msgid') the number -placeholder could be omitted and replaced by the numeral word "one". -Can you do this in your translation as well? - - msgstr[0] "jednom datotekom je uklonjen" - -Well, it depends on whether `msgstr[0]' applies only to the number 1, -or to other numbers as well. If, according to the plural formula, -`msgstr[0]' applies only to `n == 1', then you can use the specialized -translation without the number placeholder. In our case, however, -`msgstr[0]' also applies to the numbers 21, 31, 41, etc., and therefore -you cannot omit the placeholder. - - -File: gettext.info, Node: Prioritizing messages, Prev: Translating plural forms, Up: Translators - -12.7 Prioritizing messages: How to determine which messages to translate first -============================================================================== - - A translator sometimes has only a limited amount of time per week to -spend on a package, and some packages have quite large message catalogs -(over 1000 messages). Therefore she wishes to translate the messages -first that are the most visible to the user, or that occur most -frequently. This section describes how to determine these "most -urgent" messages. It also applies to determine the "next most urgent" -messages after the message catalog has already been partially -translated. - - In a first step, she uses the programs like a user would do. While -she does this, the GNU `gettext' library logs into a file the not yet -translated messages for which a translation was requested from the -program. - - In a second step, she uses the PO mode to translate precisely this -set of messages. - - Here a more details. The GNU `libintl' library (but not the -corresponding functions in GNU `libc') supports an environment variable -`GETTEXT_LOG_UNTRANSLATED'. The GNU `libintl' library will log into -this file the messages for which `gettext()' and related functions -couldn't find the translation. If the file doesn't exist, it will be -created as needed. On systems with GNU `libc' a shared library -`preloadable_libintl.so' is provided that can be used with the ELF -`LD_PRELOAD' mechanism. - - So, in the first step, the translator uses these commands on systems -with GNU `libc': - - $ LD_PRELOAD=/usr/local/lib/preloadable_libintl.so - $ export LD_PRELOAD - $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused - $ export GETTEXT_LOG_UNTRANSLATED - -and these commands on other systems: - - $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused - $ export GETTEXT_LOG_UNTRANSLATED - - Then she uses and peruses the programs. (It is a good and -recommended practice to use the programs for which you provide -translations: it gives you the needed context.) When done, she removes -the environment variables: - - $ unset LD_PRELOAD - $ unset GETTEXT_LOG_UNTRANSLATED - - The second step starts with removing duplicates: - - $ msguniq $HOME/gettextlogused > missing.po - - The result is a PO file, but needs some preprocessing before a PO -file editor can be used with it. First, it is a multi-domain PO file, -containing messages from many translation domains. Second, it lacks -all translator comments and source references. Here is how to get a -list of the affected translation domains: - - $ sed -n -e 's,^domain "\(.*\)"$,\1,p' < missing.po | sort | uniq - - Then the translator can handle the domains one by one. For -simplicity, let's use environment variables to denote the language, -domain and source package. - - $ lang=nl # your language - $ domain=coreutils # the name of the domain to be handled - $ package=/usr/src/gnu/coreutils-4.5.4 # the package where it comes from - - She takes the latest copy of `$lang.po' from the Translation Project, -or from the package (in most cases, `$package/po/$lang.po'), or creates -a fresh one if she's the first translator (see *note Creating::). She -then uses the following commands to mark the not urgent messages as -"obsolete". (This doesn't mean that these messages - translated and -untranslated ones - will go away. It simply means that the PO file -editor will ignore them in the following editing session.) - - $ msggrep --domain=$domain missing.po | grep -v '^domain' \ - > $domain-missing.po - $ msgattrib --set-obsolete --ignore-file $domain-missing.po $domain.$lang.po \ - > $domain.$lang-urgent.po - - The she translates `$domain.$lang-urgent.po' by use of a PO file -editor (*note Editing::). (FIXME: I don't know whether `KBabel' and -`gtranslator' also preserve obsolete messages, as they should.) -Finally she restores the not urgent messages (with their earlier -translations, for those which were already translated) through this -command: - - $ msgmerge --no-fuzzy-matching $domain.$lang-urgent.po $package/po/$domain.pot \ - > $domain.$lang.po - - Then she can submit `$domain.$lang.po' and proceed to the next -domain. - - -File: gettext.info, Node: Maintainers, Next: Installers, Prev: Translators, Up: Top - -13 The Maintainer's View -************************ - - The maintainer of a package has many responsibilities. One of them -is ensuring that the package will install easily on many platforms, and -that the magic we described earlier (*note Users::) will work for -installers and end users. - - Of course, there are many possible ways by which GNU `gettext' might -be integrated in a distribution, and this chapter does not cover them -in all generality. Instead, it details one possible approach which is -especially adequate for many free software distributions following GNU -standards, or even better, Gnits standards, because GNU `gettext' is -purposely for helping the internationalization of the whole GNU -project, and as many other good free packages as possible. So, the -maintainer's view presented here presumes that the package already has -a `configure.ac' file and uses GNU Autoconf. - - Nevertheless, GNU `gettext' may surely be useful for free packages -not following GNU standards and conventions, but the maintainers of such -packages might have to show imagination and initiative in organizing -their distributions so `gettext' work for them in all situations. -There are surely many, out there. - - Even if `gettext' methods are now stabilizing, slight adjustments -might be needed between successive `gettext' versions, so you should -ideally revise this chapter in subsequent releases, looking for changes. - -* Menu: - -* Flat and Non-Flat:: Flat or Non-Flat Directory Structures -* Prerequisites:: Prerequisite Works -* gettextize Invocation:: Invoking the `gettextize' Program -* Adjusting Files:: Files You Must Create or Alter -* autoconf macros:: Autoconf macros for use in `configure.ac' -* CVS Issues:: Integrating with CVS -* Release Management:: Creating a Distribution Tarball - - -File: gettext.info, Node: Flat and Non-Flat, Next: Prerequisites, Prev: Maintainers, Up: Maintainers - -13.1 Flat or Non-Flat Directory Structures -========================================== - - Some free software packages are distributed as `tar' files which -unpack in a single directory, these are said to be "flat" distributions. -Other free software packages have a one level hierarchy of -subdirectories, using for example a subdirectory named `doc/' for the -Texinfo manual and man pages, another called `lib/' for holding -functions meant to replace or complement C libraries, and a -subdirectory `src/' for holding the proper sources for the package. -These other distributions are said to be "non-flat". - - We cannot say much about flat distributions. A flat directory -structure has the disadvantage of increasing the difficulty of updating -to a new version of GNU `gettext'. Also, if you have many PO files, -this could somewhat pollute your single directory. Also, GNU -`gettext''s libintl sources consist of C sources, shell scripts, `sed' -scripts and complicated Makefile rules, which don't fit well into an -existing flat structure. For these reasons, we recommend to use -non-flat approach in this case as well. - - Maybe because GNU `gettext' itself has a non-flat structure, we have -more experience with this approach, and this is what will be described -in the remaining of this chapter. Some maintainers might use this as -an opportunity to unflatten their package structure. - - -File: gettext.info, Node: Prerequisites, Next: gettextize Invocation, Prev: Flat and Non-Flat, Up: Maintainers - -13.2 Prerequisite Works -======================= - - There are some works which are required for using GNU `gettext' in -one of your package. These works have some kind of generality that -escape the point by point descriptions used in the remainder of this -chapter. So, we describe them here. - - * Before attempting to use `gettextize' you should install some - other packages first. Ensure that recent versions of GNU `m4', - GNU Autoconf and GNU `gettext' are already installed at your site, - and if not, proceed to do this first. If you get to install these - things, beware that GNU `m4' must be fully installed before GNU - Autoconf is even _configured_. - - To further ease the task of a package maintainer the `automake' - package was designed and implemented. GNU `gettext' now uses this - tool and the `Makefile's in the `intl/' and `po/' therefore know - about all the goals necessary for using `automake' and `libintl' - in one project. - - Those four packages are only needed by you, as a maintainer; the - installers of your own package and end users do not really need - any of GNU `m4', GNU Autoconf, GNU `gettext', or GNU `automake' - for successfully installing and running your package, with messages - properly translated. But this is not completely true if you - provide internationalized shell scripts within your own package: - GNU `gettext' shall then be installed at the user site if the end - users want to see the translation of shell script messages. - - * Your package should use Autoconf and have a `configure.ac' or - `configure.in' file. If it does not, you have to learn how. The - Autoconf documentation is quite well written, it is a good idea - that you print it and get familiar with it. - - * Your C sources should have already been modified according to - instructions given earlier in this manual. *Note Sources::. - - * Your `po/' directory should receive all PO files submitted to you - by the translator teams, each having `LL.po' as a name. This is - not usually easy to get translation work done before your package - gets internationalized and available! Since the cycle has to - start somewhere, the easiest for the maintainer is to start with - absolutely no PO files, and wait until various translator teams - get interested in your package, and submit PO files. - - - It is worth adding here a few words about how the maintainer should -ideally behave with PO files submissions. As a maintainer, your role is -to authenticate the origin of the submission as being the representative -of the appropriate translating teams of the Translation Project (forward -the submission to `coordinator@translationproject.org' in case of -doubt), to ensure that the PO file format is not severely broken and -does not prevent successful installation, and for the rest, to merely -put these PO files in `po/' for distribution. - - As a maintainer, you do not have to take on your shoulders the -responsibility of checking if the translations are adequate or -complete, and should avoid diving into linguistic matters. Translation -teams drive themselves and are fully responsible of their linguistic -choices for the Translation Project. Keep in mind that translator -teams are _not_ driven by maintainers. You can help by carefully -redirecting all communications and reports from users about linguistic -matters to the appropriate translation team, or explain users how to -reach or join their team. The simplest might be to send them the -`ABOUT-NLS' file. - - Maintainers should _never ever_ apply PO file bug reports -themselves, short-cutting translation teams. If some translator has -difficulty to get some of her points through her team, it should not be -an option for her to directly negotiate translations with maintainers. -Teams ought to settle their problems themselves, if any. If you, as a -maintainer, ever think there is a real problem with a team, please -never try to _solve_ a team's problem on your own. - - -File: gettext.info, Node: gettextize Invocation, Next: Adjusting Files, Prev: Prerequisites, Up: Maintainers - -13.3 Invoking the `gettextize' Program -====================================== - - The `gettextize' program is an interactive tool that helps the -maintainer of a package internationalized through GNU `gettext'. It is -used for two purposes: - - * As a wizard, when a package is modified to use GNU `gettext' for - the first time. - - * As a migration tool, for upgrading the GNU `gettext' support in a - package from a previous to a newer version of GNU `gettext'. - - This program performs the following tasks: - - * It copies into the package some files that are consistently and - identically needed in every package internationalized through GNU - `gettext'. - - * It performs as many of the tasks mentioned in the next section - *note Adjusting Files:: as can be performed automatically. - - * It removes obsolete files and idioms used for previous GNU - `gettext' versions to the form recommended for the current GNU - `gettext' version. - - * It prints a summary of the tasks that ought to be done manually - and could not be done automatically by `gettextize'. - - It can be invoked as follows: - - gettextize [ OPTION... ] [ DIRECTORY ] - -and accepts the following options: - -`-f' -`--force' - Force replacement of files which already exist. - -`--intl' - Install the libintl sources in a subdirectory named `intl/'. This - libintl will be used to provide internationalization on systems - that don't have GNU libintl installed. If this option is omitted, - the call to `AM_GNU_GETTEXT' in `configure.ac' should read: - `AM_GNU_GETTEXT([external])', and internationalization will not be - enabled on systems lacking GNU gettext. - -`--po-dir=DIR' - Specify a directory containing PO files. Such a directory - contains the translations into various languages of a particular - POT file. This option can be specified multiple times, once for - each translation domain. If it is not specified, the directory - named `po/' is updated. - -`--no-changelog' - Don't update or create ChangeLog files. By default, `gettextize' - logs all changes (file additions, modifications and removals) in a - file called `ChangeLog' in each affected directory. - -`--symlink' - Make symbolic links instead of copying the needed files. This can - be useful to save a few kilobytes of disk space, but it requires - extra effort to create self-contained tarballs, it may disturb - some mechanism the maintainer applies to the sources, and it is - likely to introduce bugs when a newer version of `gettext' is - installed on the system. - -`-n' -`--dry-run' - Print modifications but don't perform them. All actions that - `gettextize' would normally execute are inhibited and instead only - listed on standard output. - -`--help' - Display this help and exit. - -`--version' - Output version information and exit. - - - If DIRECTORY is given, this is the top level directory of a package -to prepare for using GNU `gettext'. If not given, it is assumed that -the current directory is the top level directory of such a package. - - The program `gettextize' provides the following files. However, no -existing file will be replaced unless the option `--force' (`-f') is -specified. - - 1. The `ABOUT-NLS' file is copied in the main directory of your - package, the one being at the top level. This file gives the main - indications about how to install and use the Native Language - Support features of your program. You might elect to use a more - recent copy of this `ABOUT-NLS' file than the one provided through - `gettextize', if you have one handy. You may also fetch a more - recent copy of file `ABOUT-NLS' from Translation Project sites, - and from most GNU archive sites. - - 2. A `po/' directory is created for eventually holding all - translation files, but initially only containing the file - `po/Makefile.in.in' from the GNU `gettext' distribution (beware - the double `.in' in the file name) and a few auxiliary files. If - the `po/' directory already exists, it will be preserved along - with the files it contains, and only `Makefile.in.in' and the - auxiliary files will be overwritten. - - If `--po-dir' has been specified, this holds for every directory - specified through `--po-dir', instead of `po/'. - - 3. Only if `--intl' has been specified: A `intl/' directory is - created and filled with most of the files originally in the - `intl/' directory of the GNU `gettext' distribution. Also, if - option `--force' (`-f') is given, the `intl/' directory is emptied - first. - - 4. The file `config.rpath' is copied into the directory containing - configuration support files. It is needed by the `AM_GNU_GETTEXT' - autoconf macro. - - 5. Only if the project is using GNU `automake': A set of `autoconf' - macro files is copied into the package's `autoconf' macro - repository, usually in a directory called `m4/'. - - If your site support symbolic links, `gettextize' will not actually -copy the files into your package, but establish symbolic links instead. -This avoids duplicating the disk space needed in all packages. Merely -using the `-h' option while creating the `tar' archive of your -distribution will resolve each link by an actual copy in the -distribution archive. So, to insist, you really should use `-h' option -with `tar' within your `dist' goal of your main `Makefile.in'. - - Furthermore, `gettextize' will update all `Makefile.am' files in -each affected directory, as well as the top level `configure.ac' or -`configure.in' file. - - It is interesting to understand that most new files for supporting -GNU `gettext' facilities in one package go in `intl/', `po/' and `m4/' -subdirectories. One distinction between `intl/' and the two other -directories is that `intl/' is meant to be completely identical in all -packages using GNU `gettext', while the other directories will mostly -contain package dependent files. - - The `gettextize' program makes backup files for all files it -replaces or changes, and also write ChangeLog entries about these -changes. This way, the careful maintainer can check after running -`gettextize' whether its changes are acceptable to him, and possibly -adjust them. An exception to this rule is the `intl/' directory, which -is added or replaced or removed as a whole. - - It is important to understand that `gettextize' can not do the -entire job of adapting a package for using GNU `gettext'. The amount -of remaining work depends on whether the package uses GNU `automake' or -not. But in any case, the maintainer should still read the section -*note Adjusting Files:: after invoking `gettextize'. - - In particular, if after using `gettexize', you get an error -`AC_COMPILE_IFELSE was called before AC_GNU_SOURCE' or `AC_RUN_IFELSE -was called before AC_GNU_SOURCE', you can fix it by modifying -`configure.ac', as described in *note configure.ac::. - - It is also important to understand that `gettextize' is not part of -the GNU build system, in the sense that it should not be invoked -automatically, and not be invoked by someone who doesn't assume the -responsibilities of a package maintainer. For the latter purpose, a -separate tool is provided, see *note autopoint Invocation::. - - -File: gettext.info, Node: Adjusting Files, Next: autoconf macros, Prev: gettextize Invocation, Up: Maintainers - -13.4 Files You Must Create or Alter -=================================== - - Besides files which are automatically added through `gettextize', -there are many files needing revision for properly interacting with GNU -`gettext'. If you are closely following GNU standards for Makefile -engineering and auto-configuration, the adaptations should be easier to -achieve. Here is a point by point description of the changes needed in -each. - - So, here comes a list of files, each one followed by a description of -all alterations it needs. Many examples are taken out from the GNU -`gettext' 0.18.1 distribution itself, or from the GNU `hello' -distribution (`http://www.franken.de/users/gnu/ke/hello' or -`http://www.gnu.franken.de/ke/hello/') You may indeed refer to the -source code of the GNU `gettext' and GNU `hello' packages, as they are -intended to be good examples for using GNU gettext functionality. - -* Menu: - -* po/POTFILES.in:: `POTFILES.in' in `po/' -* po/LINGUAS:: `LINGUAS' in `po/' -* po/Makevars:: `Makevars' in `po/' -* po/Rules-*:: Extending `Makefile' in `po/' -* configure.ac:: `configure.ac' at top level -* config.guess:: `config.guess', `config.sub' at top level -* mkinstalldirs:: `mkinstalldirs' at top level -* aclocal:: `aclocal.m4' at top level -* acconfig:: `acconfig.h' at top level -* config.h.in:: `config.h.in' at top level -* Makefile:: `Makefile.in' at top level -* src/Makefile:: `Makefile.in' in `src/' -* lib/gettext.h:: `gettext.h' in `lib/' - - -File: gettext.info, Node: po/POTFILES.in, Next: po/LINGUAS, Prev: Adjusting Files, Up: Adjusting Files - -13.4.1 `POTFILES.in' in `po/' ------------------------------ - - The `po/' directory should receive a file named `POTFILES.in'. This -file tells which files, among all program sources, have marked strings -needing translation. Here is an example of such a file: - - # List of source files containing translatable strings. - # Copyright (C) 1995 Free Software Foundation, Inc. - - # Common library files - lib/error.c - lib/getopt.c - lib/xmalloc.c - - # Package source files - src/gettext.c - src/msgfmt.c - src/xgettext.c - -Hash-marked comments and white lines are ignored. All other lines list -those source files containing strings marked for translation (*note -Mark Keywords::), in a notation relative to the top level of your whole -distribution, rather than the location of the `POTFILES.in' file itself. - - When a C file is automatically generated by a tool, like `flex' or -`bison', that doesn't introduce translatable strings by itself, it is -recommended to list in `po/POTFILES.in' the real source file (ending in -`.l' in the case of `flex', or in `.y' in the case of `bison'), not the -generated C file. - - -File: gettext.info, Node: po/LINGUAS, Next: po/Makevars, Prev: po/POTFILES.in, Up: Adjusting Files - -13.4.2 `LINGUAS' in `po/' -------------------------- - - The `po/' directory should also receive a file named `LINGUAS'. -This file contains the list of available translations. It is a -whitespace separated list. Hash-marked comments and white lines are -ignored. Here is an example file: - - # Set of available languages. - de fr - -This example means that German and French PO files are available, so -that these languages are currently supported by your package. If you -want to further restrict, at installation time, the set of installed -languages, this should not be done by modifying the `LINGUAS' file, but -rather by using the `LINGUAS' environment variable (*note Installers::). - - It is recommended that you add the "languages" `en@quot' and -`en@boldquot' to the `LINGUAS' file. `en@quot' is a variant of English -message catalogs (`en') which uses real quotation marks instead of the -ugly looking asymmetric ASCII substitutes ``' and `''. `en@boldquot' -is a variant of `en@quot' that additionally outputs quoted pieces of -text in a bold font, when used in a terminal emulator which supports -the VT100 escape sequences (such as `xterm' or the Linux console, but -not Emacs in `M-x shell' mode). - - These extra message catalogs `en@quot' and `en@boldquot' are -constructed automatically, not by translators; to support them, you -need the files `Rules-quot', `quot.sed', `boldquot.sed', -`en@quot.header', `en@boldquot.header', `insert-header.sin' in the -`po/' directory. You can copy them from GNU gettext's `po/' directory; -they are also installed by running `gettextize'. - - -File: gettext.info, Node: po/Makevars, Next: po/Rules-*, Prev: po/LINGUAS, Up: Adjusting Files - -13.4.3 `Makevars' in `po/' --------------------------- - - The `po/' directory also has a file named `Makevars'. It contains -variables that are specific to your project. `po/Makevars' gets -inserted into the `po/Makefile' when the latter is created. The -variables thus take effect when the POT file is created or updated, and -when the message catalogs get installed. - - The first three variables can be left unmodified if your package has -a single message domain and, accordingly, a single `po/' directory. -Only packages which have multiple `po/' directories at different -locations need to adjust the three first variables defined in -`Makevars'. - - As an alternative to the `XGETTEXT_OPTIONS' variables, it is also -possible to specify `xgettext' options through the `AM_XGETTEXT_OPTION' -autoconf macro. See *note AM_XGETTEXT_OPTION::. - - -File: gettext.info, Node: po/Rules-*, Next: configure.ac, Prev: po/Makevars, Up: Adjusting Files - -13.4.4 Extending `Makefile' in `po/' ------------------------------------- - - All files called `Rules-*' in the `po/' directory get appended to -the `po/Makefile' when it is created. They present an opportunity to -add rules for special PO files to the Makefile, without needing to mess -with `po/Makefile.in.in'. - - GNU gettext comes with a `Rules-quot' file, containing rules for -building catalogs `en@quot.po' and `en@boldquot.po'. The effect of -`en@quot.po' is that people who set their `LANGUAGE' environment -variable to `en@quot' will get messages with proper looking symmetric -Unicode quotation marks instead of abusing the ASCII grave accent and -the ASCII apostrophe for indicating quotations. To enable this -catalog, simply add `en@quot' to the `po/LINGUAS' file. The effect of -`en@boldquot.po' is that people who set `LANGUAGE' to `en@boldquot' -will get not only proper quotation marks, but also the quoted text will -be shown in a bold font on terminals and consoles. This catalog is -useful only for command-line programs, not GUI programs. To enable it, -similarly add `en@boldquot' to the `po/LINGUAS' file. - - Similarly, you can create rules for building message catalogs for the -`sr@latin' locale - Serbian written with the Latin alphabet - from -those for the `sr' locale - Serbian written with Cyrillic letters. See -*note msgfilter Invocation::. - - -File: gettext.info, Node: configure.ac, Next: config.guess, Prev: po/Rules-*, Up: Adjusting Files - -13.4.5 `configure.ac' at top level ----------------------------------- - - `configure.ac' or `configure.in' - this is the source from which -`autoconf' generates the `configure' script. - - 1. Declare the package and version. - - This is done by a set of lines like these: - - PACKAGE=gettext - VERSION=0.18.1 - AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") - AC_DEFINE_UNQUOTED(VERSION, "$VERSION") - AC_SUBST(PACKAGE) - AC_SUBST(VERSION) - - or, if you are using GNU `automake', by a line like this: - - AM_INIT_AUTOMAKE(gettext, 0.18.1) - - Of course, you replace `gettext' with the name of your package, - and `0.18.1' by its version numbers, exactly as they should appear - in the packaged `tar' file name of your distribution - (`gettext-0.18.1.tar.gz', here). - - 2. Check for internationalization support. - - Here is the main `m4' macro for triggering internationalization - support. Just add this line to `configure.ac': - - AM_GNU_GETTEXT - - This call is purposely simple, even if it generates a lot of - configure time checking and actions. - - If you have suppressed the `intl/' subdirectory by calling - `gettextize' without `--intl' option, this call should read - - AM_GNU_GETTEXT([external]) - - 3. Have output files created. - - The `AC_OUTPUT' directive, at the end of your `configure.ac' file, - needs to be modified in two ways: - - AC_OUTPUT([EXISTING CONFIGURATION FILES intl/Makefile po/Makefile.in], - [EXISTING ADDITIONAL ACTIONS]) - - The modification to the first argument to `AC_OUTPUT' asks for - substitution in the `intl/' and `po/' directories. Note the `.in' - suffix used for `po/' only. This is because the distributed file - is really `po/Makefile.in.in'. - - If you have suppressed the `intl/' subdirectory by calling - `gettextize' without `--intl' option, then you don't need to add - `intl/Makefile' to the `AC_OUTPUT' line. - - - If, after doing the recommended modifications, a command like -`aclocal -I m4' or `autoconf' or `autoreconf' fails with a trace -similar to this: - - configure.ac:44: warning: AC_COMPILE_IFELSE was called before AC_GNU_SOURCE - ../../lib/autoconf/specific.m4:335: AC_GNU_SOURCE is expanded from... - m4/lock.m4:224: gl_LOCK is expanded from... - m4/gettext.m4:571: gt_INTL_SUBDIR_CORE is expanded from... - m4/gettext.m4:472: AM_INTL_SUBDIR is expanded from... - m4/gettext.m4:347: AM_GNU_GETTEXT is expanded from... - configure.ac:44: the top level - configure.ac:44: warning: AC_RUN_IFELSE was called before AC_GNU_SOURCE - -you need to add an explicit invocation of `AC_GNU_SOURCE' in the -`configure.ac' file - after `AC_PROG_CC' but before `AM_GNU_GETTEXT', -most likely very close to the `AC_PROG_CC' invocation. This is -necessary because of ordering restrictions imposed by GNU autoconf. - - -File: gettext.info, Node: config.guess, Next: mkinstalldirs, Prev: configure.ac, Up: Adjusting Files - -13.4.6 `config.guess', `config.sub' at top level ------------------------------------------------- - - If you haven't suppressed the `intl/' subdirectory, you need to add -the GNU `config.guess' and `config.sub' files to your distribution. -They are needed because the `intl/' directory has platform dependent -support for determining the locale's character encoding and therefore -needs to identify the platform. - - You can obtain the newest version of `config.guess' and `config.sub' -from the CVS of the `config' project at `http://savannah.gnu.org/'. The -commands to fetch them are - $ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess' - $ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub' - Less recent versions are also contained in the GNU `automake' and -GNU `libtool' packages. - - Normally, `config.guess' and `config.sub' are put at the top level -of a distribution. But it is also possible to put them in a -subdirectory, altogether with other configuration support files like -`install-sh', `ltconfig', `ltmain.sh' or `missing'. All you need to -do, other than moving the files, is to add the following line to your -`configure.ac'. - - AC_CONFIG_AUX_DIR([SUBDIR]) - - -File: gettext.info, Node: mkinstalldirs, Next: aclocal, Prev: config.guess, Up: Adjusting Files - -13.4.7 `mkinstalldirs' at top level ------------------------------------ - - With earlier versions of GNU gettext, you needed to add the GNU -`mkinstalldirs' script to your distribution. This is not needed any -more. You can remove it if you not also using an automake version -older than automake 1.9. - - -File: gettext.info, Node: aclocal, Next: acconfig, Prev: mkinstalldirs, Up: Adjusting Files - -13.4.8 `aclocal.m4' at top level --------------------------------- - - If you do not have an `aclocal.m4' file in your distribution, the -simplest is to concatenate the files `codeset.m4', `fcntl-o.m4', -`gettext.m4', `glibc2.m4', `glibc21.m4', `iconv.m4', `intdiv0.m4', -`intl.m4', `intldir.m4', `intlmacosx.m4', `intmax.m4', `inttypes_h.m4', -`inttypes-pri.m4', `lcmessage.m4', `lib-ld.m4', `lib-link.m4', -`lib-prefix.m4', `lock.m4', `longlong.m4', `nls.m4', `po.m4', -`printf-posix.m4', `progtest.m4', `size_max.m4', `stdint_h.m4', -`threadlib.m4', `uintmax_t.m4', `visibility.m4', `wchar_t.m4', -`wint_t.m4', `xsize.m4' from GNU `gettext''s `m4/' directory into a -single file. If you have suppressed the `intl/' directory, only -`gettext.m4', `iconv.m4', `lib-ld.m4', `lib-link.m4', `lib-prefix.m4', -`nls.m4', `po.m4', `progtest.m4' need to be concatenated. - - If you are not using GNU `automake' 1.8 or newer, you will need to -add a file `mkdirp.m4' from a newer automake distribution to the list -of files above. - - If you already have an `aclocal.m4' file, then you will have to -merge the said macro files into your `aclocal.m4'. Note that if you -are upgrading from a previous release of GNU `gettext', you should most -probably _replace_ the macros (`AM_GNU_GETTEXT', etc.), as they usually -change a little from one release of GNU `gettext' to the next. Their -contents may vary as we get more experience with strange systems out -there. - - If you are using GNU `automake' 1.5 or newer, it is enough to put -these macro files into a subdirectory named `m4/' and add the line - - ACLOCAL_AMFLAGS = -I m4 - -to your top level `Makefile.am'. - - These macros check for the internationalization support functions -and related informations. Hopefully, once stabilized, these macros -might be integrated in the standard Autoconf set, because this piece of -`m4' code will be the same for all projects using GNU `gettext'. - - -File: gettext.info, Node: acconfig, Next: config.h.in, Prev: aclocal, Up: Adjusting Files - -13.4.9 `acconfig.h' at top level --------------------------------- - - Earlier GNU `gettext' releases required to put definitions for -`ENABLE_NLS', `HAVE_GETTEXT' and `HAVE_LC_MESSAGES', `HAVE_STPCPY', -`PACKAGE' and `VERSION' into an `acconfig.h' file. This is not needed -any more; you can remove them from your `acconfig.h' file unless your -package uses them independently from the `intl/' directory. - - -File: gettext.info, Node: config.h.in, Next: Makefile, Prev: acconfig, Up: Adjusting Files - -13.4.10 `config.h.in' at top level ----------------------------------- - - The include file template that holds the C macros to be defined by -`configure' is usually called `config.h.in' and may be maintained -either manually or automatically. - - If `gettextize' has created an `intl/' directory, this file must be -called `config.h.in' and must be at the top level. If, however, you -have suppressed the `intl/' directory by calling `gettextize' without -`--intl' option, then you can choose the name of this file and its -location freely. - - If it is maintained automatically, by use of the `autoheader' -program, you need to do nothing about it. This is the case in -particular if you are using GNU `automake'. - - If it is maintained manually, and if `gettextize' has created an -`intl/' directory, you should switch to using `autoheader'. The list -of C macros to be added for the sake of the `intl/' directory is just -too long to be maintained manually; it also changes between different -versions of GNU `gettext'. - - If it is maintained manually, and if on the other hand you have -suppressed the `intl/' directory by calling `gettextize' without -`--intl' option, then you can get away by adding the following lines to -`config.h.in': - - /* Define to 1 if translation of program messages to the user's - native language is requested. */ - #undef ENABLE_NLS - - -File: gettext.info, Node: Makefile, Next: src/Makefile, Prev: config.h.in, Up: Adjusting Files - -13.4.11 `Makefile.in' at top level ----------------------------------- - - Here are a few modifications you need to make to your main, top-level -`Makefile.in' file. - - 1. Add the following lines near the beginning of your `Makefile.in', - so the `dist:' goal will work properly (as explained further down): - - PACKAGE = @PACKAGE@ - VERSION = @VERSION@ - - 2. Add file `ABOUT-NLS' to the `DISTFILES' definition, so the file - gets distributed. - - 3. Wherever you process subdirectories in your `Makefile.in', be sure - you also process the subdirectories `intl' and `po'. Special - rules in the `Makefiles' take care for the case where no - internationalization is wanted. - - If you are using Makefiles, either generated by automake, or - hand-written so they carefully follow the GNU coding standards, - the effected goals for which the new subdirectories must be - handled include `installdirs', `install', `uninstall', `clean', - `distclean'. - - Here is an example of a canonical order of processing. In this - example, we also define `SUBDIRS' in `Makefile.in' for it to be - further used in the `dist:' goal. - - SUBDIRS = doc intl lib src po - - Note that you must arrange for `make' to descend into the `intl' - directory before descending into other directories containing code - which make use of the `libintl.h' header file. For this reason, - here we mention `intl' before `lib' and `src'. - - 4. A delicate point is the `dist:' goal, as both `intl/Makefile' and - `po/Makefile' will later assume that the proper directory has been - set up from the main `Makefile'. Here is an example at what the - `dist:' goal might look like: - - distdir = $(PACKAGE)-$(VERSION) - dist: Makefile - rm -fr $(distdir) - mkdir $(distdir) - chmod 777 $(distdir) - for file in $(DISTFILES); do \ - ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ - done - for subdir in $(SUBDIRS); do \ - mkdir $(distdir)/$$subdir || exit 1; \ - chmod 777 $(distdir)/$$subdir; \ - (cd $$subdir && $(MAKE) $@) || exit 1; \ - done - tar chozf $(distdir).tar.gz $(distdir) - rm -fr $(distdir) - - - Note that if you are using GNU `automake', `Makefile.in' is -automatically generated from `Makefile.am', and all needed changes to -`Makefile.am' are already made by running `gettextize'. - - -File: gettext.info, Node: src/Makefile, Next: lib/gettext.h, Prev: Makefile, Up: Adjusting Files - -13.4.12 `Makefile.in' in `src/' -------------------------------- - - Some of the modifications made in the main `Makefile.in' will also -be needed in the `Makefile.in' from your package sources, which we -assume here to be in the `src/' subdirectory. Here are all the -modifications needed in `src/Makefile.in': - - 1. In view of the `dist:' goal, you should have these lines near the - beginning of `src/Makefile.in': - - PACKAGE = @PACKAGE@ - VERSION = @VERSION@ - - 2. If not done already, you should guarantee that `top_srcdir' gets - defined. This will serve for `cpp' include files. Just add the - line: - - top_srcdir = @top_srcdir@ - - 3. You might also want to define `subdir' as `src', later allowing - for almost uniform `dist:' goals in all your `Makefile.in'. At - list, the `dist:' goal below assume that you used: - - subdir = src - - 4. The `main' function of your program will normally call - `bindtextdomain' (see *note Triggering::), like this: - - bindtextdomain (PACKAGE, LOCALEDIR); - textdomain (PACKAGE); - - To make LOCALEDIR known to the program, add the following lines to - `Makefile.in' if you are using Autoconf version 2.60 or newer: - - datadir = @datadir@ - datarootdir= @datarootdir@ - localedir = @localedir@ - DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@ - - or these lines if your version of Autoconf is older than 2.60: - - datadir = @datadir@ - localedir = $(datadir)/locale - DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@ - - Note that `@datadir@' defaults to `$(prefix)/share', thus - `$(localedir)' defaults to `$(prefix)/share/locale'. - - 5. You should ensure that the final linking will use `@LIBINTL@' or - `@LTLIBINTL@' as a library. `@LIBINTL@' is for use without - `libtool', `@LTLIBINTL@' is for use with `libtool'. An easy way - to achieve this is to manage that it gets into `LIBS', like this: - - LIBS = @LIBINTL@ @LIBS@ - - In most packages internationalized with GNU `gettext', one will - find a directory `lib/' in which a library containing some helper - functions will be build. (You need at least the few functions - which the GNU `gettext' Library itself needs.) However some of - the functions in the `lib/' also give messages to the user which - of course should be translated, too. Taking care of this, the - support library (say `libsupport.a') should be placed before - `@LIBINTL@' and `@LIBS@' in the above example. So one has to - write this: - - LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@ - - 6. You should also ensure that directory `intl/' will be searched for - C preprocessor include files in all circumstances. So, you have to - manage so both `-I../intl' and `-I$(top_srcdir)/intl' will be - given to the C compiler. - - 7. Your `dist:' goal has to conform with others. Here is a - reasonable definition for it: - - distdir = ../$(PACKAGE)-$(VERSION)/$(subdir) - dist: Makefile $(DISTFILES) - for file in $(DISTFILES); do \ - ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \ - done - - - Note that if you are using GNU `automake', `Makefile.in' is -automatically generated from `Makefile.am', and the first three changes -and the last change are not necessary. The remaining needed -`Makefile.am' modifications are the following: - - 1. To make LOCALEDIR known to the program, add the following to - `Makefile.am': - - <module>_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\" - - for each specific module or compilation unit, or - - AM_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\" - - for all modules and compilation units together. Furthermore, if - you are using an Autoconf version older then 2.60, add this line - to define `localedir': - - localedir = $(datadir)/locale - - 2. To ensure that the final linking will use `@LIBINTL@' or - `@LTLIBINTL@' as a library, add the following to `Makefile.am': - - <program>_LDADD = @LIBINTL@ - - for each specific program, or - - LDADD = @LIBINTL@ - - for all programs together. Remember that when you use `libtool' - to link a program, you need to use @LTLIBINTL@ instead of @LIBINTL@ - for that program. - - 3. If you have an `intl/' directory, whose contents is created by - `gettextize', then to ensure that it will be searched for C - preprocessor include files in all circumstances, add something like - this to `Makefile.am': - - AM_CPPFLAGS = -I../intl -I$(top_srcdir)/intl - - - -File: gettext.info, Node: lib/gettext.h, Prev: src/Makefile, Up: Adjusting Files - -13.4.13 `gettext.h' in `lib/' ------------------------------ - - Internationalization of packages, as provided by GNU `gettext', is -optional. It can be turned off in two situations: - - * When the installer has specified `./configure --disable-nls'. This - can be useful when small binaries are more important than - features, for example when building utilities for boot diskettes. - It can also be useful in order to get some specific C compiler - warnings about code quality with some older versions of GCC (older - than 3.0). - - * When the package does not include the `intl/' subdirectory, and the - libintl.h header (with its associated libintl library, if any) is - not already installed on the system, it is preferable that the - package builds without internationalization support, rather than - to give a compilation error. - - A C preprocessor macro can be used to detect these two cases. -Usually, when `libintl.h' was found and not explicitly disabled, the -`ENABLE_NLS' macro will be defined to 1 in the autoconf generated -configuration file (usually called `config.h'). In the two negative -situations, however, this macro will not be defined, thus it will -evaluate to 0 in C preprocessor expressions. - - `gettext.h' is a convenience header file for conditional use of -`<libintl.h>', depending on the `ENABLE_NLS' macro. If `ENABLE_NLS' is -set, it includes `<libintl.h>'; otherwise it defines no-op substitutes -for the libintl.h functions. We recommend the use of `"gettext.h"' -over direct use of `<libintl.h>', so that portability to older systems -is guaranteed and installers can turn off internationalization if they -want to. In the C code, you will then write - - #include "gettext.h" - -instead of - - #include <libintl.h> - - The location of `gettext.h' is usually in a directory containing -auxiliary include files. In many GNU packages, there is a directory -`lib/' containing helper functions; `gettext.h' fits there. In other -packages, it can go into the `src' directory. - - Do not install the `gettext.h' file in public locations. Every -package that needs it should contain a copy of it on its own. - - -File: gettext.info, Node: autoconf macros, Next: CVS Issues, Prev: Adjusting Files, Up: Maintainers - -13.5 Autoconf macros for use in `configure.ac' -============================================== - - GNU `gettext' installs macros for use in a package's `configure.ac' -or `configure.in'. *Note Introduction: (autoconf)Top. The primary -macro is, of course, `AM_GNU_GETTEXT'. - -* Menu: - -* AM_GNU_GETTEXT:: AM_GNU_GETTEXT in `gettext.m4' -* AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in `gettext.m4' -* AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in `gettext.m4' -* AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4' -* AM_PO_SUBDIRS:: AM_PO_SUBDIRS in `po.m4' -* AM_XGETTEXT_OPTION:: AM_XGETTEXT_OPTION in `po.m4' -* AM_ICONV:: AM_ICONV in `iconv.m4' - - -File: gettext.info, Node: AM_GNU_GETTEXT, Next: AM_GNU_GETTEXT_VERSION, Prev: autoconf macros, Up: autoconf macros - -13.5.1 AM_GNU_GETTEXT in `gettext.m4' -------------------------------------- - - The `AM_GNU_GETTEXT' macro tests for the presence of the GNU gettext -function family in either the C library or a separate `libintl' library -(shared or static libraries are both supported) or in the package's -`intl/' directory. It also invokes `AM_PO_SUBDIRS', thus preparing the -`po/' directories of the package for building. - - `AM_GNU_GETTEXT' accepts up to three optional arguments. The general -syntax is - - AM_GNU_GETTEXT([INTLSYMBOL], [NEEDSYMBOL], [INTLDIR]) - - INTLSYMBOL can be `external' or `no-libtool'. The default (if it is -not specified or empty) is `no-libtool'. INTLSYMBOL should be -`external' for packages with no `intl/' directory. For packages with -an `intl/' directory, you can either use an INTLSYMBOL equal to -`no-libtool', or you can use `external' and override by using the macro -`AM_GNU_GETTEXT_INTL_SUBDIR' elsewhere. The two ways to specify the -existence of an `intl/' directory are equivalent. At build time, a -static library `$(top_builddir)/intl/libintl.a' will then be created. - - If NEEDSYMBOL is specified and is `need-ngettext', then GNU gettext -implementations (in libc or libintl) without the `ngettext()' function -will be ignored. If NEEDSYMBOL is specified and is -`need-formatstring-macros', then GNU gettext implementations that don't -support the ISO C 99 `<inttypes.h>' formatstring macros will be ignored. -Only one NEEDSYMBOL can be specified. These requirements can also be -specified by using the macro `AM_GNU_GETTEXT_NEED' elsewhere. To -specify more than one requirement, just specify the strongest one among -them, or invoke the `AM_GNU_GETTEXT_NEED' macro several times. The -hierarchy among the various alternatives is as follows: -`need-formatstring-macros' implies `need-ngettext'. - - INTLDIR is used to find the intl libraries. If empty, the value -`$(top_builddir)/intl/' is used. - - The `AM_GNU_GETTEXT' macro determines whether GNU gettext is -available and should be used. If so, it sets the `USE_NLS' variable to -`yes'; it defines `ENABLE_NLS' to 1 in the autoconf generated -configuration file (usually called `config.h'); it sets the variables -`LIBINTL' and `LTLIBINTL' to the linker options for use in a Makefile -(`LIBINTL' for use without libtool, `LTLIBINTL' for use with libtool); -it adds an `-I' option to `CPPFLAGS' if necessary. In the negative -case, it sets `USE_NLS' to `no'; it sets `LIBINTL' and `LTLIBINTL' to -empty and doesn't change `CPPFLAGS'. - - The complexities that `AM_GNU_GETTEXT' deals with are the following: - - * Some operating systems have `gettext' in the C library, for example - glibc. Some have it in a separate library `libintl'. GNU - `libintl' might have been installed as part of the GNU `gettext' - package. - - * GNU `libintl', if installed, is not necessarily already in the - search path (`CPPFLAGS' for the include file search path, - `LDFLAGS' for the library search path). - - * Except for glibc, the operating system's native `gettext' cannot - exploit the GNU mo files, doesn't have the necessary locale - dependency features, and cannot convert messages from the - catalog's text encoding to the user's locale encoding. - - * GNU `libintl', if installed, is not necessarily already in the run - time library search path. To avoid the need for setting an - environment variable like `LD_LIBRARY_PATH', the macro adds the - appropriate run time search path options to the `LIBINTL' and - `LTLIBINTL' variables. This works on most systems, but not on - some operating systems with limited shared library support, like - SCO. - - * GNU `libintl' relies on POSIX/XSI `iconv'. The macro checks for - linker options needed to use iconv and appends them to the - `LIBINTL' and `LTLIBINTL' variables. - - -File: gettext.info, Node: AM_GNU_GETTEXT_VERSION, Next: AM_GNU_GETTEXT_NEED, Prev: AM_GNU_GETTEXT, Up: autoconf macros - -13.5.2 AM_GNU_GETTEXT_VERSION in `gettext.m4' ---------------------------------------------- - - The `AM_GNU_GETTEXT_VERSION' macro declares the version number of -the GNU gettext infrastructure that is used by the package. - - The use of this macro is optional; only the `autopoint' program makes -use of it (*note CVS Issues::). - - -File: gettext.info, Node: AM_GNU_GETTEXT_NEED, Next: AM_GNU_GETTEXT_INTL_SUBDIR, Prev: AM_GNU_GETTEXT_VERSION, Up: autoconf macros - -13.5.3 AM_GNU_GETTEXT_NEED in `gettext.m4' ------------------------------------------- - - The `AM_GNU_GETTEXT_NEED' macro declares a constraint regarding the -GNU gettext implementation. The syntax is - - AM_GNU_GETTEXT_NEED([NEEDSYMBOL]) - - If NEEDSYMBOL is `need-ngettext', then GNU gettext implementations -(in libc or libintl) without the `ngettext()' function will be ignored. -If NEEDSYMBOL is `need-formatstring-macros', then GNU gettext -implementations that don't support the ISO C 99 `<inttypes.h>' -formatstring macros will be ignored. - - The optional second argument of `AM_GNU_GETTEXT' is also taken into -account. - - The `AM_GNU_GETTEXT_NEED' invocations can occur before or after the -`AM_GNU_GETTEXT' invocation; the order doesn't matter. - - -File: gettext.info, Node: AM_GNU_GETTEXT_INTL_SUBDIR, Next: AM_PO_SUBDIRS, Prev: AM_GNU_GETTEXT_NEED, Up: autoconf macros - -13.5.4 AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4' -------------------------------------------------- - - The `AM_GNU_GETTEXT_INTL_SUBDIR' macro specifies that the -`AM_GNU_GETTEXT' macro, although invoked with the first argument -`external', should also prepare for building the `intl/' subdirectory. - - The `AM_GNU_GETTEXT_INTL_SUBDIR' invocation can occur before or after -the `AM_GNU_GETTEXT' invocation; the order doesn't matter. - - The use of this macro requires GNU automake 1.10 or newer and GNU -autoconf 2.61 or newer. - - -File: gettext.info, Node: AM_PO_SUBDIRS, Next: AM_XGETTEXT_OPTION, Prev: AM_GNU_GETTEXT_INTL_SUBDIR, Up: autoconf macros - -13.5.5 AM_PO_SUBDIRS in `po.m4' -------------------------------- - - The `AM_PO_SUBDIRS' macro prepares the `po/' directories of the -package for building. This macro should be used in internationalized -programs written in other programming languages than C, C++, Objective -C, for example `sh', `Python', `Lisp'. See *note Programming -Languages:: for a list of programming languages that support -localization through PO files. - - The `AM_PO_SUBDIRS' macro determines whether internationalization -should be used. If so, it sets the `USE_NLS' variable to `yes', -otherwise to `no'. It also determines the right values for Makefile -variables in each `po/' directory. - - -File: gettext.info, Node: AM_XGETTEXT_OPTION, Next: AM_ICONV, Prev: AM_PO_SUBDIRS, Up: autoconf macros - -13.5.6 AM_XGETTEXT_OPTION in `po.m4' ------------------------------------- - - The `AM_XGETTEXT_OPTION' macro registers a command-line option to be -used in the invocations of `xgettext' in the `po/' directories of the -package. - - For example, if you have a source file that defines a function -`error_at_line' whose fifth argument is a format string, you can use - AM_XGETTEXT_OPTION([--flag=error_at_line:5:c-format]) - to instruct `xgettext' to mark all translatable strings in `gettext' -invocations that occur as fifth argument to this function as `c-format'. - - See *note xgettext Invocation:: for the list of options that -`xgettext' accepts. - - The use of this macro is an alternative to the use of the -`XGETTEXT_OPTIONS' variable in `po/Makevars'. - - -File: gettext.info, Node: AM_ICONV, Prev: AM_XGETTEXT_OPTION, Up: autoconf macros - -13.5.7 AM_ICONV in `iconv.m4' ------------------------------ - - The `AM_ICONV' macro tests for the presence of the POSIX/XSI `iconv' -function family in either the C library or a separate `libiconv' -library. If found, it sets the `am_cv_func_iconv' variable to `yes'; -it defines `HAVE_ICONV' to 1 in the autoconf generated configuration -file (usually called `config.h'); it defines `ICONV_CONST' to `const' -or to empty, depending on whether the second argument of `iconv()' is -of type `const char **' or `char **'; it sets the variables `LIBICONV' -and `LTLIBICONV' to the linker options for use in a Makefile -(`LIBICONV' for use without libtool, `LTLIBICONV' for use with -libtool); it adds an `-I' option to `CPPFLAGS' if necessary. If not -found, it sets `LIBICONV' and `LTLIBICONV' to empty and doesn't change -`CPPFLAGS'. - - The complexities that `AM_ICONV' deals with are the following: - - * Some operating systems have `iconv' in the C library, for example - glibc. Some have it in a separate library `libiconv', for example - OSF/1 or FreeBSD. Regardless of the operating system, GNU - `libiconv' might have been installed. In that case, it should be - used instead of the operating system's native `iconv'. - - * GNU `libiconv', if installed, is not necessarily already in the - search path (`CPPFLAGS' for the include file search path, - `LDFLAGS' for the library search path). - - * GNU `libiconv' is binary incompatible with some operating system's - native `iconv', for example on FreeBSD. Use of an `iconv.h' and - `libiconv.so' that don't fit together would produce program - crashes. - - * GNU `libiconv', if installed, is not necessarily already in the - run time library search path. To avoid the need for setting an - environment variable like `LD_LIBRARY_PATH', the macro adds the - appropriate run time search path options to the `LIBICONV' - variable. This works on most systems, but not on some operating - systems with limited shared library support, like SCO. - - `iconv.m4' is distributed with the GNU gettext package because -`gettext.m4' relies on it. - - -File: gettext.info, Node: CVS Issues, Next: Release Management, Prev: autoconf macros, Up: Maintainers - -13.6 Integrating with CVS -========================= - - Many projects use CVS for distributed development, version control -and source backup. This section gives some advice how to manage the -uses of `cvs', `gettextize', `autopoint' and `autoconf'. - -* Menu: - -* Distributed CVS:: Avoiding version mismatch in distributed development -* Files under CVS:: Files to put under CVS version control -* autopoint Invocation:: Invoking the `autopoint' Program - - -File: gettext.info, Node: Distributed CVS, Next: Files under CVS, Prev: CVS Issues, Up: CVS Issues - -13.6.1 Avoiding version mismatch in distributed development ------------------------------------------------------------ - - In a project development with multiple developers, using CVS, there -should be a single developer who occasionally - when there is desire to -upgrade to a new `gettext' version - runs `gettextize' and performs the -changes listed in *note Adjusting Files::, and then commits his changes -to the CVS. - - It is highly recommended that all developers on a project use the -same version of GNU `gettext' in the package. In other words, if a -developer runs `gettextize', he should go the whole way, make the -necessary remaining changes and commit his changes to the CVS. -Otherwise the following damages will likely occur: - - * Apparent version mismatch between developers. Since some `gettext' - specific portions in `configure.ac', `configure.in' and - `Makefile.am', `Makefile.in' files depend on the `gettext' - version, the use of infrastructure files belonging to different - `gettext' versions can easily lead to build errors. - - * Hidden version mismatch. Such version mismatch can also lead to - malfunctioning of the package, that may be undiscovered by the - developers. The worst case of hidden version mismatch is that - internationalization of the package doesn't work at all. - - * Release risks. All developers implicitly perform constant testing - on a package. This is important in the days and weeks before a - release. If the guy who makes the release tar files uses a - different version of GNU `gettext' than the other developers, the - distribution will be less well tested than if all had been using - the same `gettext' version. For example, it is possible that a - platform specific bug goes undiscovered due to this constellation. - - -File: gettext.info, Node: Files under CVS, Next: autopoint Invocation, Prev: Distributed CVS, Up: CVS Issues - -13.6.2 Files to put under CVS version control ---------------------------------------------- - - There are basically three ways to deal with generated files in the -context of a CVS repository, such as `configure' generated from -`configure.ac', `PARSER.c' generated from `PARSER.y', or -`po/Makefile.in.in' autoinstalled by `gettextize' or `autopoint'. - - 1. All generated files are always committed into the repository. - - 2. All generated files are committed into the repository occasionally, - for example each time a release is made. - - 3. Generated files are never committed into the repository. - - Each of these three approaches has different advantages and -drawbacks. - - 1. The advantage is that anyone can check out the CVS at any moment - and gets a working build. The drawbacks are: 1a. It requires - some frequent "cvs commit" actions by the maintainers. 1b. The - repository grows in size quite fast. - - 2. The advantage is that anyone can check out the CVS, and the usual - "./configure; make" will work. The drawbacks are: 2a. The one who - checks out the repository needs tools like GNU `automake', GNU - `autoconf', GNU `m4' installed in his PATH; sometimes he even - needs particular versions of them. 2b. When a release is made and - a commit is made on the generated files, the other developers get - conflicts on the generated files after doing "cvs update". - Although these conflicts are easy to resolve, they are annoying. - - 3. The advantage is less work for the maintainers. The drawback is - that anyone who checks out the CVS not only needs tools like GNU - `automake', GNU `autoconf', GNU `m4' installed in his PATH, but - also that he needs to perform a package specific pre-build step - before being able to "./configure; make". - - For the first and second approach, all files modified or brought in -by the occasional `gettextize' invocation and update should be -committed into the CVS. - - For the third approach, the maintainer can omit from the CVS -repository all the files that `gettextize' mentions as "copy". -Instead, he adds to the `configure.ac' or `configure.in' a line of the -form - - AM_GNU_GETTEXT_VERSION(0.18.1) - -and adds to the package's pre-build script an invocation of -`autopoint'. For everyone who checks out the CVS, this `autopoint' -invocation will copy into the right place the `gettext' infrastructure -files that have been omitted from the CVS. - - The version number used as argument to `AM_GNU_GETTEXT_VERSION' is -the version of the `gettext' infrastructure that the package wants to -use. It is also the minimum version number of the `autopoint' program. -So, if you write `AM_GNU_GETTEXT_VERSION(0.11.5)' then the developers -can have any version >= 0.11.5 installed; the package will work with -the 0.11.5 infrastructure in all developers' builds. When the -maintainer then runs gettextize from, say, version 0.12.1 on the -package, the occurrence of `AM_GNU_GETTEXT_VERSION(0.11.5)' will be -changed into `AM_GNU_GETTEXT_VERSION(0.12.1)', and all other developers -that use the CVS will henceforth need to have GNU `gettext' 0.12.1 or -newer installed. - - -File: gettext.info, Node: autopoint Invocation, Prev: Files under CVS, Up: CVS Issues - -13.6.3 Invoking the `autopoint' Program ---------------------------------------- - - autopoint [OPTION]... - - The `autopoint' program copies standard gettext infrastructure files -into a source package. It extracts from a macro call of the form -`AM_GNU_GETTEXT_VERSION(VERSION)', found in the package's -`configure.in' or `configure.ac' file, the gettext version used by the -package, and copies the infrastructure files belonging to this version -into the package. - -13.6.3.1 Options -................ - -`-f' -`--force' - Force overwriting of files that already exist. - -`-n' -`--dry-run' - Print modifications but don't perform them. All file copying - actions that `autopoint' would normally execute are inhibited and - instead only listed on standard output. - - -13.6.3.2 Informative output -........................... - -`--help' - Display this help and exit. - -`--version' - Output version information and exit. - - - `autopoint' supports the GNU `gettext' versions from 0.10.35 to the -current one, 0.18.1. In order to apply `autopoint' to a package using -a `gettext' version newer than 0.18.1, you need to install this same -version of GNU `gettext' at least. - - In packages using GNU `automake', an invocation of `autopoint' -should be followed by invocations of `aclocal' and then `autoconf' and -`autoheader'. The reason is that `autopoint' installs some autoconf -macro files, which are used by `aclocal' to create `aclocal.m4', and -the latter is used by `autoconf' to create the package's `configure' -script and by `autoheader' to create the package's `config.h.in' -include file template. - - The name `autopoint' is an abbreviation of `auto-po-intl-m4'; the -tool copies or updates mostly files in the `po', `intl', `m4' -directories. - - -File: gettext.info, Node: Release Management, Prev: CVS Issues, Up: Maintainers - -13.7 Creating a Distribution Tarball -==================================== - - In projects that use GNU `automake', the usual commands for creating -a distribution tarball, `make dist' or `make distcheck', automatically -update the PO files as needed. - - If GNU `automake' is not used, the maintainer needs to perform this -update before making a release: - - $ ./configure - $ (cd po; make update-po) - $ make distclean - - -File: gettext.info, Node: Installers, Next: Programming Languages, Prev: Maintainers, Up: Top - -14 The Installer's and Distributor's View -***************************************** - - By default, packages fully using GNU `gettext', internally, are -installed in such a way that they to allow translation of messages. At -_configuration_ time, those packages should automatically detect -whether the underlying host system already provides the GNU `gettext' -functions. If not, the GNU `gettext' library should be automatically -prepared and used. Installers may use special options at configuration -time for changing this behavior. The command `./configure ---with-included-gettext' bypasses system `gettext' to use the included -GNU `gettext' instead, while `./configure --disable-nls' produces -programs totally unable to translate messages. - - Internationalized packages have usually many `LL.po' files. Unless -translations are disabled, all those available are installed together -with the package. However, the environment variable `LINGUAS' may be -set, prior to configuration, to limit the installed set. `LINGUAS' -should then contain a space separated list of two-letter codes, stating -which languages are allowed. - - -File: gettext.info, Node: Programming Languages, Next: Conclusion, Prev: Installers, Up: Top - -15 Other Programming Languages -****************************** - - While the presentation of `gettext' focuses mostly on C and -implicitly applies to C++ as well, its scope is far broader than that: -Many programming languages, scripting languages and other textual data -like GUI resources or package descriptions can make use of the gettext -approach. - -* Menu: - -* Language Implementors:: The Language Implementor's View -* Programmers for other Languages:: The Programmer's View -* Translators for other Languages:: The Translator's View -* Maintainers for other Languages:: The Maintainer's View -* List of Programming Languages:: Individual Programming Languages -* List of Data Formats:: Internationalizable Data - - -File: gettext.info, Node: Language Implementors, Next: Programmers for other Languages, Prev: Programming Languages, Up: Programming Languages - -15.1 The Language Implementor's View -==================================== - - All programming and scripting languages that have the notion of -strings are eligible to supporting `gettext'. Supporting `gettext' -means the following: - - 1. You should add to the language a syntax for translatable strings. - In principle, a function call of `gettext' would do, but a - shorthand syntax helps keeping the legibility of internationalized - programs. For example, in C we use the syntax `_("string")', and - in GNU awk we use the shorthand `_"string"'. - - 2. You should arrange that evaluation of such a translatable string at - runtime calls the `gettext' function, or performs equivalent - processing. - - 3. Similarly, you should make the functions `ngettext', `dcgettext', - `dcngettext' available from within the language. These functions - are less often used, but are nevertheless necessary for particular - purposes: `ngettext' for correct plural handling, and `dcgettext' - and `dcngettext' for obeying other locale-related environment - variables than `LC_MESSAGES', such as `LC_TIME' or `LC_MONETARY'. - For these latter functions, you need to make the `LC_*' constants, - available in the C header `<locale.h>', referenceable from within - the language, usually either as enumeration values or as strings. - - 4. You should allow the programmer to designate a message domain, - either by making the `textdomain' function available from within - the language, or by introducing a magic variable called - `TEXTDOMAIN'. Similarly, you should allow the programmer to - designate where to search for message catalogs, by providing - access to the `bindtextdomain' function. - - 5. You should either perform a `setlocale (LC_ALL, "")' call during - the startup of your language runtime, or allow the programmer to - do so. Remember that gettext will act as a no-op if the - `LC_MESSAGES' and `LC_CTYPE' locale categories are not both set. - - 6. A programmer should have a way to extract translatable strings - from a program into a PO file. The GNU `xgettext' program is being - extended to support very different programming languages. Please - contact the GNU `gettext' maintainers to help them doing this. If - the string extractor is best integrated into your language's - parser, GNU `xgettext' can function as a front end to your string - extractor. - - 7. The language's library should have a string formatting facility - where the arguments of a format string are denoted by a positional - number or a name. This is needed because for some languages and - some messages with more than one substitutable argument, the - translation will need to output the substituted arguments in - different order. *Note c-format Flag::. - - 8. If the language has more than one implementation, and not all of - the implementations use `gettext', but the programs should be - portable across implementations, you should provide a no-i18n - emulation, that makes the other implementations accept programs - written for yours, without actually translating the strings. - - 9. To help the programmer in the task of marking translatable strings, - which is sometimes performed using the Emacs PO mode (*note - Marking::), you are welcome to contact the GNU `gettext' - maintainers, so they can add support for your language to - `po-mode.el'. - - On the implementation side, three approaches are possible, with -different effects on portability and copyright: - - * You may integrate the GNU `gettext''s `intl/' directory in your - package, as described in *note Maintainers::. This allows you to - have internationalization on all kinds of platforms. Note that - when you then distribute your package, it legally falls under the - GNU General Public License, and the GNU project will be glad about - your contribution to the Free Software pool. - - * You may link against GNU `gettext' functions if they are found in - the C library. For example, an autoconf test for `gettext()' and - `ngettext()' will detect this situation. For the moment, this test - will succeed on GNU systems and not on other platforms. No severe - copyright restrictions apply. - - * You may emulate or reimplement the GNU `gettext' functionality. - This has the advantage of full portability and no copyright - restrictions, but also the drawback that you have to reimplement - the GNU `gettext' features (such as the `LANGUAGE' environment - variable, the locale aliases database, the automatic charset - conversion, and plural handling). - - -File: gettext.info, Node: Programmers for other Languages, Next: Translators for other Languages, Prev: Language Implementors, Up: Programming Languages - -15.2 The Programmer's View -========================== - - For the programmer, the general procedure is the same as for the C -language. The Emacs PO mode marking supports other languages, and the -GNU `xgettext' string extractor recognizes other languages based on the -file extension or a command-line option. In some languages, -`setlocale' is not needed because it is already performed by the -underlying language runtime. - - -File: gettext.info, Node: Translators for other Languages, Next: Maintainers for other Languages, Prev: Programmers for other Languages, Up: Programming Languages - -15.3 The Translator's View -========================== - - The translator works exactly as in the C language case. The only -difference is that when translating format strings, she has to be aware -of the language's particular syntax for positional arguments in format -strings. - -* Menu: - -* c-format:: C Format Strings -* objc-format:: Objective C Format Strings -* sh-format:: Shell Format Strings -* python-format:: Python Format Strings -* lisp-format:: Lisp Format Strings -* elisp-format:: Emacs Lisp Format Strings -* librep-format:: librep Format Strings -* scheme-format:: Scheme Format Strings -* smalltalk-format:: Smalltalk Format Strings -* java-format:: Java Format Strings -* csharp-format:: C# Format Strings -* awk-format:: awk Format Strings -* object-pascal-format:: Object Pascal Format Strings -* ycp-format:: YCP Format Strings -* tcl-format:: Tcl Format Strings -* perl-format:: Perl Format Strings -* php-format:: PHP Format Strings -* gcc-internal-format:: GCC internal Format Strings -* gfc-internal-format:: GFC internal Format Strings -* qt-format:: Qt Format Strings -* qt-plural-format:: Qt Plural Format Strings -* kde-format:: KDE Format Strings -* boost-format:: Boost Format Strings - - -File: gettext.info, Node: c-format, Next: objc-format, Prev: Translators for other Languages, Up: Translators for other Languages - -15.3.1 C Format Strings ------------------------ - - C format strings are described in POSIX (IEEE P1003.1 2001), section -XSH 3 fprintf(), -`http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html'. -See also the fprintf() manual page, -`http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php', -`http://informatik.fh-wuerzburg.de/student/i510/man/printf.html'. - - Although format strings with positions that reorder arguments, such -as - - "Only %2$d bytes free on '%1$s'." - -which is semantically equivalent to - - "'%s' has only %d bytes free." - -are a POSIX/XSI feature and not specified by ISO C 99, translators can -rely on this reordering ability: On the few platforms where `printf()', -`fprintf()' etc. don't support this feature natively, `libintl.a' or -`libintl.so' provides replacement functions, and GNU `<libintl.h>' -activates these replacement functions automatically. - - As a special feature for Farsi (Persian) and maybe Arabic, -translators can insert an `I' flag into numeric format directives. For -example, the translation of `"%d"' can be `"%Id"'. The effect of this -flag, on systems with GNU `libc', is that in the output, the ASCII -digits are replaced with the `outdigits' defined in the `LC_CTYPE' -locale category. On other systems, the `gettext' function removes this -flag, so that it has no effect. - - Note that the programmer should _not_ put this flag into the -untranslated string. (Putting the `I' format directive flag into an -MSGID string would lead to undefined behaviour on platforms without -glibc when NLS is disabled.) - - -File: gettext.info, Node: objc-format, Next: sh-format, Prev: c-format, Up: Translators for other Languages - -15.3.2 Objective C Format Strings ---------------------------------- - - Objective C format strings are like C format strings. They support -an additional format directive: "%@", which when executed consumes an -argument of type `Object *'. - - -File: gettext.info, Node: sh-format, Next: python-format, Prev: objc-format, Up: Translators for other Languages - -15.3.3 Shell Format Strings ---------------------------- - - Shell format strings, as supported by GNU gettext and the `envsubst' -program, are strings with references to shell variables in the form -`$VARIABLE' or `${VARIABLE}'. References of the form -`${VARIABLE-DEFAULT}', `${VARIABLE:-DEFAULT}', `${VARIABLE=DEFAULT}', -`${VARIABLE:=DEFAULT}', `${VARIABLE+REPLACEMENT}', -`${VARIABLE:+REPLACEMENT}', `${VARIABLE?IGNORED}', -`${VARIABLE:?IGNORED}', that would be valid inside shell scripts, are -not supported. The VARIABLE names must consist solely of alphanumeric -or underscore ASCII characters, not start with a digit and be nonempty; -otherwise such a variable reference is ignored. - - -File: gettext.info, Node: python-format, Next: lisp-format, Prev: sh-format, Up: Translators for other Languages - -15.3.4 Python Format Strings ----------------------------- - - Python format strings are described in Python Library reference / -2. Built-in Types, Exceptions and Functions / 2.2. Built-in Types / -2.2.6. Sequence Types / 2.2.6.2. String Formatting Operations. -`http://www.python.org/doc/2.2.1/lib/typesseq-strings.html'. - - -File: gettext.info, Node: lisp-format, Next: elisp-format, Prev: python-format, Up: Translators for other Languages - -15.3.5 Lisp Format Strings --------------------------- - - Lisp format strings are described in the Common Lisp HyperSpec, -chapter 22.3 Formatted Output, -`http://www.lisp.org/HyperSpec/Body/sec_22-3.html'. - - -File: gettext.info, Node: elisp-format, Next: librep-format, Prev: lisp-format, Up: Translators for other Languages - -15.3.6 Emacs Lisp Format Strings --------------------------------- - - Emacs Lisp format strings are documented in the Emacs Lisp reference, -section Formatting Strings, -`http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75'. -Note that as of version 21, XEmacs supports numbered argument -specifications in format strings while FSF Emacs doesn't. - - -File: gettext.info, Node: librep-format, Next: scheme-format, Prev: elisp-format, Up: Translators for other Languages - -15.3.7 librep Format Strings ----------------------------- - - librep format strings are documented in the librep manual, section -Formatted Output, -`http://librep.sourceforge.net/librep-manual.html#Formatted%20Output', -`http://www.gwinnup.org/research/docs/librep.html#SEC122'. - - -File: gettext.info, Node: scheme-format, Next: smalltalk-format, Prev: librep-format, Up: Translators for other Languages - -15.3.8 Scheme Format Strings ----------------------------- - - Scheme format strings are documented in the SLIB manual, section -Format Specification. - - -File: gettext.info, Node: smalltalk-format, Next: java-format, Prev: scheme-format, Up: Translators for other Languages - -15.3.9 Smalltalk Format Strings -------------------------------- - - Smalltalk format strings are described in the GNU Smalltalk -documentation, class `CharArray', methods `bindWith:' and -`bindWithArguments:'. -`http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238'. -In summary, a directive starts with `%' and is followed by `%' or a -nonzero digit (`1' to `9'). - - -File: gettext.info, Node: java-format, Next: csharp-format, Prev: smalltalk-format, Up: Translators for other Languages - -15.3.10 Java Format Strings ---------------------------- - - Java format strings are described in the JDK documentation for class -`java.text.MessageFormat', -`http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html'. -See also the ICU documentation -`http://oss.software.ibm.com/icu/apiref/classMessageFormat.html'. - - -File: gettext.info, Node: csharp-format, Next: awk-format, Prev: java-format, Up: Translators for other Languages - -15.3.11 C# Format Strings -------------------------- - - C# format strings are described in the .NET documentation for class -`System.String' and in -`http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp'. - - -File: gettext.info, Node: awk-format, Next: object-pascal-format, Prev: csharp-format, Up: Translators for other Languages - -15.3.12 awk Format Strings --------------------------- - - awk format strings are described in the gawk documentation, section -Printf, `http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf'. - - -File: gettext.info, Node: object-pascal-format, Next: ycp-format, Prev: awk-format, Up: Translators for other Languages - -15.3.13 Object Pascal Format Strings ------------------------------------- - - Object Pascal format strings are described in the documentation of -the Free Pascal runtime library, section Format, -`http://www.freepascal.org/docs-html/rtl/sysutils/format.html'. - - -File: gettext.info, Node: ycp-format, Next: tcl-format, Prev: object-pascal-format, Up: Translators for other Languages - -15.3.14 YCP Format Strings --------------------------- - - YCP sformat strings are described in the libycp documentation -`file:/usr/share/doc/packages/libycp/YCP-builtins.html'. In summary, a -directive starts with `%' and is followed by `%' or a nonzero digit -(`1' to `9'). - - -File: gettext.info, Node: tcl-format, Next: perl-format, Prev: ycp-format, Up: Translators for other Languages - -15.3.15 Tcl Format Strings --------------------------- - - Tcl format strings are described in the `format.n' manual page, -`http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm'. - - -File: gettext.info, Node: perl-format, Next: php-format, Prev: tcl-format, Up: Translators for other Languages - -15.3.16 Perl Format Strings ---------------------------- - - There are two kinds format strings in Perl: those acceptable to the -Perl built-in function `printf', labelled as `perl-format', and those -acceptable to the `libintl-perl' function `__x', labelled as -`perl-brace-format'. - - Perl `printf' format strings are described in the `sprintf' section -of `man perlfunc'. - - Perl brace format strings are described in the -`Locale::TextDomain(3pm)' manual page of the CPAN package libintl-perl. -In brief, Perl format uses placeholders put between braces (`{' and -`}'). The placeholder must have the syntax of simple identifiers. - - -File: gettext.info, Node: php-format, Next: gcc-internal-format, Prev: perl-format, Up: Translators for other Languages - -15.3.17 PHP Format Strings --------------------------- - - PHP format strings are described in the documentation of the PHP -function `sprintf', in `phpdoc/manual/function.sprintf.html' or -`http://www.php.net/manual/en/function.sprintf.php'. - - -File: gettext.info, Node: gcc-internal-format, Next: gfc-internal-format, Prev: php-format, Up: Translators for other Languages - -15.3.18 GCC internal Format Strings ------------------------------------ - - These format strings are used inside the GCC sources. In such a -format string, a directive starts with `%', is optionally followed by a -size specifier `l', an optional flag `+', another optional flag `#', -and is finished by a specifier: `%' denotes a literal percent sign, `c' -denotes a character, `s' denotes a string, `i' and `d' denote an -integer, `o', `u', `x' denote an unsigned integer, `.*s' denotes a -string preceded by a width specification, `H' denotes a `location_t *' -pointer, `D' denotes a general declaration, `F' denotes a function -declaration, `T' denotes a type, `A' denotes a function argument, `C' -denotes a tree code, `E' denotes an expression, `L' denotes a -programming language, `O' denotes a binary operator, `P' denotes a -function parameter, `Q' denotes an assignment operator, `V' denotes a -const/volatile qualifier. - - -File: gettext.info, Node: gfc-internal-format, Next: qt-format, Prev: gcc-internal-format, Up: Translators for other Languages - -15.3.19 GFC internal Format Strings ------------------------------------ - - These format strings are used inside the GNU Fortran Compiler -sources, that is, the Fortran frontend in the GCC sources. In such a -format string, a directive starts with `%' and is finished by a -specifier: `%' denotes a literal percent sign, `C' denotes the current -source location, `L' denotes a source location, `c' denotes a -character, `s' denotes a string, `i' and `d' denote an integer, `u' -denotes an unsigned integer. `i', `d', and `u' may be preceded by a -size specifier `l'. - - -File: gettext.info, Node: qt-format, Next: qt-plural-format, Prev: gfc-internal-format, Up: Translators for other Languages - -15.3.20 Qt Format Strings -------------------------- - - Qt format strings are described in the documentation of the QString -class `file:/usr/lib/qt-4.3.0/doc/html/qstring.html'. In summary, a -directive consists of a `%' followed by a digit. The same directive -cannot occur more than once in a format string. - - -File: gettext.info, Node: qt-plural-format, Next: kde-format, Prev: qt-format, Up: Translators for other Languages - -15.3.21 Qt Format Strings -------------------------- - - Qt format strings are described in the documentation of the -QObject::tr method `file:/usr/lib/qt-4.3.0/doc/html/qobject.html'. In -summary, the only allowed directive is `%n'. - - -File: gettext.info, Node: kde-format, Next: boost-format, Prev: qt-plural-format, Up: Translators for other Languages - -15.3.22 KDE Format Strings --------------------------- - - KDE 4 format strings are defined as follows: A directive consists of -a `%' followed by a non-zero decimal number. If a `%n' occurs in a -format strings, all of `%1', ..., `%(n-1)' must occur as well, except -possibly one of them. - - -File: gettext.info, Node: boost-format, Prev: kde-format, Up: Translators for other Languages - -15.3.23 Boost Format Strings ----------------------------- - - Boost format strings are described in the documentation of the -`boost::format' class, at -`http://www.boost.org/libs/format/doc/format.html'. In summary, a -directive has either the same syntax as in a C format string, such as -`%1$+5d', or may be surrounded by vertical bars, such as `%|1$+5d|' or -`%|1$+5|', or consists of just an argument number between percent -signs, such as `%1%'. - - -File: gettext.info, Node: Maintainers for other Languages, Next: List of Programming Languages, Prev: Translators for other Languages, Up: Programming Languages - -15.4 The Maintainer's View -========================== - - For the maintainer, the general procedure differs from the C language -case in two ways. - - * For those languages that don't use GNU gettext, the `intl/' - directory is not needed and can be omitted. This means that the - maintainer calls the `gettextize' program without the `--intl' - option, and that he invokes the `AM_GNU_GETTEXT' autoconf macro via - `AM_GNU_GETTEXT([external])'. - - * If only a single programming language is used, the - `XGETTEXT_OPTIONS' variable in `po/Makevars' (*note po/Makevars::) - should be adjusted to match the `xgettext' options for that - particular programming language. If the package uses more than - one programming language with `gettext' support, it becomes - necessary to change the POT file construction rule in - `po/Makefile.in.in'. It is recommended to make one `xgettext' - invocation per programming language, each with the options - appropriate for that language, and to combine the resulting files - using `msgcat'. - - -File: gettext.info, Node: List of Programming Languages, Next: List of Data Formats, Prev: Maintainers for other Languages, Up: Programming Languages - -15.5 Individual Programming Languages -===================================== - -* Menu: - -* C:: C, C++, Objective C -* sh:: sh - Shell Script -* bash:: bash - Bourne-Again Shell Script -* Python:: Python -* Common Lisp:: GNU clisp - Common Lisp -* clisp C:: GNU clisp C sources -* Emacs Lisp:: Emacs Lisp -* librep:: librep -* Scheme:: GNU guile - Scheme -* Smalltalk:: GNU Smalltalk -* Java:: Java -* C#:: C# -* gawk:: GNU awk -* Pascal:: Pascal - Free Pascal Compiler -* wxWidgets:: wxWidgets library -* YCP:: YCP - YaST2 scripting language -* Tcl:: Tcl - Tk's scripting language -* Perl:: Perl -* PHP:: PHP Hypertext Preprocessor -* Pike:: Pike -* GCC-source:: GNU Compiler Collection sources - - -File: gettext.info, Node: C, Next: sh, Prev: List of Programming Languages, Up: List of Programming Languages - -15.5.1 C, C++, Objective C --------------------------- - -RPMs - gcc, gpp, gobjc, glibc, gettext - -File extension - For C: `c', `h'. - For C++: `C', `c++', `cc', `cxx', `cpp', `hpp'. - For Objective C: `m'. - -String syntax - `"abc"' - -gettext shorthand - `_("abc")' - -gettext/ngettext functions - `gettext', `dgettext', `dcgettext', `ngettext', `dngettext', - `dcngettext' - -textdomain - `textdomain' function - -bindtextdomain - `bindtextdomain' function - -setlocale - Programmer must call `setlocale (LC_ALL, "")' - -Prerequisite - `#include <libintl.h>' - `#include <locale.h>' - `#define _(string) gettext (string)' - -Use or emulate GNU gettext - Use - -Extractor - `xgettext -k_' - -Formatting with positions - `fprintf "%2$d %1$d"' - In C++: `autosprintf "%2$d %1$d"' (*note Introduction: - (autosprintf)Top.) - -Portability - autoconf (gettext.m4) and #if ENABLE_NLS - -po-mode marking - yes - - The following examples are available in the `examples' directory: -`hello-c', `hello-c-gnome', `hello-c++', `hello-c++-qt', -`hello-c++-kde', `hello-c++-gnome', `hello-c++-wxwidgets', -`hello-objc', `hello-objc-gnustep', `hello-objc-gnome'. - - -File: gettext.info, Node: sh, Next: bash, Prev: C, Up: List of Programming Languages - -15.5.2 sh - Shell Script ------------------------- - -RPMs - bash, gettext - -File extension - `sh' - -String syntax - `"abc"', `'abc'', `abc' - -gettext shorthand - `"`gettext \"abc\"`"' - -gettext/ngettext functions - `gettext', `ngettext' programs - `eval_gettext', `eval_ngettext' shell functions - -textdomain - environment variable `TEXTDOMAIN' - -bindtextdomain - environment variable `TEXTDOMAINDIR' - -setlocale - automatic - -Prerequisite - `. gettext.sh' - -Use or emulate GNU gettext - use - -Extractor - `xgettext' - -Formatting with positions - -- - -Portability - fully portable - -po-mode marking - -- - - An example is available in the `examples' directory: `hello-sh'. - -* Menu: - -* Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization -* gettext.sh:: Contents of `gettext.sh' -* gettext Invocation:: Invoking the `gettext' program -* ngettext Invocation:: Invoking the `ngettext' program -* envsubst Invocation:: Invoking the `envsubst' program -* eval_gettext Invocation:: Invoking the `eval_gettext' function -* eval_ngettext Invocation:: Invoking the `eval_ngettext' function - - -File: gettext.info, Node: Preparing Shell Scripts, Next: gettext.sh, Prev: sh, Up: sh - -15.5.2.1 Preparing Shell Scripts for Internationalization -......................................................... - - Preparing a shell script for internationalization is conceptually -similar to the steps described in *note Sources::. The concrete steps -for shell scripts are as follows. - - 1. Insert the line - - . gettext.sh - - near the top of the script. `gettext.sh' is a shell function - library that provides the functions `eval_gettext' (see *note - eval_gettext Invocation::) and `eval_ngettext' (see *note - eval_ngettext Invocation::). You have to ensure that `gettext.sh' - can be found in the `PATH'. - - 2. Set and export the `TEXTDOMAIN' and `TEXTDOMAINDIR' environment - variables. Usually `TEXTDOMAIN' is the package or program name, - and `TEXTDOMAINDIR' is the absolute pathname corresponding to - `$prefix/share/locale', where `$prefix' is the installation - location. - - TEXTDOMAIN=@PACKAGE@ - export TEXTDOMAIN - TEXTDOMAINDIR=@LOCALEDIR@ - export TEXTDOMAINDIR - - 3. Prepare the strings for translation, as described in *note - Preparing Strings::. - - 4. Simplify translatable strings so that they don't contain command - substitution (`"`...`"' or `"$(...)"'), variable access with - defaulting (like `${VARIABLE-DEFAULT}'), access to positional - arguments (like `$0', `$1', ...) or highly volatile shell - variables (like `$?'). This can always be done through simple - local code restructuring. For example, - - echo "Usage: $0 [OPTION] FILE..." - - becomes - - program_name=$0 - echo "Usage: $program_name [OPTION] FILE..." - - Similarly, - - echo "Remaining files: `ls | wc -l`" - - becomes - - filecount="`ls | wc -l`" - echo "Remaining files: $filecount" - - 5. For each translatable string, change the output command `echo' or - `$echo' to `gettext' (if the string contains no references to - shell variables) or to `eval_gettext' (if it refers to shell - variables), followed by a no-argument `echo' command (to account - for the terminating newline). Similarly, for cases with plural - handling, replace a conditional `echo' command with an invocation - of `ngettext' or `eval_ngettext', followed by a no-argument `echo' - command. - - When doing this, you also need to add an extra backslash before - the dollar sign in references to shell variables, so that the - `eval_gettext' function receives the translatable string before - the variable values are substituted into it. For example, - - echo "Remaining files: $filecount" - - becomes - - eval_gettext "Remaining files: \$filecount"; echo - - If the output command is not `echo', you can make it use `echo' - nevertheless, through the use of backquotes. However, note that - inside backquotes, backslashes must be doubled to be effective - (because the backquoting eats one level of backslashes). For - example, assuming that `error' is a shell function that signals an - error, - - error "file not found: $filename" - - is first transformed into - - error "`echo \"file not found: \$filename\"`" - - which then becomes - - error "`eval_gettext \"file not found: \\\$filename\"`" - - -File: gettext.info, Node: gettext.sh, Next: gettext Invocation, Prev: Preparing Shell Scripts, Up: sh - -15.5.2.2 Contents of `gettext.sh' -................................. - - `gettext.sh', contained in the run-time package of GNU gettext, -provides the following: - - * $echo The variable `echo' is set to a command that outputs its - first argument and a newline, without interpreting backslashes in - the argument string. - - * eval_gettext See *note eval_gettext Invocation::. - - * eval_ngettext See *note eval_ngettext Invocation::. - - -File: gettext.info, Node: gettext Invocation, Next: ngettext Invocation, Prev: gettext.sh, Up: sh - -15.5.2.3 Invoking the `gettext' program -....................................... - - gettext [OPTION] [[TEXTDOMAIN] MSGID] - gettext [OPTION] -s [MSGID]... - - The `gettext' program displays the native language translation of a -textual message. - -*Arguments* - -`-d TEXTDOMAIN' -`--domain=TEXTDOMAIN' - Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN - corresponds to a package, a program, or a module of a program. - -`-e' - Enable expansion of some escape sequences. This option is for - compatibility with the `echo' program or shell built-in. The - escape sequences `\a', `\b', `\c', `\f', `\n', `\r', `\t', `\v', - `\\', and `\' followed by one to three octal digits, are - interpreted like the System V `echo' program did. - -`-E' - This option is only for compatibility with the `echo' program or - shell built-in. It has no effect. - -`-h' -`--help' - Display this help and exit. - -`-n' - Suppress trailing newline. By default, `gettext' adds a newline to - the output. - -`-V' -`--version' - Output version information and exit. - -`[TEXTDOMAIN] MSGID' - Retrieve translated message corresponding to MSGID from TEXTDOMAIN. - - - If the TEXTDOMAIN parameter is not given, the domain is determined -from the environment variable `TEXTDOMAIN'. If the message catalog is -not found in the regular directory, another location can be specified -with the environment variable `TEXTDOMAINDIR'. - - When used with the `-s' option the program behaves like the `echo' -command. But it does not simply copy its arguments to stdout. Instead -those messages found in the selected catalog are translated. - - Note: `xgettext' supports only the one-argument form of the -`gettext' invocation, where no options are present and the TEXTDOMAIN -is implicit, from the environment. - - -File: gettext.info, Node: ngettext Invocation, Next: envsubst Invocation, Prev: gettext Invocation, Up: sh - -15.5.2.4 Invoking the `ngettext' program -........................................ - - ngettext [OPTION] [TEXTDOMAIN] MSGID MSGID-PLURAL COUNT - - The `ngettext' program displays the native language translation of a -textual message whose grammatical form depends on a number. - -*Arguments* - -`-d TEXTDOMAIN' -`--domain=TEXTDOMAIN' - Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN - corresponds to a package, a program, or a module of a program. - -`-e' - Enable expansion of some escape sequences. This option is for - compatibility with the `gettext' program. The escape sequences - `\a', `\b', `\c', `\f', `\n', `\r', `\t', `\v', `\\', and `\' - followed by one to three octal digits, are interpreted like the - System V `echo' program did. - -`-E' - This option is only for compatibility with the `gettext' program. - It has no effect. - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - -`TEXTDOMAIN' - Retrieve translated message from TEXTDOMAIN. - -`MSGID MSGID-PLURAL' - Translate MSGID (English singular) / MSGID-PLURAL (English plural). - -`COUNT' - Choose singular/plural form based on this value. - - - If the TEXTDOMAIN parameter is not given, the domain is determined -from the environment variable `TEXTDOMAIN'. If the message catalog is -not found in the regular directory, another location can be specified -with the environment variable `TEXTDOMAINDIR'. - - Note: `xgettext' supports only the three-arguments form of the -`ngettext' invocation, where no options are present and the TEXTDOMAIN -is implicit, from the environment. - - -File: gettext.info, Node: envsubst Invocation, Next: eval_gettext Invocation, Prev: ngettext Invocation, Up: sh - -15.5.2.5 Invoking the `envsubst' program -........................................ - - envsubst [OPTION] [SHELL-FORMAT] - - The `envsubst' program substitutes the values of environment -variables. - -*Operation mode* - -`-v' -`--variables' - Output the variables occurring in SHELL-FORMAT. - - -*Informative output* - -`-h' -`--help' - Display this help and exit. - -`-V' -`--version' - Output version information and exit. - - - In normal operation mode, standard input is copied to standard -output, with references to environment variables of the form -`$VARIABLE' or `${VARIABLE}' being replaced with the corresponding -values. If a SHELL-FORMAT is given, only those environment variables -that are referenced in SHELL-FORMAT are substituted; otherwise all -environment variables references occurring in standard input are -substituted. - - These substitutions are a subset of the substitutions that a shell -performs on unquoted and double-quoted strings. Other kinds of -substitutions done by a shell, such as `${VARIABLE-DEFAULT}' or -`$(COMMAND-LIST)' or ``COMMAND-LIST`', are not performed by the -`envsubst' program, due to security reasons. - - When `--variables' is used, standard input is ignored, and the output -consists of the environment variables that are referenced in -SHELL-FORMAT, one per line. - - -File: gettext.info, Node: eval_gettext Invocation, Next: eval_ngettext Invocation, Prev: envsubst Invocation, Up: sh - -15.5.2.6 Invoking the `eval_gettext' function -............................................. - - eval_gettext MSGID - - This function outputs the native language translation of a textual -message, performing dollar-substitution on the result. Note that only -shell variables mentioned in MSGID will be dollar-substituted in the -result. - - -File: gettext.info, Node: eval_ngettext Invocation, Prev: eval_gettext Invocation, Up: sh - -15.5.2.7 Invoking the `eval_ngettext' function -.............................................. - - eval_ngettext MSGID MSGID-PLURAL COUNT - - This function outputs the native language translation of a textual -message whose grammatical form depends on a number, performing -dollar-substitution on the result. Note that only shell variables -mentioned in MSGID or MSGID-PLURAL will be dollar-substituted in the -result. - - -File: gettext.info, Node: bash, Next: Python, Prev: sh, Up: List of Programming Languages - -15.5.3 bash - Bourne-Again Shell Script ---------------------------------------- - - GNU `bash' 2.0 or newer has a special shorthand for translating a -string and substituting variable values in it: `$"msgid"'. But the use -of this construct is *discouraged*, due to the security holes it opens -and due to its portability problems. - - The security holes of `$"..."' come from the fact that after looking -up the translation of the string, `bash' processes it like it processes -any double-quoted string: dollar and backquote processing, like `eval' -does. - - 1. In a locale whose encoding is one of BIG5, BIG5-HKSCS, GBK, - GB18030, SHIFT_JIS, JOHAB, some double-byte characters have a - second byte whose value is `0x60'. For example, the byte sequence - `\xe0\x60' is a single character in these locales. Many versions - of `bash' (all versions up to bash-2.05, and newer versions on - platforms without `mbsrtowcs()' function) don't know about - character boundaries and see a backquote character where there is - only a particular Chinese character. Thus it can start executing - part of the translation as a command list. This situation can - occur even without the translator being aware of it: if the - translator provides translations in the UTF-8 encoding, it is the - `gettext()' function which will, during its conversion from the - translator's encoding to the user's locale's encoding, produce the - dangerous `\x60' bytes. - - 2. A translator could - voluntarily or inadvertently - use backquotes - `"`...`"' or dollar-parentheses `"$(...)"' in her translations. - The enclosed strings would be executed as command lists by the - shell. - - The portability problem is that `bash' must be built with -internationalization support; this is normally not the case on systems -that don't have the `gettext()' function in libc. - - -File: gettext.info, Node: Python, Next: Common Lisp, Prev: bash, Up: List of Programming Languages - -15.5.4 Python -------------- - -RPMs - python - -File extension - `py' - -String syntax - `'abc'', `u'abc'', `r'abc'', `ur'abc'', - `"abc"', `u"abc"', `r"abc"', `ur"abc"', - `'''abc'''', `u'''abc'''', `r'''abc'''', `ur'''abc'''', - `"""abc"""', `u"""abc"""', `r"""abc"""', `ur"""abc"""' - -gettext shorthand - `_('abc')' etc. - -gettext/ngettext functions - `gettext.gettext', `gettext.dgettext', `gettext.ngettext', - `gettext.dngettext', also `ugettext', `ungettext' - -textdomain - `gettext.textdomain' function, or `gettext.install(DOMAIN)' - function - -bindtextdomain - `gettext.bindtextdomain' function, or - `gettext.install(DOMAIN,LOCALEDIR)' function - -setlocale - not used by the gettext emulation - -Prerequisite - `import gettext' - -Use or emulate GNU gettext - emulate - -Extractor - `xgettext' - -Formatting with positions - `'...%(ident)d...' % { 'ident': value }' - -Portability - fully portable - -po-mode marking - -- - - An example is available in the `examples' directory: `hello-python'. - - A note about format strings: Python supports format strings with -unnamed arguments, such as `'...%d...'', and format strings with named -arguments, such as `'...%(ident)d...''. The latter are preferable for -internationalized programs, for two reasons: - - * When a format string takes more than one argument, the translator - can provide a translation that uses the arguments in a different - order, if the format string uses named arguments. For example, - the translator can reformulate - "'%(volume)s' has only %(freespace)d bytes free." - to - "Only %(freespace)d bytes free on '%(volume)s'." - Additionally, the identifiers also provide some context to the - translator. - - * In the context of plural forms, the format string used for the - singular form does not use the numeric argument in many languages. - Even in English, one prefers to write `"one hour"' instead of `"1 - hour"'. Omitting individual arguments from format strings like - this is only possible with the named argument syntax. (With - unnamed arguments, Python - unlike C - verifies that the format - string uses all supplied arguments.) - - -File: gettext.info, Node: Common Lisp, Next: clisp C, Prev: Python, Up: List of Programming Languages - -15.5.5 GNU clisp - Common Lisp ------------------------------- - -RPMs - clisp 2.28 or newer - -File extension - `lisp' - -String syntax - `"abc"' - -gettext shorthand - `(_ "abc")', `(ENGLISH "abc")' - -gettext/ngettext functions - `i18n:gettext', `i18n:ngettext' - -textdomain - `i18n:textdomain' - -bindtextdomain - `i18n:textdomaindir' - -setlocale - automatic - -Prerequisite - -- - -Use or emulate GNU gettext - use - -Extractor - `xgettext -k_ -kENGLISH' - -Formatting with positions - `format "~1@*~D ~0@*~D"' - -Portability - On platforms without gettext, no translation. - -po-mode marking - -- - - An example is available in the `examples' directory: `hello-clisp'. - - -File: gettext.info, Node: clisp C, Next: Emacs Lisp, Prev: Common Lisp, Up: List of Programming Languages - -15.5.6 GNU clisp C sources --------------------------- - -RPMs - clisp - -File extension - `d' - -String syntax - `"abc"' - -gettext shorthand - `ENGLISH ? "abc" : ""' - `GETTEXT("abc")' - `GETTEXTL("abc")' - -gettext/ngettext functions - `clgettext', `clgettextl' - -textdomain - -- - -bindtextdomain - -- - -setlocale - automatic - -Prerequisite - `#include "lispbibl.c"' - -Use or emulate GNU gettext - use - -Extractor - `clisp-xgettext' - -Formatting with positions - `fprintf "%2$d %1$d"' - -Portability - On platforms without gettext, no translation. - -po-mode marking - -- - - -File: gettext.info, Node: Emacs Lisp, Next: librep, Prev: clisp C, Up: List of Programming Languages - -15.5.7 Emacs Lisp ------------------ - -RPMs - emacs, xemacs - -File extension - `el' - -String syntax - `"abc"' - -gettext shorthand - `(_"abc")' - -gettext/ngettext functions - `gettext', `dgettext' (xemacs only) - -textdomain - `domain' special form (xemacs only) - -bindtextdomain - `bind-text-domain' function (xemacs only) - -setlocale - automatic - -Prerequisite - -- - -Use or emulate GNU gettext - use - -Extractor - `xgettext' - -Formatting with positions - `format "%2$d %1$d"' - -Portability - Only XEmacs. Without `I18N3' defined at build time, no - translation. - -po-mode marking - -- - - -File: gettext.info, Node: librep, Next: Scheme, Prev: Emacs Lisp, Up: List of Programming Languages - -15.5.8 librep -------------- - -RPMs - librep 0.15.3 or newer - -File extension - `jl' - -String syntax - `"abc"' - -gettext shorthand - `(_"abc")' - -gettext/ngettext functions - `gettext' - -textdomain - `textdomain' function - -bindtextdomain - `bindtextdomain' function - -setlocale - -- - -Prerequisite - `(require 'rep.i18n.gettext)' - -Use or emulate GNU gettext - use - -Extractor - `xgettext' - -Formatting with positions - `format "%2$d %1$d"' - -Portability - On platforms without gettext, no translation. - -po-mode marking - -- - - An example is available in the `examples' directory: `hello-librep'. - - -File: gettext.info, Node: Scheme, Next: Smalltalk, Prev: librep, Up: List of Programming Languages - -15.5.9 GNU guile - Scheme -------------------------- - -RPMs - guile - -File extension - `scm' - -String syntax - `"abc"' - -gettext shorthand - `(_ "abc")' - -gettext/ngettext functions - `gettext', `ngettext' - -textdomain - `textdomain' - -bindtextdomain - `bindtextdomain' - -setlocale - `(catch #t (lambda () (setlocale LC_ALL "")) (lambda args #f))' - -Prerequisite - `(use-modules (ice-9 format))' - -Use or emulate GNU gettext - use - -Extractor - `xgettext -k_' - -Formatting with positions - -- - -Portability - On platforms without gettext, no translation. - -po-mode marking - -- - - An example is available in the `examples' directory: `hello-guile'. - - -File: gettext.info, Node: Smalltalk, Next: Java, Prev: Scheme, Up: List of Programming Languages - -15.5.10 GNU Smalltalk ---------------------- - -RPMs - smalltalk - -File extension - `st' - -String syntax - `'abc'' - -gettext shorthand - `NLS ? 'abc'' - -gettext/ngettext functions - `LcMessagesDomain>>#at:', `LcMessagesDomain>>#at:plural:with:' - -textdomain - `LcMessages>>#domain:localeDirectory:' (returns a - `LcMessagesDomain' object). - Example: `I18N Locale default messages domain: 'gettext' - localeDirectory: /usr/local/share/locale'' - -bindtextdomain - `LcMessages>>#domain:localeDirectory:', see above. - -setlocale - Automatic if you use `I18N Locale default'. - -Prerequisite - `PackageLoader fileInPackage: 'I18N'!' - -Use or emulate GNU gettext - emulate - -Extractor - `xgettext' - -Formatting with positions - `'%1 %2' bindWith: 'Hello' with: 'world'' - -Portability - fully portable - -po-mode marking - -- - - An example is available in the `examples' directory: -`hello-smalltalk'. - - -File: gettext.info, Node: Java, Next: C#, Prev: Smalltalk, Up: List of Programming Languages - -15.5.11 Java ------------- - -RPMs - java, java2 - -File extension - `java' - -String syntax - "abc" - -gettext shorthand - _("abc") - -gettext/ngettext functions - `GettextResource.gettext', `GettextResource.ngettext', - `GettextResource.pgettext', `GettextResource.npgettext' - -textdomain - --, use `ResourceBundle.getResource' instead - -bindtextdomain - --, use CLASSPATH instead - -setlocale - automatic - -Prerequisite - -- - -Use or emulate GNU gettext - --, uses a Java specific message catalog format - -Extractor - `xgettext -k_' - -Formatting with positions - `MessageFormat.format "{1,number} {0,number}"' - -Portability - fully portable - -po-mode marking - -- - - Before marking strings as internationalizable, uses of the string -concatenation operator need to be converted to `MessageFormat' -applications. For example, `"file "+filename+" not found"' becomes -`MessageFormat.format("file {0} not found", new Object[] { filename })'. -Only after this is done, can the strings be marked and extracted. - - GNU gettext uses the native Java internationalization mechanism, -namely `ResourceBundle's. There are two formats of `ResourceBundle's: -`.properties' files and `.class' files. The `.properties' format is a -text file which the translators can directly edit, like PO files, but -which doesn't support plural forms. Whereas the `.class' format is -compiled from `.java' source code and can support plural forms -(provided it is accessed through an appropriate API, see below). - - To convert a PO file to a `.properties' file, the `msgcat' program -can be used with the option `--properties-output'. To convert a -`.properties' file back to a PO file, the `msgcat' program can be used -with the option `--properties-input'. All the tools that manipulate PO -files can work with `.properties' files as well, if given the -`--properties-input' and/or `--properties-output' option. - - To convert a PO file to a ResourceBundle class, the `msgfmt' program -can be used with the option `--java' or `--java2'. To convert a -ResourceBundle back to a PO file, the `msgunfmt' program can be used -with the option `--java'. - - Two different programmatic APIs can be used to access -ResourceBundles. Note that both APIs work with all kinds of -ResourceBundles, whether GNU gettext generated classes, or other -`.class' or `.properties' files. - - 1. The `java.util.ResourceBundle' API. - - In particular, its `getString' function returns a string - translation. Note that a missing translation yields a - `MissingResourceException'. - - This has the advantage of being the standard API. And it does not - require any additional libraries, only the `msgcat' generated - `.properties' files or the `msgfmt' generated `.class' files. But - it cannot do plural handling, even if the resource was generated - by `msgfmt' from a PO file with plural handling. - - 2. The `gnu.gettext.GettextResource' API. - - Reference documentation in Javadoc 1.1 style format is in the - javadoc2 directory (javadoc2/index.html). - - Its `gettext' function returns a string translation. Note that - when a translation is missing, the MSGID argument is returned - unchanged. - - This has the advantage of having the `ngettext' function for plural - handling and the `pgettext' and `npgettext' for strings constraint - to a particular context. - - To use this API, one needs the `libintl.jar' file which is part of - the GNU gettext package and distributed under the LGPL. - - Four examples, using the second API, are available in the `examples' -directory: `hello-java', `hello-java-awt', `hello-java-swing', -`hello-java-qtjambi'. - - Now, to make use of the API and define a shorthand for `getString', -there are three idioms that you can choose from: - - * (This one assumes Java 1.5 or newer.) In a unique class of your - project, say `Util', define a static variable holding the - `ResourceBundle' instance and the shorthand: - - private static ResourceBundle myResources = - ResourceBundle.getBundle("domain-name"); - public static String _(String s) { - return myResources.getString(s); - } - - All classes containing internationalized strings then contain - - import static Util._; - - and the shorthand is used like this: - - System.out.println(_("Operation completed.")); - - * In a unique class of your project, say `Util', define a static - variable holding the `ResourceBundle' instance: - - public static ResourceBundle myResources = - ResourceBundle.getBundle("domain-name"); - - All classes containing internationalized strings then contain - - private static ResourceBundle res = Util.myResources; - private static String _(String s) { return res.getString(s); } - - and the shorthand is used like this: - - System.out.println(_("Operation completed.")); - - * You add a class with a very short name, say `S', containing just - the definition of the resource bundle and of the shorthand: - - public class S { - public static ResourceBundle myResources = - ResourceBundle.getBundle("domain-name"); - public static String _(String s) { - return myResources.getString(s); - } - } - - and the shorthand is used like this: - - System.out.println(S._("Operation completed.")); - - Which of the three idioms you choose, will depend on whether your -project requires portability to Java versions prior to Java 1.5 and, if -so, whether copying two lines of codes into every class is more -acceptable in your project than a class with a single-letter name. - - -File: gettext.info, Node: C#, Next: gawk, Prev: Java, Up: List of Programming Languages - -15.5.12 C# ----------- - -RPMs - pnet, pnetlib 0.6.2 or newer, or mono 0.29 or newer - -File extension - `cs' - -String syntax - `"abc"', `@"abc"' - -gettext shorthand - _("abc") - -gettext/ngettext functions - `GettextResourceManager.GetString', - `GettextResourceManager.GetPluralString' - `GettextResourceManager.GetParticularString' - `GettextResourceManager.GetParticularPluralString' - -textdomain - `new GettextResourceManager(domain)' - -bindtextdomain - --, compiled message catalogs are located in subdirectories of the - directory containing the executable - -setlocale - automatic - -Prerequisite - -- - -Use or emulate GNU gettext - --, uses a C# specific message catalog format - -Extractor - `xgettext -k_' - -Formatting with positions - `String.Format "{1} {0}"' - -Portability - fully portable - -po-mode marking - -- - - Before marking strings as internationalizable, uses of the string -concatenation operator need to be converted to `String.Format' -invocations. For example, `"file "+filename+" not found"' becomes -`String.Format("file {0} not found", filename)'. Only after this is -done, can the strings be marked and extracted. - - GNU gettext uses the native C#/.NET internationalization mechanism, -namely the classes `ResourceManager' and `ResourceSet'. Applications -use the `ResourceManager' methods to retrieve the native language -translation of strings. An instance of `ResourceSet' is the in-memory -representation of a message catalog file. The `ResourceManager' loads -and accesses `ResourceSet' instances as needed to look up the -translations. - - There are two formats of `ResourceSet's that can be directly loaded -by the C# runtime: `.resources' files and `.dll' files. - - * The `.resources' format is a binary file usually generated through - the `resgen' or `monoresgen' utility, but which doesn't support - plural forms. `.resources' files can also be embedded in .NET - `.exe' files. This only affects whether a file system access is - performed to load the message catalog; it doesn't affect the - contents of the message catalog. - - * On the other hand, the `.dll' format is a binary file that is - compiled from `.cs' source code and can support plural forms - (provided it is accessed through the GNU gettext API, see below). - - Note that these .NET `.dll' and `.exe' files are not tied to a -particular platform; their file format and GNU gettext for C# can be -used on any platform. - - To convert a PO file to a `.resources' file, the `msgfmt' program -can be used with the option `--csharp-resources'. To convert a -`.resources' file back to a PO file, the `msgunfmt' program can be used -with the option `--csharp-resources'. You can also, in some cases, use -the `resgen' program (from the `pnet' package) or the `monoresgen' -program (from the `mono'/`mcs' package). These programs can also -convert a `.resources' file back to a PO file. But beware: as of this -writing (January 2004), the `monoresgen' converter is quite buggy and -the `resgen' converter ignores the encoding of the PO files. - - To convert a PO file to a `.dll' file, the `msgfmt' program can be -used with the option `--csharp'. The result will be a `.dll' file -containing a subclass of `GettextResourceSet', which itself is a -subclass of `ResourceSet'. To convert a `.dll' file containing a -`GettextResourceSet' subclass back to a PO file, the `msgunfmt' program -can be used with the option `--csharp'. - - The advantages of the `.dll' format over the `.resources' format are: - - 1. Freedom to localize: Users can add their own translations to an - application after it has been built and distributed. Whereas when - the programmer uses a `ResourceManager' constructor provided by - the system, the set of `.resources' files for an application must - be specified when the application is built and cannot be extended - afterwards. - - 2. Plural handling: A message catalog in `.dll' format supports the - plural handling function `GetPluralString'. Whereas `.resources' - files can only contain data and only support lookups that depend - on a single string. - - 3. Context handling: A message catalog in `.dll' format supports the - query-with-context functions `GetParticularString' and - `GetParticularPluralString'. Whereas `.resources' files can only - contain data and only support lookups that depend on a single - string. - - 4. The `GettextResourceManager' that loads the message catalogs in - `.dll' format also provides for inheritance on a per-message basis. - For example, in Austrian (`de_AT') locale, translations from the - German (`de') message catalog will be used for messages not found - in the Austrian message catalog. This has the consequence that - the Austrian translators need only translate those few messages - for which the translation into Austrian differs from the German - one. Whereas when working with `.resources' files, each message - catalog must provide the translations of all messages by itself. - - 5. The `GettextResourceManager' that loads the message catalogs in - `.dll' format also provides for a fallback: The English MSGID is - returned when no translation can be found. Whereas when working - with `.resources' files, a language-neutral `.resources' file must - explicitly be provided as a fallback. - - On the side of the programmatic APIs, the programmer can use either -the standard `ResourceManager' API and the GNU `GettextResourceManager' -API. The latter is an extension of the former, because -`GettextResourceManager' is a subclass of `ResourceManager'. - - 1. The `System.Resources.ResourceManager' API. - - This API works with resources in `.resources' format. - - The creation of the `ResourceManager' is done through - new ResourceManager(domainname, Assembly.GetExecutingAssembly()) - The `GetString' function returns a string's translation. Note - that this function returns null when a translation is missing - (i.e. not even found in the fallback resource file). - - 2. The `GNU.Gettext.GettextResourceManager' API. - - This API works with resources in `.dll' format. - - Reference documentation is in the csharpdoc directory - (csharpdoc/index.html). - - The creation of the `ResourceManager' is done through - new GettextResourceManager(domainname) - - The `GetString' function returns a string's translation. Note - that when a translation is missing, the MSGID argument is returned - unchanged. - - The `GetPluralString' function returns a string translation with - plural handling, like the `ngettext' function in C. - - The `GetParticularString' function returns a string's translation, - specific to a particular context, like the `pgettext' function in - C. Note that when a translation is missing, the MSGID argument is - returned unchanged. - - The `GetParticularPluralString' function returns a string - translation, specific to a particular context, with plural - handling, like the `npgettext' function in C. - - To use this API, one needs the `GNU.Gettext.dll' file which is - part of the GNU gettext package and distributed under the LGPL. - - You can also mix both approaches: use the -`GNU.Gettext.GettextResourceManager' constructor, but otherwise use -only the `ResourceManager' type and only the `GetString' method. This -is appropriate when you want to profit from the tools for PO files, but -don't want to change an existing source code that uses -`ResourceManager' and don't (yet) need the `GetPluralString' method. - - Two examples, using the second API, are available in the `examples' -directory: `hello-csharp', `hello-csharp-forms'. - - Now, to make use of the API and define a shorthand for `GetString', -there are two idioms that you can choose from: - - * In a unique class of your project, say `Util', define a static - variable holding the `ResourceManager' instance: - - public static GettextResourceManager MyResourceManager = - new GettextResourceManager("domain-name"); - - All classes containing internationalized strings then contain - - private static GettextResourceManager Res = Util.MyResourceManager; - private static String _(String s) { return Res.GetString(s); } - - and the shorthand is used like this: - - Console.WriteLine(_("Operation completed.")); - - * You add a class with a very short name, say `S', containing just - the definition of the resource manager and of the shorthand: - - public class S { - public static GettextResourceManager MyResourceManager = - new GettextResourceManager("domain-name"); - public static String _(String s) { - return MyResourceManager.GetString(s); - } - } - - and the shorthand is used like this: - - Console.WriteLine(S._("Operation completed.")); - - Which of the two idioms you choose, will depend on whether copying -two lines of codes into every class is more acceptable in your project -than a class with a single-letter name. - - -File: gettext.info, Node: gawk, Next: Pascal, Prev: C#, Up: List of Programming Languages - -15.5.13 GNU awk ---------------- - -RPMs - gawk 3.1 or newer - -File extension - `awk' - -String syntax - `"abc"' - -gettext shorthand - `_"abc"' - -gettext/ngettext functions - `dcgettext', missing `dcngettext' in gawk-3.1.0 - -textdomain - `TEXTDOMAIN' variable - -bindtextdomain - `bindtextdomain' function - -setlocale - automatic, but missing `setlocale (LC_MESSAGES, "")' in gawk-3.1.0 - -Prerequisite - -- - -Use or emulate GNU gettext - use - -Extractor - `xgettext' - -Formatting with positions - `printf "%2$d %1$d"' (GNU awk only) - -Portability - On platforms without gettext, no translation. On non-GNU awks, - you must define `dcgettext', `dcngettext' and `bindtextdomain' - yourself. - -po-mode marking - -- - - An example is available in the `examples' directory: `hello-gawk'. - - -File: gettext.info, Node: Pascal, Next: wxWidgets, Prev: gawk, Up: List of Programming Languages - -15.5.14 Pascal - Free Pascal Compiler -------------------------------------- - -RPMs - fpk - -File extension - `pp', `pas' - -String syntax - `'abc'' - -gettext shorthand - automatic - -gettext/ngettext functions - --, use `ResourceString' data type instead - -textdomain - --, use `TranslateResourceStrings' function instead - -bindtextdomain - --, use `TranslateResourceStrings' function instead - -setlocale - automatic, but uses only LANG, not LC_MESSAGES or LC_ALL - -Prerequisite - `{$mode delphi}' or `{$mode objfpc}' - `uses gettext;' - -Use or emulate GNU gettext - emulate partially - -Extractor - `ppc386' followed by `xgettext' or `rstconv' - -Formatting with positions - `uses sysutils;' - `format "%1:d %0:d"' - -Portability - ? - -po-mode marking - -- - - The Pascal compiler has special support for the `ResourceString' data -type. It generates a `.rst' file. This is then converted to a `.pot' -file by use of `xgettext' or `rstconv'. At runtime, a `.mo' file -corresponding to translations of this `.pot' file can be loaded using -the `TranslateResourceStrings' function in the `gettext' unit. - - An example is available in the `examples' directory: `hello-pascal'. - - -File: gettext.info, Node: wxWidgets, Next: YCP, Prev: Pascal, Up: List of Programming Languages - -15.5.15 wxWidgets library -------------------------- - -RPMs - wxGTK, gettext - -File extension - `cpp' - -String syntax - `"abc"' - -gettext shorthand - `_("abc")' - -gettext/ngettext functions - `wxLocale::GetString', `wxGetTranslation' - -textdomain - `wxLocale::AddCatalog' - -bindtextdomain - `wxLocale::AddCatalogLookupPathPrefix' - -setlocale - `wxLocale::Init', `wxSetLocale' - -Prerequisite - `#include <wx/intl.h>' - -Use or emulate GNU gettext - emulate, see `include/wx/intl.h' and `src/common/intl.cpp' - -Extractor - `xgettext' - -Formatting with positions - wxString::Format supports positions if and only if the system has - `wprintf()', `vswprintf()' functions and they support positions - according to POSIX. - -Portability - fully portable - -po-mode marking - yes - - -File: gettext.info, Node: YCP, Next: Tcl, Prev: wxWidgets, Up: List of Programming Languages - -15.5.16 YCP - YaST2 scripting language --------------------------------------- - -RPMs - libycp, libycp-devel, yast2-core, yast2-core-devel - -File extension - `ycp' - -String syntax - `"abc"' - -gettext shorthand - `_("abc")' - -gettext/ngettext functions - `_()' with 1 or 3 arguments - -textdomain - `textdomain' statement - -bindtextdomain - -- - -setlocale - -- - -Prerequisite - -- - -Use or emulate GNU gettext - use - -Extractor - `xgettext' - -Formatting with positions - `sformat "%2 %1"' - -Portability - fully portable - -po-mode marking - -- - - An example is available in the `examples' directory: `hello-ycp'. - - -File: gettext.info, Node: Tcl, Next: Perl, Prev: YCP, Up: List of Programming Languages - -15.5.17 Tcl - Tk's scripting language -------------------------------------- - -RPMs - tcl - -File extension - `tcl' - -String syntax - `"abc"' - -gettext shorthand - `[_ "abc"]' - -gettext/ngettext functions - `::msgcat::mc' - -textdomain - -- - -bindtextdomain - --, use `::msgcat::mcload' instead - -setlocale - automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL - -Prerequisite - `package require msgcat' - `proc _ {s} {return [::msgcat::mc $s]}' - -Use or emulate GNU gettext - --, uses a Tcl specific message catalog format - -Extractor - `xgettext -k_' - -Formatting with positions - `format "%2\$d %1\$d"' - -Portability - fully portable - -po-mode marking - -- - - Two examples are available in the `examples' directory: `hello-tcl', -`hello-tcl-tk'. - - Before marking strings as internationalizable, substitutions of -variables into the string need to be converted to `format' -applications. For example, `"file $filename not found"' becomes -`[format "file %s not found" $filename]'. Only after this is done, can -the strings be marked and extracted. After marking, this example -becomes `[format [_ "file %s not found"] $filename]' or `[msgcat::mc -"file %s not found" $filename]'. Note that the `msgcat::mc' function -implicitly calls `format' when more than one argument is given. - - -File: gettext.info, Node: Perl, Next: PHP, Prev: Tcl, Up: List of Programming Languages - -15.5.18 Perl ------------- - -RPMs - perl - -File extension - `pl', `PL', `pm', `cgi' - -String syntax - * `"abc"' - - * `'abc'' - - * `qq (abc)' - - * `q (abc)' - - * `qr /abc/' - - * `qx (/bin/date)' - - * `/pattern match/' - - * `?pattern match?' - - * `s/substitution/operators/' - - * `$tied_hash{"message"}' - - * `$tied_hash_reference->{"message"}' - - * etc., issue the command `man perlsyn' for details - - -gettext shorthand - `__' (double underscore) - -gettext/ngettext functions - `gettext', `dgettext', `dcgettext', `ngettext', `dngettext', - `dcngettext' - -textdomain - `textdomain' function - -bindtextdomain - `bindtextdomain' function - -bind_textdomain_codeset - `bind_textdomain_codeset' function - -setlocale - Use `setlocale (LC_ALL, "");' - -Prerequisite - `use POSIX;' - `use Locale::TextDomain;' (included in the package libintl-perl - which is available on the Comprehensive Perl Archive Network CPAN, - http://www.cpan.org/). - -Use or emulate GNU gettext - platform dependent: gettext_pp emulates, gettext_xs uses GNU - gettext - -Extractor - `xgettext -k__ -k\$__ -k%__ -k__x -k__n:1,2 -k__nx:1,2 -k__xn:1,2 - -kN__ -k' - -Formatting with positions - Both kinds of format strings support formatting with positions. - `printf "%2\$d %1\$d", ...' (requires Perl 5.8.0 or newer) - `__expand("[new] replaces [old]", old => $oldvalue, new => - $newvalue)' - -Portability - The `libintl-perl' package is platform independent but is not part - of the Perl core. The programmer is responsible for providing a - dummy implementation of the required functions if the package is - not installed on the target system. - -po-mode marking - -- - -Documentation - Included in `libintl-perl', available on CPAN - (http://www.cpan.org/). - - - An example is available in the `examples' directory: `hello-perl'. - - The `xgettext' parser backend for Perl differs significantly from -the parser backends for other programming languages, just as Perl -itself differs significantly from other programming languages. The -Perl parser backend offers many more string marking facilities than the -other backends but it also has some Perl specific limitations, the -worst probably being its imperfectness. - -* Menu: - -* General Problems:: General Problems Parsing Perl Code -* Default Keywords:: Which Keywords Will xgettext Look For? -* Special Keywords:: How to Extract Hash Keys -* Quote-like Expressions:: What are Strings And Quote-like Expressions? -* Interpolation I:: Invalid String Interpolation -* Interpolation II:: Valid String Interpolation -* Parentheses:: When To Use Parentheses -* Long Lines:: How To Grok with Long Lines -* Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work - - -File: gettext.info, Node: General Problems, Next: Default Keywords, Up: Perl - -15.5.18.1 General Problems Parsing Perl Code -............................................ - - It is often heard that only Perl can parse Perl. This is not true. -Perl cannot be _parsed_ at all, it can only be _executed_. Perl has -various built-in ambiguities that can only be resolved at runtime. - - The following example may illustrate one common problem: - - print gettext "Hello World!"; - - Although this example looks like a bullet-proof case of a function -invocation, it is not: - - open gettext, ">testfile" or die; - print gettext "Hello world!" - - In this context, the string `gettext' looks more like a file handle. -But not necessarily: - - use Locale::Messages qw (:libintl_h); - open gettext ">testfile" or die; - print gettext "Hello world!"; - - Now, the file is probably syntactically incorrect, provided that the -module `Locale::Messages' found first in the Perl include path exports a -function `gettext'. But what if the module `Locale::Messages' really -looks like this? - - use vars qw (*gettext); - - 1; - - In this case, the string `gettext' will be interpreted as a file -handle again, and the above example will create a file `testfile' and -write the string "Hello world!" into it. Even advanced control flow -analysis will not really help: - - if (0.5 < rand) { - eval "use Sane"; - } else { - eval "use InSane"; - } - print gettext "Hello world!"; - - If the module `Sane' exports a function `gettext' that does what we -expect, and the module `InSane' opens a file for writing and associates -the _handle_ `gettext' with this output stream, we are clueless again -about what will happen at runtime. It is completely unpredictable. -The truth is that Perl has so many ways to fill its symbol table at -runtime that it is impossible to interpret a particular piece of code -without executing it. - - Of course, `xgettext' will not execute your Perl sources while -scanning for translatable strings, but rather use heuristics in order -to guess what you meant. - - Another problem is the ambiguity of the slash and the question mark. -Their interpretation depends on the context: - - # A pattern match. - print "OK\n" if /foobar/; - - # A division. - print 1 / 2; - - # Another pattern match. - print "OK\n" if ?foobar?; - - # Conditional. - print $x ? "foo" : "bar"; - - The slash may either act as the division operator or introduce a -pattern match, whereas the question mark may act as the ternary -conditional operator or as a pattern match, too. Other programming -languages like `awk' present similar problems, but the consequences of a -misinterpretation are particularly nasty with Perl sources. In `awk' -for instance, a statement can never exceed one line and the parser can -recover from a parsing error at the next newline and interpret the rest -of the input stream correctly. Perl is different, as a pattern match -is terminated by the next appearance of the delimiter (the slash or the -question mark) in the input stream, regardless of the semantic context. -If a slash is really a division sign but mis-interpreted as a pattern -match, the rest of the input file is most probably parsed incorrectly. - - There are certain cases, where the ambiguity cannot be resolved at -all: - - $x = wantarray ? 1 : 0; - - The Perl built-in function `wantarray' does not accept any arguments. -The Perl parser therefore knows that the question mark does not start a -regular expression but is the ternary conditional operator. - - sub wantarrays {} - $x = wantarrays ? 1 : 0; - - Now the situation is different. The function `wantarrays' takes a -variable number of arguments (like any non-prototyped Perl function). -The question mark is now the delimiter of a pattern match, and hence -the piece of code does not compile. - - sub wantarrays() {} - $x = wantarrays ? 1 : 0; - - Now the function is prototyped, Perl knows that it does not accept -any arguments, and the question mark is therefore interpreted as the -ternaray operator again. But that unfortunately outsmarts `xgettext'. - - The Perl parser in `xgettext' cannot know whether a function has a -prototype and what that prototype would look like. It therefore makes -an educated guess. If a function is known to be a Perl built-in and -this function does not accept any arguments, a following question mark -or slash is treated as an operator, otherwise as the delimiter of a -following regular expression. The Perl built-ins that do not accept -arguments are `wantarray', `fork', `time', `times', `getlogin', -`getppid', `getpwent', `getgrent', `gethostent', `getnetent', -`getprotoent', `getservent', `setpwent', `setgrent', `endpwent', -`endgrent', `endhostent', `endnetent', `endprotoent', and `endservent'. - - If you find that `xgettext' fails to extract strings from portions -of your sources, you should therefore look out for slashes and/or -question marks preceding these sections. You may have come across a -bug in `xgettext''s Perl parser (and of course you should report that -bug). In the meantime you should consider to reformulate your code in -a manner less challenging to `xgettext'. - - In particular, if the parser is too dumb to see that a function does -not accept arguments, use parentheses: - - $x = somefunc() ? 1 : 0; - $y = (somefunc) ? 1 : 0; - - In fact the Perl parser itself has similar problems and warns you -about such constructs. - - -File: gettext.info, Node: Default Keywords, Next: Special Keywords, Prev: General Problems, Up: Perl - -15.5.18.2 Which keywords will xgettext look for? -................................................ - - Unless you instruct `xgettext' otherwise by invoking it with one of -the options `--keyword' or `-k', it will recognize the following -keywords in your Perl sources: - - * `gettext' - - * `dgettext' - - * `dcgettext' - - * `ngettext:1,2' - - The first (singular) and the second (plural) argument will be - extracted. - - * `dngettext:1,2' - - The first (singular) and the second (plural) argument will be - extracted. - - * `dcngettext:1,2' - - The first (singular) and the second (plural) argument will be - extracted. - - * `gettext_noop' - - * `%gettext' - - The keys of lookups into the hash `%gettext' will be extracted. - - * `$gettext' - - The keys of lookups into the hash reference `$gettext' will be - extracted. - - - -File: gettext.info, Node: Special Keywords, Next: Quote-like Expressions, Prev: Default Keywords, Up: Perl - -15.5.18.3 How to Extract Hash Keys -.................................. - - Translating messages at runtime is normally performed by looking up -the original string in the translation database and returning the -translated version. The "natural" Perl implementation is a hash -lookup, and, of course, `xgettext' supports such practice. - - print __"Hello world!"; - print $__{"Hello world!"}; - print $__->{"Hello world!"}; - print $$__{"Hello world!"}; - - The above four lines all do the same thing. The Perl module -`Locale::TextDomain' exports by default a hash `%__' that is tied to -the function `__()'. It also exports a reference `$__' to `%__'. - - If an argument to the `xgettext' option `--keyword', resp. `-k' -starts with a percent sign, the rest of the keyword is interpreted as -the name of a hash. If it starts with a dollar sign, the rest of the -keyword is interpreted as a reference to a hash. - - Note that you can omit the quotation marks (single or double) around -the hash key (almost) whenever Perl itself allows it: - - print $gettext{Error}; - - The exact rule is: You can omit the surrounding quotes, when the hash -key is a valid C (!) identifier, i.e. when it starts with an underscore -or an ASCII letter and is followed by an arbitrary number of -underscores, ASCII letters or digits. Other Unicode characters are -_not_ allowed, regardless of the `use utf8' pragma. - - -File: gettext.info, Node: Quote-like Expressions, Next: Interpolation I, Prev: Special Keywords, Up: Perl - -15.5.18.4 What are Strings And Quote-like Expressions? -...................................................... - - Perl offers a plethora of different string constructs. Those that -can be used either as arguments to functions or inside braces for hash -lookups are generally supported by `xgettext'. - - * *double-quoted strings* - print gettext "Hello World!"; - - * *single-quoted strings* - print gettext 'Hello World!'; - - * *the operator qq* - print gettext qq |Hello World!|; - print gettext qq <E-mail: <guido\@imperia.net>>; - - The operator `qq' is fully supported. You can use arbitrary - delimiters, including the four bracketing delimiters (round, angle, - square, curly) that nest. - - * *the operator q* - print gettext q |Hello World!|; - print gettext q <E-mail: <guido@imperia.net>>; - - The operator `q' is fully supported. You can use arbitrary - delimiters, including the four bracketing delimiters (round, angle, - square, curly) that nest. - - * *the operator qx* - print gettext qx ;LANGUAGE=C /bin/date; - print gettext qx [/usr/bin/ls | grep '^[A-Z]*']; - - The operator `qx' is fully supported. You can use arbitrary - delimiters, including the four bracketing delimiters (round, angle, - square, curly) that nest. - - The example is actually a useless use of `gettext'. It will - invoke the `gettext' function on the output of the command - specified with the `qx' operator. The feature was included in - order to make the interface consistent (the parser will extract - all strings and quote-like expressions). - - * *here documents* - print gettext <<'EOF'; - program not found in $PATH - EOF - - print ngettext <<EOF, <<"EOF"; - one file deleted - EOF - several files deleted - EOF - - Here-documents are recognized. If the delimiter is enclosed in - single quotes, the string is not interpolated. If it is enclosed - in double quotes or has no quotes at all, the string is - interpolated. - - Delimiters that start with a digit are not supported! - - - -File: gettext.info, Node: Interpolation I, Next: Interpolation II, Prev: Quote-like Expressions, Up: Perl - -15.5.18.5 Invalid Uses Of String Interpolation -.............................................. - - Perl is capable of interpolating variables into strings. This offers -some nice features in localized programs but can also lead to problems. - - A common error is a construct like the following: - - print gettext "This is the program $0!\n"; - - Perl will interpolate at runtime the value of the variable `$0' into -the argument of the `gettext()' function. Hence, this argument is not -a string constant but a variable argument (`$0' is a global variable -that holds the name of the Perl script being executed). The -interpolation is performed by Perl before the string argument is passed -to `gettext()' and will therefore depend on the name of the script -which can only be determined at runtime. Consequently, it is almost -impossible that a translation can be looked up at runtime (except if, -by accident, the interpolated string is found in the message catalog). - - The `xgettext' program will therefore terminate parsing with a fatal -error if it encounters a variable inside of an extracted string. In -general, this will happen for all kinds of string interpolations that -cannot be safely performed at compile time. If you absolutely know -what you are doing, you can always circumvent this behavior: - - my $know_what_i_am_doing = "This is program $0!\n"; - print gettext $know_what_i_am_doing; - - Since the parser only recognizes strings and quote-like expressions, -but not variables or other terms, the above construct will be accepted. -You will have to find another way, however, to let your original string -make it into your message catalog. - - If invoked with the option `--extract-all', resp. `-a', variable -interpolation will be accepted. Rationale: You will generally use this -option in order to prepare your sources for internationalization. - - Please see the manual page `man perlop' for details of strings and -quote-like expressions that are subject to interpolation and those that -are not. Safe interpolations (that will not lead to a fatal error) are: - - * the escape sequences `\t' (tab, HT, TAB), `\n' (newline, NL), `\r' - (return, CR), `\f' (form feed, FF), `\b' (backspace, BS), `\a' - (alarm, bell, BEL), and `\e' (escape, ESC). - - * octal chars, like `\033' - Note that octal escapes in the range of 400-777 are translated - into a UTF-8 representation, regardless of the presence of the - `use utf8' pragma. - - * hex chars, like `\x1b' - - * wide hex chars, like `\x{263a}' - Note that this escape is translated into a UTF-8 representation, - regardless of the presence of the `use utf8' pragma. - - * control chars, like `\c[' (CTRL-[) - - * named Unicode chars, like `\N{LATIN CAPITAL LETTER C WITH CEDILLA}' - Note that this escape is translated into a UTF-8 representation, - regardless of the presence of the `use utf8' pragma. - - The following escapes are considered partially safe: - - * `\l' lowercase next char - - * `\u' uppercase next char - - * `\L' lowercase till \E - - * `\U' uppercase till \E - - * `\E' end case modification - - * `\Q' quote non-word characters till \E - - - These escapes are only considered safe if the string consists of -ASCII characters only. Translation of characters outside the range -defined by ASCII is locale-dependent and can actually only be performed -at runtime; `xgettext' doesn't do these locale-dependent translations -at extraction time. - - Except for the modifier `\Q', these translations, albeit valid, are -generally useless and only obfuscate your sources. If a translation -can be safely performed at compile time you can just as well write what -you mean. - - -File: gettext.info, Node: Interpolation II, Next: Parentheses, Prev: Interpolation I, Up: Perl - -15.5.18.6 Valid Uses Of String Interpolation -............................................ - - Perl is often used to generate sources for other programming -languages or arbitrary file formats. Web applications that output HTML -code make a prominent example for such usage. - - You will often come across situations where you want to intersperse -code written in the target (programming) language with translatable -messages, like in the following HTML example: - - print gettext <<EOF; - <h1>My Homepage</h1> - <script language="JavaScript"><!-- - for (i = 0; i < 100; ++i) { - alert ("Thank you so much for visiting my homepage!"); - } - //--></script> - EOF - - The parser will extract the entire here document, and it will appear -entirely in the resulting PO file, including the JavaScript snippet -embedded in the HTML code. If you exaggerate with constructs like the -above, you will run the risk that the translators of your package will -look out for a less challenging project. You should consider an -alternative expression here: - - print <<EOF; - <h1>$gettext{"My Homepage"}</h1> - <script language="JavaScript"><!-- - for (i = 0; i < 100; ++i) { - alert ("$gettext{'Thank you so much for visiting my homepage!'}"); - } - //--></script> - EOF - - Only the translatable portions of the code will be extracted here, -and the resulting PO file will begrudgingly improve in terms of -readability. - - You can interpolate hash lookups in all strings or quote-like -expressions that are subject to interpolation (see the manual page `man -perlop' for details). Double interpolation is invalid, however: - - # TRANSLATORS: Replace "the earth" with the name of your planet. - print gettext qq{Welcome to $gettext->{"the earth"}}; - - The `qq'-quoted string is recognized as an argument to `xgettext' in -the first place, and checked for invalid variable interpolation. The -dollar sign of hash-dereferencing will therefore terminate the parser -with an "invalid interpolation" error. - - It is valid to interpolate hash lookups in regular expressions: - - if ($var =~ /$gettext{"the earth"}/) { - print gettext "Match!\n"; - } - s/$gettext{"U. S. A."}/$gettext{"U. S. A."} $gettext{"(dial +0)"}/g; - - -File: gettext.info, Node: Parentheses, Next: Long Lines, Prev: Interpolation II, Up: Perl - -15.5.18.7 When To Use Parentheses -................................. - - In Perl, parentheses around function arguments are mostly optional. -`xgettext' will always assume that all recognized keywords (except for -hashes and hash references) are names of properly prototyped functions, -and will (hopefully) only require parentheses where Perl itself -requires them. All constructs in the following example are therefore -ok to use: - - print gettext ("Hello World!\n"); - print gettext "Hello World!\n"; - print dgettext ($package => "Hello World!\n"); - print dgettext $package, "Hello World!\n"; - - # The "fat comma" => turns the left-hand side argument into a - # single-quoted string! - print dgettext smellovision => "Hello World!\n"; - - # The following assignment only works with prototyped functions. - # Otherwise, the functions will act as "greedy" list operators and - # eat up all following arguments. - my $anonymous_hash = { - planet => gettext "earth", - cakes => ngettext "one cake", "several cakes", $n, - still => $works, - }; - # The same without fat comma: - my $other_hash = { - 'planet', gettext "earth", - 'cakes', ngettext "one cake", "several cakes", $n, - 'still', $works, - }; - - # Parentheses are only significant for the first argument. - print dngettext 'package', ("one cake", "several cakes", $n), $discarded; - - -File: gettext.info, Node: Long Lines, Next: Perl Pitfalls, Prev: Parentheses, Up: Perl - -15.5.18.8 How To Grok with Long Lines -..................................... - - The necessity of long messages can often lead to a cumbersome or -unreadable coding style. Perl has several options that may prevent you -from writing unreadable code, and `xgettext' does its best to do -likewise. This is where the dot operator (the string concatenation -operator) may come in handy: - - print gettext ("This is a very long" - . " message that is still" - . " readable, because" - . " it is split into" - . " multiple lines.\n"); - - Perl is smart enough to concatenate these constant string fragments -into one long string at compile time, and so is `xgettext'. You will -only find one long message in the resulting POT file. - - Note that the future Perl 6 will probably use the underscore (`_') -as the string concatenation operator, and the dot (`.') for -dereferencing. This new syntax is not yet supported by `xgettext'. - - If embedded newline characters are not an issue, or even desired, you -may also insert newline characters inside quoted strings wherever you -feel like it: - - print gettext ("<em>In HTML output - embedded newlines are generally no - problem, since adjacent whitespace - is always rendered into a single - space character.</em>"); - - You may also consider to use here documents: - - print gettext <<EOF; - <em>In HTML output - embedded newlines are generally no - problem, since adjacent whitespace - is always rendered into a single - space character.</em> - EOF - - Please do not forget that the line breaks are real, i.e. they -translate into newline characters that will consequently show up in the -resulting POT file. - - -File: gettext.info, Node: Perl Pitfalls, Prev: Long Lines, Up: Perl - -15.5.18.9 Bugs, Pitfalls, And Things That Do Not Work -..................................................... - - The foregoing sections should have proven that `xgettext' is quite -smart in extracting translatable strings from Perl sources. Yet, some -more or less exotic constructs that could be expected to work, actually -do not work. - - One of the more relevant limitations can be found in the -implementation of variable interpolation inside quoted strings. Only -simple hash lookups can be used there: - - print <<EOF; - $gettext{"The dot operator" - . " does not work" - . "here!"} - Likewise, you cannot @{[ gettext ("interpolate function calls") ]} - inside quoted strings or quote-like expressions. - EOF - - This is valid Perl code and will actually trigger invocations of the -`gettext' function at runtime. Yet, the Perl parser in `xgettext' will -fail to recognize the strings. A less obvious example can be found in -the interpolation of regular expressions: - - s/<!--START_OF_WEEK-->/gettext ("Sunday")/e; - - The modifier `e' will cause the substitution to be interpreted as an -evaluable statement. Consequently, at runtime the function `gettext()' -is called, but again, the parser fails to extract the string "Sunday". -Use a temporary variable as a simple workaround if you really happen to -need this feature: - - my $sunday = gettext "Sunday"; - s/<!--START_OF_WEEK-->/$sunday/; - - Hash slices would also be handy but are not recognized: - - my @weekdays = @gettext{'Sunday', 'Monday', 'Tuesday', 'Wednesday', - 'Thursday', 'Friday', 'Saturday'}; - # Or even: - @weekdays = @gettext{qw (Sunday Monday Tuesday Wednesday Thursday - Friday Saturday) }; - - This is perfectly valid usage of the tied hash `%gettext' but the -strings are not recognized and therefore will not be extracted. - - Another caveat of the current version is its rudimentary support for -non-ASCII characters in identifiers. You may encounter serious -problems if you use identifiers with characters outside the range of -'A'-'Z', 'a'-'z', '0'-'9' and the underscore '_'. - - Maybe some of these missing features will be implemented in future -versions, but since you can always make do without them at minimal -effort, these todos have very low priority. - - A nasty problem are brace format strings that already contain braces -as part of the normal text, for example the usage strings typically -encountered in programs: - - die "usage: $0 {OPTIONS} FILENAME...\n"; - - If you want to internationalize this code with Perl brace format -strings, you will run into a problem: - - die __x ("usage: {program} {OPTIONS} FILENAME...\n", program => $0); - - Whereas `{program}' is a placeholder, `{OPTIONS}' is not and should -probably be translated. Yet, there is no way to teach the Perl parser -in `xgettext' to recognize the first one, and leave the other one alone. - - There are two possible work-arounds for this problem. If you are -sure that your program will run under Perl 5.8.0 or newer (these Perl -versions handle positional parameters in `printf()') or if you are sure -that the translator will not have to reorder the arguments in her -translation - for example if you have only one brace placeholder in -your string, or if it describes a syntax, like in this one -, you can -mark the string as `no-perl-brace-format' and use `printf()': - - # xgettext: no-perl-brace-format - die sprintf ("usage: %s {OPTIONS} FILENAME...\n", $0); - - If you want to use the more portable Perl brace format, you will -have to do put placeholders in place of the literal braces: - - die __x ("usage: {program} {[}OPTIONS{]} FILENAME...\n", - program => $0, '[' => '{', ']' => '}'); - - Perl brace format strings know no escaping mechanism. No matter how -this escaping mechanism looked like, it would either give the -programmer a hard time, make translating Perl brace format strings -heavy-going, or result in a performance penalty at runtime, when the -format directives get executed. Most of the time you will happily get -along with `printf()' for this special case. - - -File: gettext.info, Node: PHP, Next: Pike, Prev: Perl, Up: List of Programming Languages - -15.5.19 PHP Hypertext Preprocessor ----------------------------------- - -RPMs - mod_php4, mod_php4-core, phpdoc - -File extension - `php', `php3', `php4' - -String syntax - `"abc"', `'abc'' - -gettext shorthand - `_("abc")' - -gettext/ngettext functions - `gettext', `dgettext', `dcgettext'; starting with PHP 4.2.0 also - `ngettext', `dngettext', `dcngettext' - -textdomain - `textdomain' function - -bindtextdomain - `bindtextdomain' function - -setlocale - Programmer must call `setlocale (LC_ALL, "")' - -Prerequisite - -- - -Use or emulate GNU gettext - use - -Extractor - `xgettext' - -Formatting with positions - `printf "%2\$d %1\$d"' - -Portability - On platforms without gettext, the functions are not available. - -po-mode marking - -- - - An example is available in the `examples' directory: `hello-php'. - - -File: gettext.info, Node: Pike, Next: GCC-source, Prev: PHP, Up: List of Programming Languages - -15.5.20 Pike ------------- - -RPMs - roxen - -File extension - `pike' - -String syntax - `"abc"' - -gettext shorthand - -- - -gettext/ngettext functions - `gettext', `dgettext', `dcgettext' - -textdomain - `textdomain' function - -bindtextdomain - `bindtextdomain' function - -setlocale - `setlocale' function - -Prerequisite - `import Locale.Gettext;' - -Use or emulate GNU gettext - use - -Extractor - -- - -Formatting with positions - -- - -Portability - On platforms without gettext, the functions are not available. - -po-mode marking - -- - - -File: gettext.info, Node: GCC-source, Prev: Pike, Up: List of Programming Languages - -15.5.21 GNU Compiler Collection sources ---------------------------------------- - -RPMs - gcc - -File extension - `c', `h'. - -String syntax - `"abc"' - -gettext shorthand - `_("abc")' - -gettext/ngettext functions - `gettext', `dgettext', `dcgettext', `ngettext', `dngettext', - `dcngettext' - -textdomain - `textdomain' function - -bindtextdomain - `bindtextdomain' function - -setlocale - Programmer must call `setlocale (LC_ALL, "")' - -Prerequisite - `#include "intl.h"' - -Use or emulate GNU gettext - Use - -Extractor - `xgettext -k_' - -Formatting with positions - -- - -Portability - Uses autoconf macros - -po-mode marking - yes - - -File: gettext.info, Node: List of Data Formats, Prev: List of Programming Languages, Up: Programming Languages - -15.6 Internationalizable Data -============================= - - Here is a list of other data formats which can be internationalized -using GNU gettext. - -* Menu: - -* POT:: POT - Portable Object Template -* RST:: Resource String Table -* Glade:: Glade - GNOME user interface description - - -File: gettext.info, Node: POT, Next: RST, Prev: List of Data Formats, Up: List of Data Formats - -15.6.1 POT - Portable Object Template -------------------------------------- - -RPMs - gettext - -File extension - `pot', `po' - -Extractor - `xgettext' - - -File: gettext.info, Node: RST, Next: Glade, Prev: POT, Up: List of Data Formats - -15.6.2 Resource String Table ----------------------------- - -RPMs - fpk - -File extension - `rst' - -Extractor - `xgettext', `rstconv' - - -File: gettext.info, Node: Glade, Prev: RST, Up: List of Data Formats - -15.6.3 Glade - GNOME user interface description ------------------------------------------------ - -RPMs - glade, libglade, glade2, libglade2, intltool - -File extension - `glade', `glade2' - -Extractor - `xgettext', `libglade-xgettext', `xml-i18n-extract', - `intltool-extract' - - -File: gettext.info, Node: Conclusion, Next: Language Codes, Prev: Programming Languages, Up: Top - -16 Concluding Remarks -********************* - - We would like to conclude this GNU `gettext' manual by presenting an -history of the Translation Project so far. We finally give a few -pointers for those who want to do further research or readings about -Native Language Support matters. - -* Menu: - -* History:: History of GNU `gettext' -* References:: Related Readings - - -File: gettext.info, Node: History, Next: References, Prev: Conclusion, Up: Conclusion - -16.1 History of GNU `gettext' -============================= - - Internationalization concerns and algorithms have been informally -and casually discussed for years in GNU, sometimes around GNU `libc', -maybe around the incoming `Hurd', or otherwise (nobody clearly -remembers). And even then, when the work started for real, this was -somewhat independently of these previous discussions. - - This all began in July 1994, when Patrick D'Cruze had the idea and -initiative of internationalizing version 3.9.2 of GNU `fileutils'. He -then asked Jim Meyering, the maintainer, how to get those changes -folded into an official release. That first draft was full of -`#ifdef's and somewhat disconcerting, and Jim wanted to find nicer -ways. Patrick and Jim shared some tries and experimentations in this -area. Then, feeling that this might eventually have a deeper impact on -GNU, Jim wanted to know what standards were, and contacted Richard -Stallman, who very quickly and verbally described an overall design for -what was meant to become `glocale', at that time. - - Jim implemented `glocale' and got a lot of exhausting feedback from -Patrick and Richard, of course, but also from Mitchum DSouza (who wrote -a `catgets'-like package), Roland McGrath, maybe David MacKenzie, -François Pinard, and Paul Eggert, all pushing and pulling in various -directions, not always compatible, to the extent that after a couple of -test releases, `glocale' was torn apart. In particular, Paul Eggert - -always keeping an eye on developments in Solaris - advocated the use of -the `gettext' API over `glocale''s `catgets'-based API. - - While Jim took some distance and time and became dad for a second -time, Roland wanted to get GNU `libc' internationalized, and got Ulrich -Drepper involved in that project. Instead of starting from `glocale', -Ulrich rewrote something from scratch, but more conforming to the set -of guidelines who emerged out of the `glocale' effort. Then, Ulrich -got people from the previous forum to involve themselves into this new -project, and the switch from `glocale' to what was first named -`msgutils', renamed `nlsutils', and later `gettext', became officially -accepted by Richard in May 1995 or so. - - Let's summarize by saying that Ulrich Drepper wrote GNU `gettext' in -April 1995. The first official release of the package, including PO -mode, occurred in July 1995, and was numbered 0.7. Other people -contributed to the effort by providing a discussion forum around -Ulrich, writing little pieces of code, or testing. These are quoted in -the `THANKS' file which comes with the GNU `gettext' distribution. - - While this was being done, François adapted half a dozen of GNU -packages to `glocale' first, then later to `gettext', putting them in -pretest, so providing along the way an effective user environment for -fine tuning the evolving tools. He also took the responsibility of -organizing and coordinating the Translation Project. After nearly a -year of informal exchanges between people from many countries, -translator teams started to exist in May 1995, through the creation and -support by Patrick D'Cruze of twenty unmoderated mailing lists for that -many native languages, and two moderated lists: one for reaching all -teams at once, the other for reaching all willing maintainers of -internationalized free software packages. - - François also wrote PO mode in June 1995 with the collaboration of -Greg McGary, as a kind of contribution to Ulrich's package. He also -gave a hand with the GNU `gettext' Texinfo manual. - - In 1997, Ulrich Drepper released the GNU libc 2.0, which included the -`gettext', `textdomain' and `bindtextdomain' functions. - - In 2000, Ulrich Drepper added plural form handling (the `ngettext' -function) to GNU libc. Later, in 2001, he released GNU libc 2.2.x, -which is the first free C library with full internationalization -support. - - Ulrich being quite busy in his role of General Maintainer of GNU -libc, he handed over the GNU `gettext' maintenance to Bruno Haible in -2000. Bruno added the plural form handling to the tools as well, added -support for UTF-8 and CJK locales, and wrote a few new tools for -manipulating PO files. - - -File: gettext.info, Node: References, Prev: History, Up: Conclusion - -16.2 Related Readings -===================== - - * NOTE: * This documentation section is outdated and needs to be -revised. - - Eugene H. Dorr (`dorre@well.com') maintains an interesting -bibliography on internationalization matters, called -`Internationalization Reference List', which is available as: - ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt - - Michael Gschwind (`mike@vlsivie.tuwien.ac.at') maintains a -Frequently Asked Questions (FAQ) list, entitled `Programming for -Internationalisation'. This FAQ discusses writing programs which can -handle different language conventions, character sets, etc.; and is -applicable to all character set encodings, with particular emphasis on -ISO 8859-1. It is regularly published in Usenet groups -`comp.unix.questions', `comp.std.internat', -`comp.software.international', `comp.lang.c', `comp.windows.x', -`comp.std.c', `comp.answers' and `news.answers'. The home location of -this document is: - ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming - - Patrick D'Cruze (`pdcruze@li.org') wrote a tutorial about NLS -matters, and Jochen Hein (`Hein@student.tu-clausthal.de') took over the -responsibility of maintaining it. It may be found as: - ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/... - ...locale-tutorial-0.8.txt.gz - This site is mirrored in: - ftp://ftp.ibp.fr/pub/linux/sunsite/ - - A French version of the same tutorial should be findable at: - ftp://ftp.ibp.fr/pub/linux/french/docs/ - together with French translations of many Linux-related documents. - - -File: gettext.info, Node: Language Codes, Next: Country Codes, Prev: Conclusion, Up: Top - -Appendix A Language Codes -************************* - - The ISO 639 standard defines two-letter codes for many languages, and -three-letter codes for more rarely used languages. All abbreviations -for languages used in the Translation Project should come from this -standard. - -* Menu: - -* Usual Language Codes:: Two-letter ISO 639 language codes -* Rare Language Codes:: Three-letter ISO 639 language codes - - -File: gettext.info, Node: Usual Language Codes, Next: Rare Language Codes, Prev: Language Codes, Up: Language Codes - -A.1 Usual Language Codes -======================== - - For the commonly used languages, the ISO 639-1 standard defines -two-letter codes. - -`aa' - Afar. - -`ab' - Abkhazian. - -`ae' - Avestan. - -`af' - Afrikaans. - -`ak' - Akan. - -`am' - Amharic. - -`an' - Aragonese. - -`ar' - Arabic. - -`as' - Assamese. - -`av' - Avaric. - -`ay' - Aymara. - -`az' - Azerbaijani. - -`ba' - Bashkir. - -`be' - Belarusian. - -`bg' - Bulgarian. - -`bh' - Bihari. - -`bi' - Bislama. - -`bm' - Bambara. - -`bn' - Bengali; Bangla. - -`bo' - Tibetan. - -`br' - Breton. - -`bs' - Bosnian. - -`ca' - Catalan. - -`ce' - Chechen. - -`ch' - Chamorro. - -`co' - Corsican. - -`cr' - Cree. - -`cs' - Czech. - -`cu' - Church Slavic. - -`cv' - Chuvash. - -`cy' - Welsh. - -`da' - Danish. - -`de' - German. - -`dv' - Divehi; Maldivian. - -`dz' - Dzongkha; Bhutani. - -`ee' - Éwé. - -`el' - Greek. - -`en' - English. - -`eo' - Esperanto. - -`es' - Spanish. - -`et' - Estonian. - -`eu' - Basque. - -`fa' - Persian. - -`ff' - Fulah. - -`fi' - Finnish. - -`fj' - Fijian; Fiji. - -`fo' - Faroese. - -`fr' - French. - -`fy' - Western Frisian. - -`ga' - Irish. - -`gd' - Scottish Gaelic. - -`gl' - Galician. - -`gn' - Guarani. - -`gu' - Gujarati. - -`gv' - Manx. - -`ha' - Hausa. - -`he' - Hebrew (formerly iw). - -`hi' - Hindi. - -`ho' - Hiri Motu. - -`hr' - Croatian. - -`ht' - Haitian; Haitian Creole. - -`hu' - Hungarian. - -`hy' - Armenian. - -`hz' - Herero. - -`ia' - Interlingua. - -`id' - Indonesian (formerly in). - -`ie' - Interlingue; Occidental. - -`ig' - Igbo. - -`ii' - Sichuan Yi; Nuosu. - -`ik' - Inupiak; Inupiaq. - -`io' - Ido. - -`is' - Icelandic. - -`it' - Italian. - -`iu' - Inuktitut. - -`ja' - Japanese. - -`jv' - Javanese. - -`ka' - Georgian. - -`kg' - Kongo. - -`ki' - Kikuyu; Gikuyu. - -`kj' - Kuanyama; Kwanyama. - -`kk' - Kazakh. - -`kl' - Kalaallisut; Greenlandic. - -`km' - Central Khmer; Cambodian. - -`kn' - Kannada. - -`ko' - Korean. - -`kr' - Kanuri. - -`ks' - Kashmiri. - -`ku' - Kurdish. - -`kv' - Komi. - -`kw' - Cornish. - -`ky' - Kirghiz. - -`la' - Latin. - -`lb' - Letzeburgesch; Luxembourgish. - -`lg' - Ganda. - -`li' - Limburgish; Limburger; Limburgan. - -`ln' - Lingala. - -`lo' - Lao; Laotian. - -`lt' - Lithuanian. - -`lu' - Luba-Katanga. - -`lv' - Latvian; Lettish. - -`mg' - Malagasy. - -`mh' - Marshallese. - -`mi' - Maori. - -`mk' - Macedonian. - -`ml' - Malayalam. - -`mn' - Mongolian. - -`mo' - Moldavian. - -`mr' - Marathi. - -`ms' - Malay. - -`mt' - Maltese. - -`my' - Burmese. - -`na' - Nauru. - -`nb' - Norwegian BokmÃ¥l. - -`nd' - Ndebele, North. - -`ne' - Nepali. - -`ng' - Ndonga. - -`nl' - Dutch. - -`nn' - Norwegian Nynorsk. - -`no' - Norwegian. - -`nr' - Ndebele, South. - -`nv' - Navajo; Navaho. - -`ny' - Chichewa; Nyanja. - -`oc' - Occitan; Provençal. - -`oj' - Ojibwa. - -`om' - (Afan) Oromo. - -`or' - Oriya. - -`os' - Ossetian; Ossetic. - -`pa' - Panjabi; Punjabi. - -`pi' - Pali. - -`pl' - Polish. - -`ps' - Pashto; Pushto. - -`pt' - Portuguese. - -`qu' - Quechua. - -`rm' - Romansh. - -`rn' - Rundi; Kirundi. - -`ro' - Romanian. - -`ru' - Russian. - -`rw' - Kinyarwanda. - -`sa' - Sanskrit. - -`sc' - Sardinian. - -`sd' - Sindhi. - -`se' - Northern Sami. - -`sg' - Sango; Sangro. - -`si' - Sinhala; Sinhalese. - -`sk' - Slovak. - -`sl' - Slovenian. - -`sm' - Samoan. - -`sn' - Shona. - -`so' - Somali. - -`sq' - Albanian. - -`sr' - Serbian. - -`ss' - Swati; Siswati. - -`st' - Sesotho; Sotho, Southern. - -`su' - Sundanese. - -`sv' - Swedish. - -`sw' - Swahili. - -`ta' - Tamil. - -`te' - Telugu. - -`tg' - Tajik. - -`th' - Thai. - -`ti' - Tigrinya. - -`tk' - Turkmen. - -`tl' - Tagalog. - -`tn' - Tswana; Setswana. - -`to' - Tonga. - -`tr' - Turkish. - -`ts' - Tsonga. - -`tt' - Tatar. - -`tw' - Twi. - -`ty' - Tahitian. - -`ug' - Uighur. - -`uk' - Ukrainian. - -`ur' - Urdu. - -`uz' - Uzbek. - -`ve' - Venda. - -`vi' - Vietnamese. - -`vo' - Volapük; Volapuk. - -`wa' - Walloon. - -`wo' - Wolof. - -`xh' - Xhosa. - -`yi' - Yiddish (formerly ji). - -`yo' - Yoruba. - -`za' - Zhuang. - -`zh' - Chinese. - -`zu' - Zulu. - - -File: gettext.info, Node: Rare Language Codes, Prev: Usual Language Codes, Up: Language Codes - -A.2 Rare Language Codes -======================= - - For rarely used languages, the ISO 639-2 standard defines -three-letter codes. Here is the current list, reduced to only living -languages with at least one million of speakers. - -`ace' - Achinese. - -`awa' - Awadhi. - -`bal' - Baluchi. - -`ban' - Balinese. - -`bej' - Beja; Bedawiyet. - -`bem' - Bemba. - -`bho' - Bhojpuri. - -`bik' - Bikol. - -`bin' - Bini; Edo. - -`bug' - Buginese. - -`ceb' - Cebuano. - -`din' - Dinka. - -`doi' - Dogri. - -`fil' - Filipino; Pilipino. - -`fon' - Fon. - -`gon' - Gondi. - -`gsw' - Swiss German; Alemannic; Alsatian. - -`hil' - Hiligaynon. - -`hmn' - Hmong. - -`ilo' - Iloko. - -`kab' - Kabyle. - -`kam' - Kamba. - -`kbd' - Kabardian. - -`kmb' - Kimbundu. - -`kok' - Konkani. - -`kru' - Kurukh. - -`lua' - Luba-Lulua. - -`luo' - Luo (Kenya and Tanzania). - -`mad' - Madurese. - -`mag' - Magahi. - -`mai' - Maithili. - -`mak' - Makasar. - -`man' - Mandingo. - -`men' - Mende. - -`min' - Minangkabau. - -`mni' - Manipuri. - -`mos' - Mossi. - -`mwr' - Marwari. - -`nap' - Neapolitan. - -`nso' - Pedi; Sepedi; Northern Sotho. - -`nym' - Nyamwezi. - -`nyn' - Nyankole. - -`pag' - Pangasinan. - -`pam' - Pampanga; Kapampangan. - -`raj' - Rajasthani. - -`sas' - Sasak. - -`sat' - Santali. - -`scn' - Sicilian. - -`shn' - Shan. - -`sid' - Sidamo. - -`srr' - Serer. - -`suk' - Sukuma. - -`sus' - Susu. - -`tem' - Timne. - -`tiv' - Tiv. - -`tum' - Tumbuka. - -`umb' - Umbundu. - -`wal' - Walamo. - -`war' - Waray. - -`yao' - Yao. - - -File: gettext.info, Node: Country Codes, Next: Licenses, Prev: Language Codes, Up: Top - -Appendix B Country Codes -************************ - - The ISO 3166 standard defines two character codes for many countries -and territories. All abbreviations for countries used in the -Translation Project should come from this standard. - -`AD' - Andorra. - -`AE' - United Arab Emirates. - -`AF' - Afghanistan. - -`AG' - Antigua and Barbuda. - -`AI' - Anguilla. - -`AL' - Albania. - -`AM' - Armenia. - -`AN' - Netherlands Antilles. - -`AO' - Angola. - -`AQ' - Antarctica. - -`AR' - Argentina. - -`AS' - Samoa (American). - -`AT' - Austria. - -`AU' - Australia. - -`AW' - Aruba. - -`AX' - Aaland Islands. - -`AZ' - Azerbaijan. - -`BA' - Bosnia and Herzegovina. - -`BB' - Barbados. - -`BD' - Bangladesh. - -`BE' - Belgium. - -`BF' - Burkina Faso. - -`BG' - Bulgaria. - -`BH' - Bahrain. - -`BI' - Burundi. - -`BJ' - Benin. - -`BM' - Bermuda. - -`BN' - Brunei. - -`BO' - Bolivia. - -`BR' - Brazil. - -`BS' - Bahamas. - -`BT' - Bhutan. - -`BV' - Bouvet Island. - -`BW' - Botswana. - -`BY' - Belarus. - -`BZ' - Belize. - -`CA' - Canada. - -`CC' - Cocos (Keeling) Islands. - -`CD' - Congo (Dem. Rep.). - -`CF' - Central African Republic. - -`CG' - Congo (Rep.). - -`CH' - Switzerland. - -`CI' - Côte d'Ivoire. - -`CK' - Cook Islands. - -`CL' - Chile. - -`CM' - Cameroon. - -`CN' - China. - -`CO' - Colombia. - -`CR' - Costa Rica. - -`CU' - Cuba. - -`CV' - Cape Verde. - -`CX' - Christmas Island. - -`CY' - Cyprus. - -`CZ' - Czech Republic. - -`DE' - Germany. - -`DJ' - Djibouti. - -`DK' - Denmark. - -`DM' - Dominica. - -`DO' - Dominican Republic. - -`DZ' - Algeria. - -`EC' - Ecuador. - -`EE' - Estonia. - -`EG' - Egypt. - -`EH' - Western Sahara. - -`ER' - Eritrea. - -`ES' - Spain. - -`ET' - Ethiopia. - -`FI' - Finland. - -`FJ' - Fiji. - -`FK' - Falkland Islands. - -`FM' - Micronesia. - -`FO' - Faeroe Islands. - -`FR' - France. - -`GA' - Gabon. - -`GB' - Britain (United Kingdom). - -`GD' - Grenada. - -`GE' - Georgia. - -`GF' - French Guiana. - -`GG' - Guernsey. - -`GH' - Ghana. - -`GI' - Gibraltar. - -`GL' - Greenland. - -`GM' - Gambia. - -`GN' - Guinea. - -`GP' - Guadeloupe. - -`GQ' - Equatorial Guinea. - -`GR' - Greece. - -`GS' - South Georgia and the South Sandwich Islands. - -`GT' - Guatemala. - -`GU' - Guam. - -`GW' - Guinea-Bissau. - -`GY' - Guyana. - -`HK' - Hong Kong. - -`HM' - Heard Island and McDonald Islands. - -`HN' - Honduras. - -`HR' - Croatia. - -`HT' - Haiti. - -`HU' - Hungary. - -`ID' - Indonesia. - -`IE' - Ireland. - -`IL' - Israel. - -`IM' - Isle of Man. - -`IN' - India. - -`IO' - British Indian Ocean Territory. - -`IQ' - Iraq. - -`IR' - Iran. - -`IS' - Iceland. - -`IT' - Italy. - -`JE' - Jersey. - -`JM' - Jamaica. - -`JO' - Jordan. - -`JP' - Japan. - -`KE' - Kenya. - -`KG' - Kyrgyzstan. - -`KH' - Cambodia. - -`KI' - Kiribati. - -`KM' - Comoros. - -`KN' - St Kitts and Nevis. - -`KP' - Korea (North). - -`KR' - Korea (South). - -`KW' - Kuwait. - -`KY' - Cayman Islands. - -`KZ' - Kazakhstan. - -`LA' - Laos. - -`LB' - Lebanon. - -`LC' - St Lucia. - -`LI' - Liechtenstein. - -`LK' - Sri Lanka. - -`LR' - Liberia. - -`LS' - Lesotho. - -`LT' - Lithuania. - -`LU' - Luxembourg. - -`LV' - Latvia. - -`LY' - Libya. - -`MA' - Morocco. - -`MC' - Monaco. - -`MD' - Moldova. - -`ME' - Montenegro. - -`MG' - Madagascar. - -`MH' - Marshall Islands. - -`MK' - Macedonia. - -`ML' - Mali. - -`MM' - Myanmar (Burma). - -`MN' - Mongolia. - -`MO' - Macao. - -`MP' - Northern Mariana Islands. - -`MQ' - Martinique. - -`MR' - Mauritania. - -`MS' - Montserrat. - -`MT' - Malta. - -`MU' - Mauritius. - -`MV' - Maldives. - -`MW' - Malawi. - -`MX' - Mexico. - -`MY' - Malaysia. - -`MZ' - Mozambique. - -`NA' - Namibia. - -`NC' - New Caledonia. - -`NE' - Niger. - -`NF' - Norfolk Island. - -`NG' - Nigeria. - -`NI' - Nicaragua. - -`NL' - Netherlands. - -`NO' - Norway. - -`NP' - Nepal. - -`NR' - Nauru. - -`NU' - Niue. - -`NZ' - New Zealand. - -`OM' - Oman. - -`PA' - Panama. - -`PE' - Peru. - -`PF' - French Polynesia. - -`PG' - Papua New Guinea. - -`PH' - Philippines. - -`PK' - Pakistan. - -`PL' - Poland. - -`PM' - St Pierre and Miquelon. - -`PN' - Pitcairn. - -`PR' - Puerto Rico. - -`PS' - Palestine. - -`PT' - Portugal. - -`PW' - Palau. - -`PY' - Paraguay. - -`QA' - Qatar. - -`RE' - Reunion. - -`RO' - Romania. - -`RS' - Serbia. - -`RU' - Russia. - -`RW' - Rwanda. - -`SA' - Saudi Arabia. - -`SB' - Solomon Islands. - -`SC' - Seychelles. - -`SD' - Sudan. - -`SE' - Sweden. - -`SG' - Singapore. - -`SH' - St Helena. - -`SI' - Slovenia. - -`SJ' - Svalbard and Jan Mayen. - -`SK' - Slovakia. - -`SL' - Sierra Leone. - -`SM' - San Marino. - -`SN' - Senegal. - -`SO' - Somalia. - -`SR' - Suriname. - -`ST' - Sao Tome and Principe. - -`SV' - El Salvador. - -`SY' - Syria. - -`SZ' - Swaziland. - -`TC' - Turks and Caicos Islands. - -`TD' - Chad. - -`TF' - French Southern and Antarctic Lands. - -`TG' - Togo. - -`TH' - Thailand. - -`TJ' - Tajikistan. - -`TK' - Tokelau. - -`TL' - Timor-Leste. - -`TM' - Turkmenistan. - -`TN' - Tunisia. - -`TO' - Tonga. - -`TR' - Turkey. - -`TT' - Trinidad and Tobago. - -`TV' - Tuvalu. - -`TW' - Taiwan. - -`TZ' - Tanzania. - -`UA' - Ukraine. - -`UG' - Uganda. - -`UM' - US minor outlying islands. - -`US' - United States. - -`UY' - Uruguay. - -`UZ' - Uzbekistan. - -`VA' - Vatican City. - -`VC' - St Vincent and the Grenadines. - -`VE' - Venezuela. - -`VG' - Virgin Islands (UK). - -`VI' - Virgin Islands (US). - -`VN' - Vietnam. - -`VU' - Vanuatu. - -`WF' - Wallis and Futuna. - -`WS' - Samoa (Western). - -`YE' - Yemen. - -`YT' - Mayotte. - -`ZA' - South Africa. - -`ZM' - Zambia. - -`ZW' - Zimbabwe. - - -File: gettext.info, Node: Licenses, Next: Program Index, Prev: Country Codes, Up: Top - -Appendix C Licenses -******************* - - The files of this package are covered by the licenses indicated in -each particular file or directory. Here is a summary: - - * The `libintl' and `libasprintf' libraries are covered by the GNU - Library General Public License (LGPL). A copy of the license is - included in *note GNU LGPL::. - - * The executable programs of this package and the `libgettextpo' - library are covered by the GNU General Public License (GPL). A - copy of the license is included in *note GNU GPL::. - - * This manual is free documentation. It is dually licensed under the - GNU FDL and the GNU GPL. This means that you can redistribute this - manual under either of these two licenses, at your choice. - This manual is covered by the GNU FDL. Permission is granted to - copy, distribute and/or modify this document under the terms of the - GNU Free Documentation License (FDL), either version 1.2 of the - License, or (at your option) any later version published by the - Free Software Foundation (FSF); with no Invariant Sections, with no - Front-Cover Text, and with no Back-Cover Texts. A copy of the - license is included in *note GNU FDL::. - This manual is covered by the GNU GPL. You can redistribute it - and/or modify it under the terms of the GNU General Public License - (GPL), either version 2 of the License, or (at your option) any - later version published by the Free Software Foundation (FSF). A - copy of the license is included in *note GNU GPL::. - -* Menu: - -* GNU GPL:: GNU General Public License -* GNU LGPL:: GNU Lesser General Public License -* GNU FDL:: GNU Free Documentation License - - -File: gettext.info, Node: GNU GPL, Next: GNU LGPL, Up: Licenses - -C.1 GNU GENERAL PUBLIC LICENSE -============================== - - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - -Preamble --------- - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it in -new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, -and (2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains a - notice placed by the copyright holder saying it may be distributed - under the terms of this General Public License. The "Program", - below, refers to any such program or work, and a "work based on - the Program" means either the Program or any derivative work under - copyright law: that is to say, a work containing the Program or a - portion of it, either verbatim or with modifications and/or - translated into another language. (Hereinafter, translation is - included without limitation in the term "modification".) Each - licensee is addressed as "you". - - Activities other than copying, distribution and modification are - not covered by this License; they are outside its scope. The act - of running the Program is not restricted, and the output from the - Program is covered only if its contents constitute a work based on - the Program (independent of having been made by running the - Program). Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's - source code as you receive it, in any medium, provided that you - conspicuously and appropriately publish on each copy an appropriate - copyright notice and disclaimer of warranty; keep intact all the - notices that refer to this License and to the absence of any - warranty; and give any other recipients of the Program a copy of - this License along with the Program. - - You may charge a fee for the physical act of transferring a copy, - and you may at your option offer warranty protection in exchange - for a fee. - - 2. You may modify your copy or copies of the Program or any portion - of it, thus forming a work based on the Program, and copy and - distribute such modifications or work under the terms of Section 1 - above, provided that you also meet all of these conditions: - - a. You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b. You must cause any work that you distribute or publish, that - in whole or in part contains or is derived from the Program - or any part thereof, to be licensed as a whole at no charge - to all third parties under the terms of this License. - - c. If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display - an announcement including an appropriate copyright notice and - a notice that there is no warranty (or else, saying that you - provide a warranty) and that users may redistribute the - program under these conditions, and telling the user how to - view a copy of this License. (Exception: if the Program - itself is interactive but does not normally print such an - announcement, your work based on the Program is not required - to print an announcement.) - - These requirements apply to the modified work as a whole. If - identifiable sections of that work are not derived from the - Program, and can be reasonably considered independent and separate - works in themselves, then this License, and its terms, do not - apply to those sections when you distribute them as separate - works. But when you distribute the same sections as part of a - whole which is a work based on the Program, the distribution of - the whole must be on the terms of this License, whose permissions - for other licensees extend to the entire whole, and thus to each - and every part regardless of who wrote it. - - Thus, it is not the intent of this section to claim rights or - contest your rights to work written entirely by you; rather, the - intent is to exercise the right to control the distribution of - derivative or collective works based on the Program. - - In addition, mere aggregation of another work not based on the - Program with the Program (or with a work based on the Program) on - a volume of a storage or distribution medium does not bring the - other work under the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, - under Section 2) in object code or executable form under the terms - of Sections 1 and 2 above provided that you also do one of the - following: - - a. Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of - Sections 1 and 2 above on a medium customarily used for - software interchange; or, - - b. Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a - medium customarily used for software interchange; or, - - c. Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with - such an offer, in accord with Subsection b above.) - - The source code for a work means the preferred form of the work for - making modifications to it. For an executable work, complete - source code means all the source code for all modules it contains, - plus any associated interface definition files, plus the scripts - used to control compilation and installation of the executable. - However, as a special exception, the source code distributed need - not include anything that is normally distributed (in either - source or binary form) with the major components (compiler, - kernel, and so on) of the operating system on which the executable - runs, unless that component itself accompanies the executable. - - If distribution of executable or object code is made by offering - access to copy from a designated place, then offering equivalent - access to copy the source code from the same place counts as - distribution of the source code, even though third parties are not - compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program - except as expressly provided under this License. Any attempt - otherwise to copy, modify, sublicense or distribute the Program is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 5. You are not required to accept this License, since you have not - signed it. However, nothing else grants you permission to modify - or distribute the Program or its derivative works. These actions - are prohibited by law if you do not accept this License. - Therefore, by modifying or distributing the Program (or any work - based on the Program), you indicate your acceptance of this - License to do so, and all its terms and conditions for copying, - distributing or modifying the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the - Program), the recipient automatically receives a license from the - original licensor to copy, distribute or modify the Program - subject to these terms and conditions. You may not impose any - further restrictions on the recipients' exercise of the rights - granted herein. You are not responsible for enforcing compliance - by third parties to this License. - - 7. If, as a consequence of a court judgment or allegation of patent - infringement or for any other reason (not limited to patent - issues), conditions are imposed on you (whether by court order, - agreement or otherwise) that contradict the conditions of this - License, they do not excuse you from the conditions of this - License. If you cannot distribute so as to satisfy simultaneously - your obligations under this License and any other pertinent - obligations, then as a consequence you may not distribute the - Program at all. For example, if a patent license would not permit - royalty-free redistribution of the Program by all those who - receive copies directly or indirectly through you, then the only - way you could satisfy both it and this License would be to refrain - entirely from distribution of the Program. - - If any portion of this section is held invalid or unenforceable - under any particular circumstance, the balance of the section is - intended to apply and the section as a whole is intended to apply - in other circumstances. - - It is not the purpose of this section to induce you to infringe any - patents or other property right claims or to contest validity of - any such claims; this section has the sole purpose of protecting - the integrity of the free software distribution system, which is - implemented by public license practices. Many people have made - generous contributions to the wide range of software distributed - through that system in reliance on consistent application of that - system; it is up to the author/donor to decide if he or she is - willing to distribute software through any other system and a - licensee cannot impose that choice. - - This section is intended to make thoroughly clear what is believed - to be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in - certain countries either by patents or by copyrighted interfaces, - the original copyright holder who places the Program under this - License may add an explicit geographical distribution limitation - excluding those countries, so that distribution is permitted only - in or among countries not thus excluded. In such case, this - License incorporates the limitation as if written in the body of - this License. - - 9. The Free Software Foundation may publish revised and/or new - versions of the General Public License from time to time. Such - new versions will be similar in spirit to the present version, but - may differ in detail to address new problems or concerns. - - Each version is given a distinguishing version number. If the - Program specifies a version number of this License which applies - to it and "any later version", you have the option of following - the terms and conditions either of that version or of any later - version published by the Free Software Foundation. If the Program - does not specify a version number of this License, you may choose - any version ever published by the Free Software Foundation. - - 10. If you wish to incorporate parts of the Program into other free - programs whose distribution conditions are different, write to the - author to ask for permission. For software which is copyrighted - by the Free Software Foundation, write to the Free Software - Foundation; we sometimes make exceptions for this. Our decision - will be guided by the two goals of preserving the free status of - all derivatives of our free software and of promoting the sharing - and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO - WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE - LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT - HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT - WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT - NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE - QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE - PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY - SERVICING, REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN - WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY - MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE - LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, - INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR - INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF - DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU - OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY - OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN - ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - -Appendix: How to Apply These Terms to Your New Programs -------------------------------------------------------- - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. - Copyright (C) YYYY NAME OF AUTHOR - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - - Also add information on how to contact you by electronic and paper -mail. - - If the program is interactive, make it output a short notice like -this when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - - The hypothetical commands `show w' and `show c' should show the -appropriate parts of the General Public License. Of course, the -commands you use may be called something other than `show w' and `show -c'; they could even be mouse-clicks or menu items--whatever suits your -program. - - You should also get your employer (if you work as a programmer) or -your school, if any, to sign a "copyright disclaimer" for the program, -if necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - SIGNATURE OF TY COON, 1 April 1989 - Ty Coon, President of Vice - - This General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use the -GNU Library General Public License instead of this License. - - -File: gettext.info, Node: GNU LGPL, Next: GNU FDL, Prev: GNU GPL, Up: Licenses - -C.2 GNU LESSER GENERAL PUBLIC LICENSE -===================================== - - Version 2.1, February 1999 - - Copyright (C) 1991, 1999 Free Software Foundation, Inc. - 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - [This is the first released version of the Lesser GPL. It also counts - as the successor of the GNU Library Public License, version 2, hence the - version number 2.1.] - -Preamble --------- - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -Licenses are intended to guarantee your freedom to share and change -free software--to make sure the software is free for all its users. - - This license, the Lesser General Public License, applies to some -specially designated software--typically libraries--of the Free -Software Foundation and other authors who decide to use it. You can use -it too, but we suggest you first think carefully about whether this -license or the ordinary General Public License is the better strategy to -use in any particular case, based on the explanations below. - - When we speak of free software, we are referring to freedom of use, -not price. Our General Public Licenses are designed to make sure that -you have the freedom to distribute copies of free software (and charge -for this service if you wish); that you receive source code or can get -it if you want it; that you can change the software and use pieces of it -in new free programs; and that you are informed that you can do these -things. - - To protect your rights, we need to make restrictions that forbid -distributors to deny you these rights or to ask you to surrender these -rights. These restrictions translate to certain responsibilities for -you if you distribute copies of the library or if you modify it. - - For example, if you distribute copies of the library, whether gratis -or for a fee, you must give the recipients all the rights that we gave -you. You must make sure that they, too, receive or can get the source -code. If you link other code with the library, you must provide -complete object files to the recipients, so that they can relink them -with the library after making changes to the library and recompiling -it. And you must show them these terms so they know their rights. - - We protect your rights with a two-step method: (1) we copyright the -library, and (2) we offer you this license, which gives you legal -permission to copy, distribute and/or modify the library. - - To protect each distributor, we want to make it very clear that -there is no warranty for the free library. Also, if the library is -modified by someone else and passed on, the recipients should know that -what they have is not the original version, so that the original -author's reputation will not be affected by problems that might be -introduced by others. - - Finally, software patents pose a constant threat to the existence of -any free program. We wish to make sure that a company cannot -effectively restrict the users of a free program by obtaining a -restrictive license from a patent holder. Therefore, we insist that -any patent license obtained for a version of the library must be -consistent with the full freedom of use specified in this license. - - Most GNU software, including some libraries, is covered by the -ordinary GNU General Public License. This license, the GNU Lesser -General Public License, applies to certain designated libraries, and is -quite different from the ordinary General Public License. We use this -license for certain libraries in order to permit linking those -libraries into non-free programs. - - When a program is linked with a library, whether statically or using -a shared library, the combination of the two is legally speaking a -combined work, a derivative of the original library. The ordinary -General Public License therefore permits such linking only if the -entire combination fits its criteria of freedom. The Lesser General -Public License permits more lax criteria for linking other code with -the library. - - We call this license the "Lesser" General Public License because it -does _Less_ to protect the user's freedom than the ordinary General -Public License. It also provides other free software developers Less -of an advantage over competing non-free programs. These disadvantages -are the reason we use the ordinary General Public License for many -libraries. However, the Lesser license provides advantages in certain -special circumstances. - - For example, on rare occasions, there may be a special need to -encourage the widest possible use of a certain library, so that it -becomes a de-facto standard. To achieve this, non-free programs must be -allowed to use the library. A more frequent case is that a free -library does the same job as widely used non-free libraries. In this -case, there is little to gain by limiting the free library to free -software only, so we use the Lesser General Public License. - - In other cases, permission to use a particular library in non-free -programs enables a greater number of people to use a large body of free -software. For example, permission to use the GNU C Library in non-free -programs enables many more people to use the whole GNU operating -system, as well as its variant, the GNU/Linux operating system. - - Although the Lesser General Public License is Less protective of the -users' freedom, it does ensure that the user of a program that is -linked with the Library has the freedom and the wherewithal to run that -program using a modified version of the Library. - - The precise terms and conditions for copying, distribution and -modification follow. Pay close attention to the difference between a -"work based on the library" and a "work that uses the library". The -former contains code derived from the library, whereas the latter must -be combined with the library in order to run. - - GNU LESSER GENERAL PUBLIC LICENSE - - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License Agreement applies to any software library or other - program which contains a notice placed by the copyright holder or - other authorized party saying it may be distributed under the - terms of this Lesser General Public License (also called "this - License"). Each licensee is addressed as "you". - - A "library" means a collection of software functions and/or data - prepared so as to be conveniently linked with application programs - (which use some of those functions and data) to form executables. - - The "Library", below, refers to any such software library or work - which has been distributed under these terms. A "work based on the - Library" means either the Library or any derivative work under - copyright law: that is to say, a work containing the Library or a - portion of it, either verbatim or with modifications and/or - translated straightforwardly into another language. (Hereinafter, - translation is included without limitation in the term - "modification".) - - "Source code" for a work means the preferred form of the work for - making modifications to it. For a library, complete source code - means all the source code for all modules it contains, plus any - associated interface definition files, plus the scripts used to - control compilation and installation of the library. - - Activities other than copying, distribution and modification are - not covered by this License; they are outside its scope. The act - of running a program using the Library is not restricted, and - output from such a program is covered only if its contents - constitute a work based on the Library (independent of the use of - the Library in a tool for writing it). Whether that is true - depends on what the Library does and what the program that uses - the Library does. - - 1. You may copy and distribute verbatim copies of the Library's - complete source code as you receive it, in any medium, provided - that you conspicuously and appropriately publish on each copy an - appropriate copyright notice and disclaimer of warranty; keep - intact all the notices that refer to this License and to the - absence of any warranty; and distribute a copy of this License - along with the Library. - - You may charge a fee for the physical act of transferring a copy, - and you may at your option offer warranty protection in exchange - for a fee. - - 2. You may modify your copy or copies of the Library or any portion - of it, thus forming a work based on the Library, and copy and - distribute such modifications or work under the terms of Section 1 - above, provided that you also meet all of these conditions: - - a. The modified work must itself be a software library. - - b. You must cause the files modified to carry prominent notices - stating that you changed the files and the date of any change. - - c. You must cause the whole of the work to be licensed at no - charge to all third parties under the terms of this License. - - d. If a facility in the modified Library refers to a function or - a table of data to be supplied by an application program that - uses the facility, other than as an argument passed when the - facility is invoked, then you must make a good faith effort - to ensure that, in the event an application does not supply - such function or table, the facility still operates, and - performs whatever part of its purpose remains meaningful. - - (For example, a function in a library to compute square roots - has a purpose that is entirely well-defined independent of the - application. Therefore, Subsection 2d requires that any - application-supplied function or table used by this function - must be optional: if the application does not supply it, the - square root function must still compute square roots.) - - These requirements apply to the modified work as a whole. If - identifiable sections of that work are not derived from the - Library, and can be reasonably considered independent and separate - works in themselves, then this License, and its terms, do not - apply to those sections when you distribute them as separate - works. But when you distribute the same sections as part of a - whole which is a work based on the Library, the distribution of - the whole must be on the terms of this License, whose permissions - for other licensees extend to the entire whole, and thus to each - and every part regardless of who wrote it. - - Thus, it is not the intent of this section to claim rights or - contest your rights to work written entirely by you; rather, the - intent is to exercise the right to control the distribution of - derivative or collective works based on the Library. - - In addition, mere aggregation of another work not based on the - Library with the Library (or with a work based on the Library) on - a volume of a storage or distribution medium does not bring the - other work under the scope of this License. - - 3. You may opt to apply the terms of the ordinary GNU General Public - License instead of this License to a given copy of the Library. - To do this, you must alter all the notices that refer to this - License, so that they refer to the ordinary GNU General Public - License, version 2, instead of to this License. (If a newer - version than version 2 of the ordinary GNU General Public License - has appeared, then you can specify that version instead if you - wish.) Do not make any other change in these notices. - - Once this change is made in a given copy, it is irreversible for - that copy, so the ordinary GNU General Public License applies to - all subsequent copies and derivative works made from that copy. - - This option is useful when you wish to copy part of the code of - the Library into a program that is not a library. - - 4. You may copy and distribute the Library (or a portion or - derivative of it, under Section 2) in object code or executable - form under the terms of Sections 1 and 2 above provided that you - accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software - interchange. - - If distribution of object code is made by offering access to copy - from a designated place, then offering equivalent access to copy - the source code from the same place satisfies the requirement to - distribute the source code, even though third parties are not - compelled to copy the source along with the object code. - - 5. A program that contains no derivative of any portion of the - Library, but is designed to work with the Library by being - compiled or linked with it, is called a "work that uses the - Library". Such a work, in isolation, is not a derivative work of - the Library, and therefore falls outside the scope of this License. - - However, linking a "work that uses the Library" with the Library - creates an executable that is a derivative of the Library (because - it contains portions of the Library), rather than a "work that - uses the library". The executable is therefore covered by this - License. Section 6 states terms for distribution of such - executables. - - When a "work that uses the Library" uses material from a header - file that is part of the Library, the object code for the work may - be a derivative work of the Library even though the source code is - not. Whether this is true is especially significant if the work - can be linked without the Library, or if the work is itself a - library. The threshold for this to be true is not precisely - defined by law. - - If such an object file uses only numerical parameters, data - structure layouts and accessors, and small macros and small inline - functions (ten lines or less in length), then the use of the object - file is unrestricted, regardless of whether it is legally a - derivative work. (Executables containing this object code plus - portions of the Library will still fall under Section 6.) - - Otherwise, if the work is a derivative of the Library, you may - distribute the object code for the work under the terms of Section - 6. Any executables containing that work also fall under Section 6, - whether or not they are linked directly with the Library itself. - - 6. As an exception to the Sections above, you may also combine or - link a "work that uses the Library" with the Library to produce a - work containing portions of the Library, and distribute that work - under terms of your choice, provided that the terms permit - modification of the work for the customer's own use and reverse - engineering for debugging such modifications. - - You must give prominent notice with each copy of the work that the - Library is used in it and that the Library and its use are covered - by this License. You must supply a copy of this License. If the - work during execution displays copyright notices, you must include - the copyright notice for the Library among them, as well as a - reference directing the user to the copy of this License. Also, - you must do one of these things: - - a. Accompany the work with the complete corresponding - machine-readable source code for the Library including - whatever changes were used in the work (which must be - distributed under Sections 1 and 2 above); and, if the work - is an executable linked with the Library, with the complete - machine-readable "work that uses the Library", as object code - and/or source code, so that the user can modify the Library - and then relink to produce a modified executable containing - the modified Library. (It is understood that the user who - changes the contents of definitions files in the Library will - not necessarily be able to recompile the application to use - the modified definitions.) - - b. Use a suitable shared library mechanism for linking with the - Library. A suitable mechanism is one that (1) uses at run - time a copy of the library already present on the user's - computer system, rather than copying library functions into - the executable, and (2) will operate properly with a modified - version of the library, if the user installs one, as long as - the modified version is interface-compatible with the version - that the work was made with. - - c. Accompany the work with a written offer, valid for at least - three years, to give the same user the materials specified in - Subsection 6a, above, for a charge no more than the cost of - performing this distribution. - - d. If distribution of the work is made by offering access to copy - from a designated place, offer equivalent access to copy the - above specified materials from the same place. - - e. Verify that the user has already received a copy of these - materials or that you have already sent this user a copy. - - For an executable, the required form of the "work that uses the - Library" must include any data and utility programs needed for - reproducing the executable from it. However, as a special - exception, the materials to be distributed need not include - anything that is normally distributed (in either source or binary - form) with the major components (compiler, kernel, and so on) of - the operating system on which the executable runs, unless that - component itself accompanies the executable. - - It may happen that this requirement contradicts the license - restrictions of other proprietary libraries that do not normally - accompany the operating system. Such a contradiction means you - cannot use both them and the Library together in an executable - that you distribute. - - 7. You may place library facilities that are a work based on the - Library side-by-side in a single library together with other - library facilities not covered by this License, and distribute - such a combined library, provided that the separate distribution - of the work based on the Library and of the other library - facilities is otherwise permitted, and provided that you do these - two things: - - a. Accompany the combined library with a copy of the same work - based on the Library, uncombined with any other library - facilities. This must be distributed under the terms of the - Sections above. - - b. Give prominent notice with the combined library of the fact - that part of it is a work based on the Library, and explaining - where to find the accompanying uncombined form of the same - work. - - 8. You may not copy, modify, sublicense, link with, or distribute the - Library except as expressly provided under this License. Any - attempt otherwise to copy, modify, sublicense, link with, or - distribute the Library is void, and will automatically terminate - your rights under this License. However, parties who have - received copies, or rights, from you under this License will not - have their licenses terminated so long as such parties remain in - full compliance. - - 9. You are not required to accept this License, since you have not - signed it. However, nothing else grants you permission to modify - or distribute the Library or its derivative works. These actions - are prohibited by law if you do not accept this License. - Therefore, by modifying or distributing the Library (or any work - based on the Library), you indicate your acceptance of this - License to do so, and all its terms and conditions for copying, - distributing or modifying the Library or works based on it. - - 10. Each time you redistribute the Library (or any work based on the - Library), the recipient automatically receives a license from the - original licensor to copy, distribute, link with or modify the - Library subject to these terms and conditions. You may not impose - any further restrictions on the recipients' exercise of the rights - granted herein. You are not responsible for enforcing compliance - by third parties with this License. - - 11. If, as a consequence of a court judgment or allegation of patent - infringement or for any other reason (not limited to patent - issues), conditions are imposed on you (whether by court order, - agreement or otherwise) that contradict the conditions of this - License, they do not excuse you from the conditions of this - License. If you cannot distribute so as to satisfy simultaneously - your obligations under this License and any other pertinent - obligations, then as a consequence you may not distribute the - Library at all. For example, if a patent license would not permit - royalty-free redistribution of the Library by all those who - receive copies directly or indirectly through you, then the only - way you could satisfy both it and this License would be to refrain - entirely from distribution of the Library. - - If any portion of this section is held invalid or unenforceable - under any particular circumstance, the balance of the section is - intended to apply, and the section as a whole is intended to apply - in other circumstances. - - It is not the purpose of this section to induce you to infringe any - patents or other property right claims or to contest validity of - any such claims; this section has the sole purpose of protecting - the integrity of the free software distribution system which is - implemented by public license practices. Many people have made - generous contributions to the wide range of software distributed - through that system in reliance on consistent application of that - system; it is up to the author/donor to decide if he or she is - willing to distribute software through any other system and a - licensee cannot impose that choice. - - This section is intended to make thoroughly clear what is believed - to be a consequence of the rest of this License. - - 12. If the distribution and/or use of the Library is restricted in - certain countries either by patents or by copyrighted interfaces, - the original copyright holder who places the Library under this - License may add an explicit geographical distribution limitation - excluding those countries, so that distribution is permitted only - in or among countries not thus excluded. In such case, this - License incorporates the limitation as if written in the body of - this License. - - 13. The Free Software Foundation may publish revised and/or new - versions of the Lesser General Public License from time to time. - Such new versions will be similar in spirit to the present version, - but may differ in detail to address new problems or concerns. - - Each version is given a distinguishing version number. If the - Library specifies a version number of this License which applies - to it and "any later version", you have the option of following - the terms and conditions either of that version or of any later - version published by the Free Software Foundation. If the Library - does not specify a license version number, you may choose any - version ever published by the Free Software Foundation. - - 14. If you wish to incorporate parts of the Library into other free - programs whose distribution conditions are incompatible with these, - write to the author to ask for permission. For software which is - copyrighted by the Free Software Foundation, write to the Free - Software Foundation; we sometimes make exceptions for this. Our - decision will be guided by the two goals of preserving the free - status of all derivatives of our free software and of promoting - the sharing and reuse of software generally. - - NO WARRANTY - - 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO - WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE - LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT - HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT - WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT - NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE - QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE - LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY - SERVICING, REPAIR OR CORRECTION. - - 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN - WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY - MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE - LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, - INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR - INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF - DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU - OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY - OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN - ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - -How to Apply These Terms to Your New Libraries ----------------------------------------------- - - If you develop a new library, and you want it to be of the greatest -possible use to the public, we recommend making it free software that -everyone can redistribute and change. You can do so by permitting -redistribution under these terms (or, alternatively, under the terms of -the ordinary General Public License). - - To apply these terms, attach the following notices to the library. -It is safest to attach them to the start of each source file to most -effectively convey the exclusion of warranty; and each file should have -at least the "copyright" line and a pointer to where the full notice is -found. - - ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES. - Copyright (C) YEAR NAME OF AUTHOR - - This library is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or (at - your option) any later version. - - This library is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, - USA. - - Also add information on how to contact you by electronic and paper -mail. - - You should also get your employer (if you work as a programmer) or -your school, if any, to sign a "copyright disclaimer" for the library, -if necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the library - `Frob' (a library for tweaking knobs) written by James Random Hacker. - - SIGNATURE OF TY COON, 1 April 1990 - Ty Coon, President of Vice - - That's all there is to it! - - -File: gettext.info, Node: GNU FDL, Prev: GNU LGPL, Up: Licenses - -C.3 GNU Free Documentation License -================================== - - Version 1.2, November 2002 - - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. - We recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it - can be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You - accept the license if you copy, modify or distribute the work in a - way requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in - the notice that says that the Document is released under this - License. If a section does not fit the above definition of - Secondary then it is not allowed to be designated as Invariant. - The Document may contain zero Invariant Sections. If the Document - does not identify any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup, or absence of - markup, has been arranged to thwart or discourage subsequent - modification by readers is not Transparent. An image format is - not Transparent if used for any substantial amount of text. A - copy that is not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and - standard-conforming simple HTML, PostScript or PDF designed for - human modification. Examples of transparent image formats include - PNG, XCF and JPG. Opaque formats include proprietary formats that - can be read and edited only by proprietary word processors, SGML or - XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML, PostScript or PDF - produced by some word processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow - the conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the - title equally prominent and visible. You may add other material - on the covers in addition. Copying with changes limited to the - covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in - other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a computer-network location from - which the general network-using public has access to download - using public-standard network protocols a complete Transparent - copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of - copies, to give them a chance to provide you with an updated - version of the Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with - the Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version to - whoever possesses a copy of it. In addition, you must do these - things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of - previous versions (which should, if there were any, be listed - in the History section of the Document). You may use the - same title as a previous version if the original publisher of - that version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on - the Title Page. If there is no section Entitled "History" in - the Document, create one stating the title, year, authors, - and publisher of the Document as given on its Title Page, - then add an item describing the Modified Version as stated in - the previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in - the "History" section. You may omit a network location for a - work that was published at least four years before the - Document itself, or if the original publisher of the version - it refers to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the - section all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section - titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end - of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow - this License in all other respects regarding verbatim copying of - that document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included in an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warranty Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - `http://www.gnu.org/copyleft/'. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. - -ADDENDUM: How to use this License for your documents ----------------------------------------------------- - - To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover -Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, to -permit their use in free software. - - -File: gettext.info, Node: Program Index, Next: Option Index, Prev: Licenses, Up: Top - -Program Index -************* - - -* Menu: - -* autopoint: autopoint Invocation. (line 6) -* envsubst: envsubst Invocation. (line 6) -* gettext <1>: gettext Invocation. (line 6) -* gettext: sh. (line 19) -* gettextize: gettextize Invocation. - (line 34) -* msgattrib: msgattrib Invocation. (line 6) -* msgcat: msgcat Invocation. (line 6) -* msgcmp: msgcmp Invocation. (line 6) -* msgcomm: msgcomm Invocation. (line 6) -* msgconv: msgconv Invocation. (line 6) -* msgen: msgen Invocation. (line 6) -* msgexec: msgexec Invocation. (line 6) -* msgfilter: msgfilter Invocation. (line 6) -* msgfmt: msgfmt Invocation. (line 6) -* msggrep: msggrep Invocation. (line 6) -* msginit: msginit Invocation. (line 6) -* msgmerge: msgmerge Invocation. (line 6) -* msgunfmt: msgunfmt Invocation. (line 6) -* msguniq: msguniq Invocation. (line 6) -* ngettext <1>: ngettext Invocation. (line 6) -* ngettext: sh. (line 19) -* recode-sr-latin: msgfilter Invocation. (line 92) -* xgettext: xgettext Invocation. (line 6) - - -File: gettext.info, Node: Option Index, Next: Variable Index, Prev: Program Index, Up: Top - -Option Index -************ - - -* Menu: - -* --add-comments, xgettext option: xgettext Invocation. (line 97) -* --add-location, msgattrib option: msgattrib Invocation. - (line 136) -* --add-location, msgcat option: msgcat Invocation. (line 119) -* --add-location, msgcomm option: msgcomm Invocation. (line 104) -* --add-location, msgconv option: msgconv Invocation. (line 83) -* --add-location, msgen option: msgen Invocation. (line 85) -* --add-location, msgfilter option: msgfilter Invocation. - (line 144) -* --add-location, msggrep option: msggrep Invocation. (line 161) -* --add-location, msgmerge option: msgmerge Invocation. (line 155) -* --add-location, msguniq option: msguniq Invocation. (line 101) -* --add-location, xgettext option: xgettext Invocation. (line 297) -* --alignment, msgfmt option: msgfmt Invocation. (line 209) -* --backup, msgmerge option: msgmerge Invocation. (line 65) -* --boost, xgettext option: xgettext Invocation. (line 254) -* --c++, xgettext option: xgettext Invocation. (line 64) -* --check, msgfmt option: msgfmt Invocation. (line 146) -* --check-accelerators, msgfmt option: msgfmt Invocation. (line 187) -* --check-compatibility, msgfmt option: msgfmt Invocation. (line 183) -* --check-domain, msgfmt option: msgfmt Invocation. (line 178) -* --check-format, msgfmt option: msgfmt Invocation. (line 150) -* --check-header, msgfmt option: msgfmt Invocation. (line 173) -* --clear-fuzzy, msgattrib option: msgattrib Invocation. - (line 71) -* --clear-obsolete, msgattrib option: msgattrib Invocation. - (line 77) -* --clear-previous, msgattrib option: msgattrib Invocation. - (line 80) -* --color, msgattrib option: msgattrib Invocation. - (line 117) -* --color, msgcat option <1>: The --color option. (line 6) -* --color, msgcat option: msgcat Invocation. (line 100) -* --color, msgcomm option: msgcomm Invocation. (line 85) -* --color, msgconv option: msgconv Invocation. (line 65) -* --color, msgen option: msgen Invocation. (line 67) -* --color, msgfilter option: msgfilter Invocation. - (line 122) -* --color, msggrep option: msggrep Invocation. (line 144) -* --color, msginit option: msginit Invocation. (line 63) -* --color, msgmerge option: msgmerge Invocation. (line 137) -* --color, msgunfmt option: msgunfmt Invocation. (line 109) -* --color, msguniq option: msguniq Invocation. (line 82) -* --color, xgettext option: xgettext Invocation. (line 276) -* --comment, msggrep option: msggrep Invocation. (line 93) -* --compendium, msgmerge option: msgmerge Invocation. (line 36) -* --copyright-holder, xgettext option: xgettext Invocation. (line 347) -* --csharp, msgfmt option: msgfmt Invocation. (line 36) -* --csharp, msgunfmt option: msgunfmt Invocation. (line 19) -* --csharp-resources, msgfmt option: msgfmt Invocation. (line 40) -* --csharp-resources, msgunfmt option: msgunfmt Invocation. (line 23) -* --debug, xgettext option: xgettext Invocation. (line 258) -* --default-domain, xgettext option: xgettext Invocation. (line 36) -* --directory, msgattrib option: msgattrib Invocation. - (line 19) -* --directory, msgcat option: msgcat Invocation. (line 32) -* --directory, msgcmp option: msgcmp Invocation. (line 27) -* --directory, msgcomm option: msgcomm Invocation. (line 30) -* --directory, msgconv option: msgconv Invocation. (line 19) -* --directory, msgen option: msgen Invocation. (line 25) -* --directory, msgexec option: msgexec Invocation. (line 44) -* --directory, msgfilter option: msgfilter Invocation. - (line 27) -* --directory, msgfmt option: msgfmt Invocation. (line 18) -* --directory, msggrep option: msggrep Invocation. (line 19) -* --directory, msgmerge option: msgmerge Invocation. (line 30) -* --directory, msguniq option: msguniq Invocation. (line 26) -* --directory, xgettext option: xgettext Invocation. (line 24) -* --domain, gettext option: gettext Invocation. (line 16) -* --domain, msggrep option: msggrep Invocation. (line 77) -* --domain, ngettext option: ngettext Invocation. (line 15) -* --dry-run, autopoint option: autopoint Invocation. - (line 24) -* --dry-run, gettextize option: gettextize Invocation. - (line 72) -* --exclude-file, xgettext option: xgettext Invocation. (line 92) -* --expression, msgfilter option: msgfilter Invocation. - (line 77) -* --extended-regexp, msggrep option: msggrep Invocation. (line 101) -* --extract-all, xgettext option: xgettext Invocation. (line 107) -* --extracted-comment, msggrep option: msggrep Invocation. (line 97) -* --file, msgfilter option: msgfilter Invocation. - (line 81) -* --file, msggrep option: msggrep Invocation. (line 113) -* --files-from, msgcat option: msgcat Invocation. (line 27) -* --files-from, msgcomm option: msgcomm Invocation. (line 25) -* --files-from, xgettext option: xgettext Invocation. (line 19) -* --fixed-strings, msggrep option: msggrep Invocation. (line 105) -* --flag, xgettext option: xgettext Invocation. (line 201) -* --force, autopoint option: autopoint Invocation. - (line 20) -* --force, gettextize option: gettextize Invocation. - (line 40) -* --force-po, msgattrib option: msgattrib Invocation. - (line 125) -* --force-po, msgcat option: msgcat Invocation. (line 108) -* --force-po, msgcomm option: msgcomm Invocation. (line 93) -* --force-po, msgconv option: msgconv Invocation. (line 73) -* --force-po, msgen option: msgen Invocation. (line 75) -* --force-po, msgfilter option: msgfilter Invocation. - (line 130) -* --force-po, msggrep option: msggrep Invocation. (line 152) -* --force-po, msgmerge option: msgmerge Invocation. (line 145) -* --force-po, msgunfmt option: msgunfmt Invocation. (line 117) -* --force-po, msguniq option: msguniq Invocation. (line 90) -* --force-po, xgettext option: xgettext Invocation. (line 284) -* --foreign-user, xgettext option: xgettext Invocation. (line 362) -* --from-code, xgettext option: xgettext Invocation. (line 74) -* --fuzzy, msgattrib option: msgattrib Invocation. - (line 91) -* --help, autopoint option: autopoint Invocation. - (line 33) -* --help, envsubst option: envsubst Invocation. (line 22) -* --help, gettext option: gettext Invocation. (line 32) -* --help, gettextize option: gettextize Invocation. - (line 77) -* --help, msgattrib option: msgattrib Invocation. - (line 181) -* --help, msgcat option: msgcat Invocation. (line 164) -* --help, msgcmp option: msgcmp Invocation. (line 72) -* --help, msgcomm option: msgcomm Invocation. (line 152) -* --help, msgconv option: msgconv Invocation. (line 128) -* --help, msgen option: msgen Invocation. (line 130) -* --help, msgexec option: msgexec Invocation. (line 69) -* --help, msgfilter option: msgfilter Invocation. - (line 189) -* --help, msgfmt option: msgfmt Invocation. (line 222) -* --help, msggrep option: msggrep Invocation. (line 204) -* --help, msginit option: msginit Invocation. (line 99) -* --help, msgmerge option: msgmerge Invocation. (line 200) -* --help, msgunfmt option: msgunfmt Invocation. (line 162) -* --help, msguniq option: msguniq Invocation. (line 146) -* --help, ngettext option: ngettext Invocation. (line 31) -* --help, xgettext option: xgettext Invocation. (line 415) -* --ignore-case, msggrep option: msggrep Invocation. (line 117) -* --ignore-file, msgattrib option: msgattrib Invocation. - (line 87) -* --indent, msgattrib option: msgattrib Invocation. - (line 129) -* --indent, msgcat option: msgcat Invocation. (line 112) -* --indent, msgcomm option: msgcomm Invocation. (line 97) -* --indent, msgconv option: msgconv Invocation. (line 77) -* --indent, msgen option: msgen Invocation. (line 79) -* --indent, msgfilter option: msgfilter Invocation. - (line 133) -* --indent, msggrep option: msggrep Invocation. (line 155) -* --indent, msgmerge option: msgmerge Invocation. (line 149) -* --indent, msgunfmt option: msgunfmt Invocation. (line 121) -* --indent, msguniq option: msguniq Invocation. (line 94) -* --indent, xgettext option: xgettext Invocation. (line 288) -* --input, msgexec option: msgexec Invocation. (line 40) -* --input, msgfilter option: msgfilter Invocation. - (line 23) -* --input, msginit option: msginit Invocation. (line 16) -* --intl, gettextize option: gettextize Invocation. - (line 43) -* --invert-match, msggrep option: msggrep Invocation. (line 121) -* --java, msgfmt option: msgfmt Invocation. (line 30) -* --java, msgunfmt option: msgunfmt Invocation. (line 16) -* --java2, msgfmt option: msgfmt Invocation. (line 33) -* --join-existing, xgettext option: xgettext Invocation. (line 88) -* --kde, xgettext option: xgettext Invocation. (line 250) -* --keep-header, msgfilter option: msgfilter Invocation. - (line 136) -* --keyword, xgettext option: xgettext Invocation. (line 115) -* --lang, msgcat option <1>: msgen Invocation. (line 60) -* --lang, msgcat option <2>: msgcat Invocation. (line 94) -* --lang, msgcat option: msgmerge Invocation. (line 129) -* --language, xgettext option: xgettext Invocation. (line 56) -* --less-than, msgcat option: msgcat Invocation. (line 55) -* --less-than, msgcomm option: msgcomm Invocation. (line 53) -* --locale, msgfmt option: msgfmt Invocation. (line 79) -* --locale, msginit option: msginit Invocation. (line 52) -* --locale, msgunfmt option: msgunfmt Invocation. (line 47) -* --location, msggrep option: msggrep Invocation. (line 72) -* --more-than, msgcat option: msgcat Invocation. (line 60) -* --more-than, msgcomm option: msgcomm Invocation. (line 58) -* --msgctxt, msggrep option: msggrep Invocation. (line 81) -* --msgid, msggrep option: msggrep Invocation. (line 85) -* --msgid-bugs-address, xgettext option: xgettext Invocation. (line 375) -* --msgstr, msggrep option: msggrep Invocation. (line 89) -* --msgstr-prefix, xgettext option: xgettext Invocation. (line 403) -* --msgstr-suffix, xgettext option: xgettext Invocation. (line 407) -* --multi-domain, msgcmp option: msgcmp Invocation. (line 36) -* --multi-domain, msgmerge option: msgmerge Invocation. (line 101) -* --no-changelog, gettextize option: gettextize Invocation. - (line 58) -* --no-fuzzy, msgattrib option: msgattrib Invocation. - (line 47) -* --no-fuzzy-matching, msgcmp option: msgcmp Invocation. (line 40) -* --no-fuzzy-matching, msgmerge option: msgmerge Invocation. (line 105) -* --no-hash, msgfmt option: msgfmt Invocation. (line 212) -* --no-location, msgattrib option: msgattrib Invocation. - (line 132) -* --no-location, msgcat option: msgcat Invocation. (line 115) -* --no-location, msgcomm option: msgcomm Invocation. (line 100) -* --no-location, msgconv option: msgconv Invocation. (line 80) -* --no-location, msgen option: msgen Invocation. (line 82) -* --no-location, msgfilter option: msgfilter Invocation. - (line 141) -* --no-location, msggrep option: msggrep Invocation. (line 158) -* --no-location, msgmerge option: msgmerge Invocation. (line 152) -* --no-location, msguniq option: msguniq Invocation. (line 97) -* --no-location, xgettext option: xgettext Invocation. (line 291) -* --no-obsolete, msgattrib option: msgattrib Invocation. - (line 53) -* --no-translator, msginit option: msginit Invocation. (line 58) -* --no-wrap, msgattrib option: msgattrib Invocation. - (line 161) -* --no-wrap, msgcat option: msgcat Invocation. (line 144) -* --no-wrap, msgcomm option: msgcomm Invocation. (line 129) -* --no-wrap, msgconv option: msgconv Invocation. (line 108) -* --no-wrap, msgen option: msgen Invocation. (line 110) -* --no-wrap, msgfilter option: msgfilter Invocation. - (line 169) -* --no-wrap, msggrep option: msggrep Invocation. (line 186) -* --no-wrap, msginit option: msginit Invocation. (line 88) -* --no-wrap, msgmerge option: msgmerge Invocation. (line 180) -* --no-wrap, msgunfmt option: msgunfmt Invocation. (line 146) -* --no-wrap, msguniq option: msguniq Invocation. (line 126) -* --no-wrap, xgettext option: xgettext Invocation. (line 321) -* --obsolete, msgattrib option: msgattrib Invocation. - (line 95) -* --omit-header, msgcomm option: msgcomm Invocation. (line 144) -* --omit-header, xgettext option: xgettext Invocation. (line 336) -* --only-file, msgattrib option: msgattrib Invocation. - (line 83) -* --only-fuzzy, msgattrib option: msgattrib Invocation. - (line 50) -* --only-obsolete, msgattrib option: msgattrib Invocation. - (line 56) -* --output, xgettext option: xgettext Invocation. (line 40) -* --output-dir, xgettext option: xgettext Invocation. (line 45) -* --output-file, msgattrib option: msgattrib Invocation. - (line 31) -* --output-file, msgcat option: msgcat Invocation. (line 44) -* --output-file, msgcomm option: msgcomm Invocation. (line 42) -* --output-file, msgconv option: msgconv Invocation. (line 31) -* --output-file, msgen option: msgen Invocation. (line 37) -* --output-file, msgfilter option: msgfilter Invocation. - (line 39) -* --output-file, msgfmt option: msgfmt Invocation. (line 54) -* --output-file, msggrep option: msggrep Invocation. (line 31) -* --output-file, msginit option: msginit Invocation. (line 27) -* --output-file, msgmerge option: msgmerge Invocation. (line 53) -* --output-file, msgunfmt option: msgunfmt Invocation. (line 98) -* --output-file, msguniq option: msguniq Invocation. (line 38) -* --package-name, xgettext option: xgettext Invocation. (line 368) -* --package-version, xgettext option: xgettext Invocation. (line 371) -* --po-dir, gettextize option: gettextize Invocation. - (line 51) -* --previous, msgmerge option: msgmerge Invocation. (line 109) -* --properties-input, msgattrib option: msgattrib Invocation. - (line 104) -* --properties-input, msgcat option: msgcat Invocation. (line 74) -* --properties-input, msgcmp option: msgcmp Invocation. (line 59) -* --properties-input, msgcomm option: msgcomm Invocation. (line 72) -* --properties-input, msgconv option: msgconv Invocation. (line 52) -* --properties-input, msgen option: msgen Invocation. (line 48) -* --properties-input, msgexec option: msgexec Invocation. (line 56) -* --properties-input, msgfilter option: msgfilter Invocation. - (line 109) -* --properties-input, msgfmt option: msgfmt Invocation. (line 133) -* --properties-input, msggrep option: msggrep Invocation. (line 131) -* --properties-input, msginit option: msginit Invocation. (line 39) -* --properties-input, msgmerge option: msgmerge Invocation. (line 117) -* --properties-input, msguniq option: msguniq Invocation. (line 61) -* --properties-output, msgattrib option: msgattrib Invocation. - (line 145) -* --properties-output, msgcat option: msgcat Invocation. (line 128) -* --properties-output, msgcomm option: msgcomm Invocation. (line 113) -* --properties-output, msgconv option: msgconv Invocation. (line 92) -* --properties-output, msgen option: msgen Invocation. (line 94) -* --properties-output, msgfilter option: msgfilter Invocation. - (line 153) -* --properties-output, msggrep option: msggrep Invocation. (line 170) -* --properties-output, msginit option: msginit Invocation. (line 72) -* --properties-output, msgmerge option: msgmerge Invocation. (line 164) -* --properties-output, msgunfmt option: msgunfmt Invocation. (line 130) -* --properties-output, msguniq option: msguniq Invocation. (line 110) -* --properties-output, xgettext option: xgettext Invocation. (line 305) -* --qt, msgfmt option: msgfmt Invocation. (line 46) -* --qt, xgettext option: xgettext Invocation. (line 246) -* --quiet, msgfilter option: msgfilter Invocation. - (line 86) -* --quiet, msgmerge option: msgmerge Invocation. (line 213) -* --regexp=, msggrep option: msggrep Invocation. (line 109) -* --repeated, msguniq option: msguniq Invocation. (line 49) -* --resource, msgfmt option: msgfmt Invocation. (line 75) -* --resource, msgunfmt option: msgunfmt Invocation. (line 43) -* --set-fuzzy, msgattrib option: msgattrib Invocation. - (line 68) -* --set-obsolete, msgattrib option: msgattrib Invocation. - (line 74) -* --silent, msgfilter option: msgfilter Invocation. - (line 86) -* --silent, msgmerge option: msgmerge Invocation. (line 213) -* --sort-by-file, msgattrib option: msgattrib Invocation. - (line 173) -* --sort-by-file, msgcat option: msgcat Invocation. (line 156) -* --sort-by-file, msgcomm option: msgcomm Invocation. (line 141) -* --sort-by-file, msgconv option: msgconv Invocation. (line 120) -* --sort-by-file, msgen option: msgen Invocation. (line 122) -* --sort-by-file, msgfilter option: msgfilter Invocation. - (line 181) -* --sort-by-file, msggrep option: msggrep Invocation. (line 196) -* --sort-by-file, msgmerge option: msgmerge Invocation. (line 192) -* --sort-by-file, msguniq option: msguniq Invocation. (line 138) -* --sort-by-file, xgettext option: xgettext Invocation. (line 333) -* --sort-output, msgattrib option: msgattrib Invocation. - (line 168) -* --sort-output, msgcat option: msgcat Invocation. (line 151) -* --sort-output, msgcomm option: msgcomm Invocation. (line 136) -* --sort-output, msgconv option: msgconv Invocation. (line 115) -* --sort-output, msgen option: msgen Invocation. (line 117) -* --sort-output, msgfilter option: msgfilter Invocation. - (line 176) -* --sort-output, msggrep option: msggrep Invocation. (line 192) -* --sort-output, msgmerge option: msgmerge Invocation. (line 187) -* --sort-output, msgunfmt option: msgunfmt Invocation. (line 153) -* --sort-output, msguniq option: msguniq Invocation. (line 133) -* --sort-output, xgettext option: xgettext Invocation. (line 328) -* --statistics, msgfmt option: msgfmt Invocation. (line 229) -* --strict, msgattrib option: msgattrib Invocation. - (line 139) -* --strict, msgcat option: msgcat Invocation. (line 122) -* --strict, msgcomm option: msgcomm Invocation. (line 107) -* --strict, msgconv option: msgconv Invocation. (line 86) -* --strict, msgen option: msgen Invocation. (line 88) -* --strict, msgfilter option: msgfilter Invocation. - (line 147) -* --strict, msgfmt option: msgfmt Invocation. (line 57) -* --strict, msggrep option: msggrep Invocation. (line 164) -* --strict, msgmerge option: msgmerge Invocation. (line 158) -* --strict, msgunfmt option: msgunfmt Invocation. (line 124) -* --strict, msguniq option: msguniq Invocation. (line 104) -* --strict, xgettext option: xgettext Invocation. (line 300) -* --stringtable-input, msgattrib option: msgattrib Invocation. - (line 108) -* --stringtable-input, msgcat option: msgcat Invocation. (line 78) -* --stringtable-input, msgcmp option: msgcmp Invocation. (line 63) -* --stringtable-input, msgcomm option: msgcomm Invocation. (line 76) -* --stringtable-input, msgen option: msgen Invocation. (line 52) -* --stringtable-input, msgexec option: msgexec Invocation. (line 60) -* --stringtable-input, msgfilter option: msgfilter Invocation. - (line 113) -* --stringtable-input, msgfmt option: msgfmt Invocation. (line 137) -* --stringtable-input, msggrep option: msggrep Invocation. (line 135) -* --stringtable-input, msginit option: msginit Invocation. (line 43) -* --stringtable-input, msgmerge option: msgmerge Invocation. (line 121) -* --stringtable-input, msgonv option: msgconv Invocation. (line 56) -* --stringtable-input, msguniq option: msguniq Invocation. (line 65) -* --stringtable-output, msgattrib option: msgattrib Invocation. - (line 150) -* --stringtable-output, msgcat option: msgcat Invocation. (line 133) -* --stringtable-output, msgcomm option: msgcomm Invocation. (line 118) -* --stringtable-output, msgconv option: msgconv Invocation. (line 97) -* --stringtable-output, msgen option: msgen Invocation. (line 99) -* --stringtable-output, msgfilter option: msgfilter Invocation. - (line 158) -* --stringtable-output, msggrep option: msggrep Invocation. (line 175) -* --stringtable-output, msginit option: msginit Invocation. (line 77) -* --stringtable-output, msgmerge option: msgmerge Invocation. (line 169) -* --stringtable-output, msgunfmt option: msgunfmt Invocation. (line 135) -* --stringtable-output, msguniq option: msguniq Invocation. (line 115) -* --stringtable-output, xgettext option: xgettext Invocation. (line 310) -* --style, msgattrib option: msgattrib Invocation. - (line 121) -* --style, msgcat option <1>: The --style option. (line 6) -* --style, msgcat option: msgcat Invocation. (line 104) -* --style, msgcomm option: msgcomm Invocation. (line 89) -* --style, msgconv option: msgconv Invocation. (line 69) -* --style, msgen option: msgen Invocation. (line 71) -* --style, msgfilter option: msgfilter Invocation. - (line 126) -* --style, msggrep option: msggrep Invocation. (line 148) -* --style, msginit option: msginit Invocation. (line 67) -* --style, msgmerge option: msgmerge Invocation. (line 141) -* --style, msgunfmt option: msgunfmt Invocation. (line 113) -* --style, msguniq option: msguniq Invocation. (line 86) -* --style, xgettext option: xgettext Invocation. (line 280) -* --suffix, msgmerge option: msgmerge Invocation. (line 68) -* --symlink, gettextize option: gettextize Invocation. - (line 63) -* --tcl, msgfmt option: msgfmt Invocation. (line 43) -* --tcl, msgunfmt option: msgunfmt Invocation. (line 26) -* --to-code, msgcat option: msgcat Invocation. (line 87) -* --to-code, msgconv option: msgconv Invocation. (line 42) -* --to-code, msguniq option: msguniq Invocation. (line 74) -* --translated, msgattrib option: msgattrib Invocation. - (line 41) -* --trigraphs, xgettext option: xgettext Invocation. (line 241) -* --unique, msgcat option: msgcat Invocation. (line 65) -* --unique, msgcomm option: msgcomm Invocation. (line 63) -* --unique, msguniq option: msguniq Invocation. (line 53) -* --untranslated, msgattrib option: msgattrib Invocation. - (line 44) -* --update, msgmerge option: msgmerge Invocation. (line 45) -* --use-first, msgcat option: msgcat Invocation. (line 90) -* --use-first, msguniq option: msguniq Invocation. (line 77) -* --use-fuzzy, msgcmp option: msgcmp Invocation. (line 44) -* --use-fuzzy, msgfmt option: msgfmt Invocation. (line 199) -* --use-untranslated, msgcmp option: msgcmp Invocation. (line 50) -* --variables, envsubst option: envsubst Invocation. (line 15) -* --verbose, msgfmt option: msgfmt Invocation. (line 235) -* --verbose, msgmerge option: msgmerge Invocation. (line 208) -* --verbose, msgunfmt option: msgunfmt Invocation. (line 170) -* --version, autopoint option: autopoint Invocation. - (line 36) -* --version, envsubst option: envsubst Invocation. (line 26) -* --version, gettext option: gettext Invocation. (line 40) -* --version, gettextize option: gettextize Invocation. - (line 80) -* --version, msgattrib option: msgattrib Invocation. - (line 185) -* --version, msgcat option: msgcat Invocation. (line 168) -* --version, msgcmp option: msgcmp Invocation. (line 76) -* --version, msgcomm option: msgcomm Invocation. (line 156) -* --version, msgconv option: msgconv Invocation. (line 132) -* --version, msgen option: msgen Invocation. (line 134) -* --version, msgexec option: msgexec Invocation. (line 73) -* --version, msgfilter option: msgfilter Invocation. - (line 193) -* --version, msgfmt option: msgfmt Invocation. (line 226) -* --version, msggrep option: msggrep Invocation. (line 208) -* --version, msginit option: msginit Invocation. (line 103) -* --version, msgmerge option: msgmerge Invocation. (line 204) -* --version, msgunfmt option: msgunfmt Invocation. (line 166) -* --version, msguniq option: msguniq Invocation. (line 150) -* --version, ngettext option: ngettext Invocation. (line 35) -* --version, xgettext option: xgettext Invocation. (line 419) -* --width, msgattrib option: msgattrib Invocation. - (line 155) -* --width, msgcat option: msgcat Invocation. (line 138) -* --width, msgcomm option: msgcomm Invocation. (line 123) -* --width, msgconv option: msgconv Invocation. (line 102) -* --width, msgen option: msgen Invocation. (line 104) -* --width, msgfilter option: msgfilter Invocation. - (line 163) -* --width, msggrep option: msggrep Invocation. (line 180) -* --width, msginit option: msginit Invocation. (line 82) -* --width, msgmerge option: msgmerge Invocation. (line 174) -* --width, msgunfmt option: msgunfmt Invocation. (line 140) -* --width, msguniq option: msguniq Invocation. (line 120) -* --width, xgettext option: xgettext Invocation. (line 315) -* -<, msgcat option: msgcat Invocation. (line 55) -* -<, msgcomm option: msgcomm Invocation. (line 53) -* ->, msgcat option: msgcat Invocation. (line 60) -* ->, msgcomm option: msgcomm Invocation. (line 58) -* -a, msgfmt option: msgfmt Invocation. (line 209) -* -a, xgettext option: xgettext Invocation. (line 107) -* -C, msgfmt option: msgfmt Invocation. (line 183) -* -c, msgfmt option: msgfmt Invocation. (line 146) -* -C, msggrep option: msggrep Invocation. (line 93) -* -C, msgmerge option: msgmerge Invocation. (line 36) -* -c, xgettext option: xgettext Invocation. (line 97) -* -C, xgettext option: xgettext Invocation. (line 64) -* -d, autopoint option: autopoint Invocation. - (line 24) -* -d, gettext option: gettext Invocation. (line 16) -* -d, gettextize option: gettextize Invocation. - (line 72) -* -D, msgattrib option: msgattrib Invocation. - (line 19) -* -D, msgcat option: msgcat Invocation. (line 32) -* -D, msgcmp option: msgcmp Invocation. (line 27) -* -D, msgcomm option: msgcomm Invocation. (line 30) -* -D, msgconv option: msgconv Invocation. (line 19) -* -D, msgen option: msgen Invocation. (line 25) -* -D, msgexec option: msgexec Invocation. (line 44) -* -D, msgfilter option: msgfilter Invocation. - (line 27) -* -d, msgfmt option: msgfmt Invocation. (line 84) -* -D, msgfmt option: msgfmt Invocation. (line 18) -* -D, msggrep option: msggrep Invocation. (line 19) -* -D, msgmerge option: msgmerge Invocation. (line 30) -* -d, msgunfmt option: msgunfmt Invocation. (line 70) -* -d, msguniq option: msguniq Invocation. (line 49) -* -D, msguniq option: msguniq Invocation. (line 26) -* -d, ngettext option: ngettext Invocation. (line 15) -* -d, xgettext option: xgettext Invocation. (line 36) -* -D, xgettext option: xgettext Invocation. (line 24) -* -E, gettext option: gettext Invocation. (line 27) -* -e, gettext option: gettext Invocation. (line 20) -* -e, msgfilter option: msgfilter Invocation. - (line 77) -* -e, msggrep option: msggrep Invocation. (line 109) -* -E, msggrep option: msggrep Invocation. (line 101) -* -E, ngettext option: ngettext Invocation. (line 26) -* -e, ngettext option: ngettext Invocation. (line 19) -* -f, autopoint option: autopoint Invocation. - (line 20) -* -f, gettextize option: gettextize Invocation. - (line 40) -* -F, msgattrib option: msgattrib Invocation. - (line 173) -* -F, msgcat option: msgcat Invocation. (line 156) -* -f, msgcat option: msgcat Invocation. (line 27) -* -F, msgcomm option: msgcomm Invocation. (line 141) -* -f, msgcomm option: msgcomm Invocation. (line 25) -* -F, msgconv option: msgconv Invocation. (line 120) -* -F, msgen option: msgen Invocation. (line 122) -* -F, msgfilter option: msgfilter Invocation. - (line 181) -* -f, msgfilter option: msgfilter Invocation. - (line 81) -* -f, msgfmt option: msgfmt Invocation. (line 199) -* -f, msggrep option: msggrep Invocation. (line 113) -* -F, msggrep option: msggrep Invocation. (line 105) -* -F, msgmerge option: msgmerge Invocation. (line 192) -* -F, msguniq option: msguniq Invocation. (line 138) -* -F, xgettext option: xgettext Invocation. (line 333) -* -f, xgettext option: xgettext Invocation. (line 19) -* -h, envsubst option: envsubst Invocation. (line 22) -* -h, gettext option: gettext Invocation. (line 32) -* -h, msgattrib option: msgattrib Invocation. - (line 181) -* -h, msgcat option: msgcat Invocation. (line 164) -* -h, msgcmp option: msgcmp Invocation. (line 72) -* -h, msgcomm option: msgcomm Invocation. (line 152) -* -h, msgconv option: msgconv Invocation. (line 128) -* -h, msgen option: msgen Invocation. (line 130) -* -h, msgexec option: msgexec Invocation. (line 69) -* -h, msgfilter option: msgfilter Invocation. - (line 189) -* -h, msgfmt option: msgfmt Invocation. (line 222) -* -h, msggrep option: msggrep Invocation. (line 204) -* -h, msginit option: msginit Invocation. (line 99) -* -h, msgmerge option: msgmerge Invocation. (line 200) -* -h, msgunfmt option: msgunfmt Invocation. (line 162) -* -h, msguniq option: msguniq Invocation. (line 146) -* -h, ngettext option: ngettext Invocation. (line 31) -* -h, xgettext option: xgettext Invocation. (line 415) -* -i, msgattrib option: msgattrib Invocation. - (line 129) -* -i, msgcat option: msgcat Invocation. (line 112) -* -i, msgcomm option: msgcomm Invocation. (line 97) -* -i, msgconv option: msgconv Invocation. (line 77) -* -i, msgen option: msgen Invocation. (line 79) -* -i, msgexec option: msgexec Invocation. (line 40) -* -i, msgfilter option: msgfilter Invocation. - (line 23) -* -i, msggrep option: msggrep Invocation. (line 117) -* -i, msginit option: msginit Invocation. (line 16) -* -i, msgmerge option: msgmerge Invocation. (line 149) -* -i, msgunfmt option: msgunfmt Invocation. (line 121) -* -i, msguniq option: msguniq Invocation. (line 94) -* -i, xgettext option: xgettext Invocation. (line 288) -* -j, msgfmt option: msgfmt Invocation. (line 30) -* -J, msggrep option: msggrep Invocation. (line 81) -* -j, msgunfmt option: msgunfmt Invocation. (line 16) -* -j, xgettext option: xgettext Invocation. (line 88) -* -K, msggrep option: msggrep Invocation. (line 85) -* -k, xgettext option: xgettext Invocation. (line 115) -* -l, msgfmt option: msgfmt Invocation. (line 79) -* -l, msginit option: msginit Invocation. (line 52) -* -l, msgunfmt option: msgunfmt Invocation. (line 47) -* -L, xgettext option: xgettext Invocation. (line 56) -* -m, msgcmp option: msgcmp Invocation. (line 36) -* -M, msggrep option: msggrep Invocation. (line 77) -* -m, msgmerge option: msgmerge Invocation. (line 101) -* -M, xgettext option: xgettext Invocation. (line 407) -* -m, xgettext option: xgettext Invocation. (line 403) -* -n, gettext option: gettext Invocation. (line 35) -* -n, msgattrib option: msgattrib Invocation. - (line 136) -* -n, msgcat option: msgcat Invocation. (line 119) -* -N, msgcmp option: msgcmp Invocation. (line 40) -* -n, msgcomm option: msgcomm Invocation. (line 104) -* -n, msgfilter option: msgfilter Invocation. - (line 86) -* -N, msggrep option: msggrep Invocation. (line 72) -* -N, msgmerge option: msgmerge Invocation. (line 105) -* -n, msguniq option: msguniq Invocation. (line 101) -* -n, xgettext option: xgettext Invocation. (line 297) -* -o, msgattrib option: msgattrib Invocation. - (line 31) -* -o, msgcat option: msgcat Invocation. (line 44) -* -o, msgcomm option: msgcomm Invocation. (line 42) -* -o, msgconv option: msgconv Invocation. (line 31) -* -o, msgen option: msgen Invocation. (line 37) -* -o, msgfilter option: msgfilter Invocation. - (line 39) -* -o, msgfmt option: msgfmt Invocation. (line 54) -* -o, msggrep option: msggrep Invocation. (line 31) -* -o, msginit option: msginit Invocation. (line 27) -* -o, msgmerge option: msgmerge Invocation. (line 53) -* -o, msgunfmt option: msgunfmt Invocation. (line 98) -* -o, msguniq option: msguniq Invocation. (line 38) -* -o, xgettext option: xgettext Invocation. (line 40) -* -p, msgattrib option: msgattrib Invocation. - (line 145) -* -P, msgattrib option: msgattrib Invocation. - (line 104) -* -p, msgcat option: msgcat Invocation. (line 128) -* -P, msgcat option: msgcat Invocation. (line 74) -* -P, msgcmp option: msgcmp Invocation. (line 59) -* -p, msgcomm option: msgcomm Invocation. (line 113) -* -P, msgcomm option: msgcomm Invocation. (line 72) -* -p, msgconv option: msgconv Invocation. (line 92) -* -P, msgconv option: msgconv Invocation. (line 52) -* -p, msgen option: msgen Invocation. (line 94) -* -P, msgen option: msgen Invocation. (line 48) -* -P, msgexec option: msgexec Invocation. (line 56) -* -p, msgfilter option: msgfilter Invocation. - (line 153) -* -P, msgfilter option: msgfilter Invocation. - (line 109) -* -P, msgfmt option: msgfmt Invocation. (line 133) -* -p, msggrep option: msggrep Invocation. (line 170) -* -P, msggrep option: msggrep Invocation. (line 131) -* -p, msginit option: msginit Invocation. (line 72) -* -P, msginit option: msginit Invocation. (line 39) -* -p, msgmerge option: msgmerge Invocation. (line 164) -* -P, msgmerge option: msgmerge Invocation. (line 117) -* -p, msgunfmt option: msgunfmt Invocation. (line 130) -* -p, msguniq option: msguniq Invocation. (line 110) -* -P, msguniq option: msguniq Invocation. (line 61) -* -p, xgettext option: xgettext Invocation. (line 45) -* -q, msgmerge option: msgmerge Invocation. (line 213) -* -r, msgfmt option: msgfmt Invocation. (line 75) -* -r, msgunfmt option: msgunfmt Invocation. (line 43) -* -s, msgattrib option: msgattrib Invocation. - (line 168) -* -s, msgcat option: msgcat Invocation. (line 151) -* -s, msgcomm option: msgcomm Invocation. (line 136) -* -s, msgconv option: msgconv Invocation. (line 115) -* -s, msgen option: msgen Invocation. (line 117) -* -s, msgfilter option: msgfilter Invocation. - (line 176) -* -s, msgmerge option: msgmerge Invocation. (line 187) -* -s, msgunfmt option: msgunfmt Invocation. (line 153) -* -s, msguniq option: msguniq Invocation. (line 133) -* -s, xgettext option: xgettext Invocation. (line 328) -* -t, msgcat option: msgcat Invocation. (line 87) -* -t, msgconv option: msgconv Invocation. (line 42) -* -T, msggrep option: msggrep Invocation. (line 89) -* -t, msguniq option: msguniq Invocation. (line 74) -* -T, xgettext option: xgettext Invocation. (line 241) -* -u, msgcat option: msgcat Invocation. (line 65) -* -u, msgcomm option: msgcomm Invocation. (line 63) -* -U, msgmerge option: msgmerge Invocation. (line 45) -* -u, msguniq option: msguniq Invocation. (line 53) -* -V, envsubst option: envsubst Invocation. (line 26) -* -v, envsubst option: envsubst Invocation. (line 15) -* -V, gettext option: gettext Invocation. (line 40) -* -V, msgattrib option: msgattrib Invocation. - (line 185) -* -V, msgcat option: msgcat Invocation. (line 168) -* -V, msgcmp option: msgcmp Invocation. (line 76) -* -V, msgcomm option: msgcomm Invocation. (line 156) -* -V, msgconv option: msgconv Invocation. (line 132) -* -V, msgen option: msgen Invocation. (line 134) -* -V, msgexec option: msgexec Invocation. (line 73) -* -V, msgfilter option: msgfilter Invocation. - (line 193) -* -v, msgfmt option: msgfmt Invocation. (line 235) -* -V, msgfmt option: msgfmt Invocation. (line 226) -* -V, msggrep option: msggrep Invocation. (line 208) -* -v, msggrep option: msggrep Invocation. (line 121) -* -V, msginit option: msginit Invocation. (line 103) -* -v, msgmerge option: msgmerge Invocation. (line 208) -* -V, msgmerge option: msgmerge Invocation. (line 204) -* -v, msgunfmt option: msgunfmt Invocation. (line 170) -* -V, msgunfmt option: msgunfmt Invocation. (line 166) -* -V, msguniq option: msguniq Invocation. (line 150) -* -V, ngettext option: ngettext Invocation. (line 35) -* -V, xgettext option: xgettext Invocation. (line 419) -* -w, msgattrib option: msgattrib Invocation. - (line 155) -* -w, msgcat option: msgcat Invocation. (line 138) -* -w, msgcomm option: msgcomm Invocation. (line 123) -* -w, msgconv option: msgconv Invocation. (line 102) -* -w, msgen option: msgen Invocation. (line 104) -* -w, msgfilter option: msgfilter Invocation. - (line 163) -* -w, msggrep option: msggrep Invocation. (line 180) -* -w, msginit option: msginit Invocation. (line 82) -* -w, msgmerge option: msgmerge Invocation. (line 174) -* -w, msgunfmt option: msgunfmt Invocation. (line 140) -* -w, msguniq option: msguniq Invocation. (line 120) -* -w, xgettext option: xgettext Invocation. (line 315) -* -X, msggrep option: msggrep Invocation. (line 97) -* -x, xgettext option: xgettext Invocation. (line 92) - - -File: gettext.info, Node: Variable Index, Next: PO Mode Index, Prev: Option Index, Up: Top - -Variable Index -************** - - -* Menu: - -* GETTEXT_LOG_UNTRANSLATED, environment variable: Prioritizing messages. - (line 23) -* LANG, environment variable <1>: gettext grok. (line 32) -* LANG, environment variable: Locale Environment Variables. - (line 17) -* LANGUAGE, environment variable <1>: po/Rules-*. (line 11) -* LANGUAGE, environment variable <2>: gettext grok. (line 28) -* LANGUAGE, environment variable: Locale Environment Variables. - (line 11) -* LC_ALL, environment variable <1>: gettext grok. (line 28) -* LC_ALL, environment variable: Locale Environment Variables. - (line 11) -* LC_COLLATE, environment variable <1>: gettext grok. (line 30) -* LC_COLLATE, environment variable: Locale Environment Variables. - (line 13) -* LC_CTYPE, environment variable <1>: gettext grok. (line 30) -* LC_CTYPE, environment variable: Locale Environment Variables. - (line 13) -* LC_MESSAGES, environment variable <1>: gettext grok. (line 30) -* LC_MESSAGES, environment variable: Locale Environment Variables. - (line 13) -* LC_MONETARY, environment variable <1>: gettext grok. (line 30) -* LC_MONETARY, environment variable: Locale Environment Variables. - (line 13) -* LC_NUMERIC, environment variable <1>: gettext grok. (line 30) -* LC_NUMERIC, environment variable: Locale Environment Variables. - (line 13) -* LC_TIME, environment variable <1>: gettext grok. (line 30) -* LC_TIME, environment variable: Locale Environment Variables. - (line 13) -* LINGUAS, environment variable: Installers. (line 17) -* MSGEXEC_LOCATION, environment variable: msgexec Invocation. (line 18) -* MSGEXEC_MSGCTXT, environment variable: msgexec Invocation. (line 18) -* MSGEXEC_MSGID, environment variable: msgexec Invocation. (line 18) -* MSGFILTER_LOCATION, environment variable: msgfilter Invocation. - (line 11) -* MSGFILTER_MSGCTXT, environment variable: msgfilter Invocation. - (line 11) -* MSGFILTER_MSGID, environment variable: msgfilter Invocation. (line 11) -* PO_STYLE, environment variable: The --style option. (line 10) -* TERM, environment variable: The TERM variable. (line 6) -* TEXTDOMAIN, environment variable: sh. (line 23) -* TEXTDOMAINDIR, environment variable: sh. (line 26) - - -File: gettext.info, Node: PO Mode Index, Next: Autoconf Macro Index, Prev: Variable Index, Up: Top - -PO Mode Index -************* - - -* Menu: - -* #, PO Mode command: Modifying Comments. (line 24) -* ,, PO Mode command: Marking. (line 44) -* ., PO Mode command: Entry Positioning. (line 20) -* .emacs customizations: Installation. (line 13) -* 0, PO Mode command: Main PO Commands. (line 40) -* <, PO Mode command: Entry Positioning. (line 29) -* =, PO Mode command: Main PO Commands. (line 47) -* >, PO Mode command: Entry Positioning. (line 32) -* ?, PO Mode command: Main PO Commands. (line 44) -* _, PO Mode command: Main PO Commands. (line 30) -* a, PO Mode command: Auxiliary. (line 40) -* A, PO Mode command: Auxiliary. (line 28) -* a, PO Mode command: Auxiliary. (line 21) -* auxiliary PO file: Auxiliary. (line 13) -* C-c C-a, PO Mode command <1>: Auxiliary. (line 25) -* C-c C-a, PO Mode command: Subedit. (line 17) -* C-c C-c, PO Mode command: Subedit. (line 11) -* C-c C-k, PO Mode command: Subedit. (line 14) -* C-j, PO Mode command: Modifying Translations. - (line 26) -* commands: Main PO Commands. (line 6) -* comment out PO file entry: Obsolete Entries. (line 47) -* consulting program sources: C Sources Context. (line 6) -* consulting translations to other languages: Auxiliary. (line 6) -* current entry of a PO file: Entry Positioning. (line 6) -* cut and paste for translated strings: Modifying Translations. - (line 74) -* DEL, PO Mode command <1>: Obsolete Entries. (line 32) -* DEL, PO Mode command: Fuzzy Entries. (line 60) -* editing comments: Modifying Comments. (line 6) -* editing multiple entries: Subedit. (line 62) -* editing translations: Modifying Translations. - (line 6) -* etags, using for marking strings: Marking. (line 17) -* exiting PO subedit: Subedit. (line 20) -* F, PO Mode command: Fuzzy Entries. (line 39) -* f, PO Mode command: Fuzzy Entries. (line 39) -* F, PO Mode command: Fuzzy Entries. (line 33) -* f, PO Mode command: Fuzzy Entries. (line 30) -* find source fragment for a PO file entry: C Sources Context. - (line 33) -* h, PO Mode command: Main PO Commands. (line 44) -* installing PO mode: Installation. (line 13) -* K, PO Mode command: Modifying Comments. (line 27) -* k, PO Mode command <1>: Modifying Translations. - (line 30) -* k, PO Mode command: Untranslated Entries. - (line 32) -* LFD, PO Mode command: Modifying Translations. - (line 26) -* looking at the source to aid translation: C Sources Context. - (line 6) -* m, PO Mode command: Entry Positioning. (line 35) -* M-,, PO Mode command: Marking. (line 48) -* M-., PO Mode command: Marking. (line 51) -* M-A, PO Mode command: Auxiliary. (line 32) -* M-S, PO Mode command: C Sources Context. (line 89) -* M-s, PO Mode command: C Sources Context. (line 53) -* M-S, PO Mode command: C Sources Context. (line 49) -* M-s, PO Mode command: C Sources Context. (line 41) -* marking strings for translation: Marking. (line 6) -* moving by fuzzy entries: Fuzzy Entries. (line 24) -* moving by obsolete entries: Obsolete Entries. (line 22) -* moving by translated entries: Translated Entries. (line 12) -* moving by untranslated entries: Untranslated Entries. - (line 18) -* moving through a PO file: Entry Positioning. (line 14) -* n, PO Mode command: Entry Positioning. (line 23) -* next-error, stepping through PO file validation results: Main PO Commands. - (line 99) -* normalize, PO Mode command: Auxiliary. (line 64) -* O, PO Mode command: Obsolete Entries. (line 36) -* o, PO Mode command: Obsolete Entries. (line 36) -* O, PO Mode command: Obsolete Entries. (line 29) -* o, PO Mode command: Obsolete Entries. (line 26) -* obsolete active entry: Obsolete Entries. (line 47) -* p, PO Mode command: Entry Positioning. (line 26) -* pending subedits: Subedit. (line 73) -* po-auto-edit-with-msgid, PO Mode variable: Modifying Translations. - (line 57) -* po-auto-fuzzy-on-edit, PO Mode variable: Translated Entries. - (line 28) -* po-auto-select-on-unfuzzy, PO Mode variable: Fuzzy Entries. (line 44) -* po-confirm-and-quit, PO Mode command: Main PO Commands. (line 62) -* po-consider-as-auxiliary, PO Mode command: Auxiliary. (line 36) -* po-consider-source-path, PO Mode command: C Sources Context. - (line 89) -* po-current-entry, PO Mode command: Entry Positioning. (line 46) -* po-cycle-auxiliary, PO Mode command: Auxiliary. (line 40) -* po-cycle-source-reference, PO Mode command: C Sources Context. - (line 53) -* po-edit-comment, PO Mode command: Modifying Comments. (line 46) -* po-edit-msgstr, PO Mode command: Modifying Translations. - (line 42) -* po-exchange-location, PO Mode command: Entry Positioning. (line 106) -* po-fade-out-entry, PO Mode command <1>: Obsolete Entries. (line 47) -* po-fade-out-entry, PO Mode command: Fuzzy Entries. (line 60) -* po-first-entry, PO Mode command: Entry Positioning. (line 74) -* po-help, PO Mode command: Main PO Commands. (line 83) -* po-ignore-as-auxiliary, PO Mode command: Auxiliary. (line 36) -* po-ignore-source-path, PO Mode command: C Sources Context. (line 89) -* po-kill-comment, PO Mode command: Modifying Comments. (line 60) -* po-kill-msgstr, PO Mode command <1>: Modifying Translations. - (line 74) -* po-kill-msgstr, PO Mode command: Untranslated Entries. - (line 40) -* po-kill-ring-save-comment, PO Mode command: Modifying Comments. - (line 60) -* po-kill-ring-save-msgstr, PO Mode command: Modifying Translations. - (line 74) -* po-last-entry, PO Mode command: Entry Positioning. (line 74) -* po-mark-translatable, PO Mode command: Marking. (line 98) -* po-msgid-to-msgstr, PO Mode command: Modifying Translations. - (line 52) -* po-next-entry, PO Mode command: Entry Positioning. (line 69) -* po-next-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 39) -* po-next-obsolete-entry, PO Mode command: Obsolete Entries. (line 36) -* po-next-translated-entry, PO Mode command: Translated Entries. - (line 23) -* po-next-untranslated-entry, PO Mode command: Untranslated Entries. - (line 35) -* po-normalize, PO Mode command: Normalizing. (line 31) -* po-other-window, PO Mode command: Main PO Commands. (line 72) -* po-pop-location, PO Mode command: Entry Positioning. (line 92) -* po-previous-entry, PO Mode command: Entry Positioning. (line 69) -* po-previous-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 39) -* po-previous-obsolete-entry, PO Mode command: Obsolete Entries. - (line 36) -* po-previous-translated-entry, PO Mode command: Translated Entries. - (line 23) -* po-previous-untransted-entry, PO Mode command: Untranslated Entries. - (line 35) -* po-push-location, PO Mode command: Entry Positioning. (line 92) -* po-quit, PO Mode command: Main PO Commands. (line 62) -* po-select-auxiliary, PO Mode command: Auxiliary. (line 49) -* po-select-mark-and-mark, PO Mode command: Marking. (line 98) -* po-select-source-reference, PO Mode command: C Sources Context. - (line 53) -* po-statistics, PO Mode command: Main PO Commands. (line 87) -* po-subedit-abort, PO Mode command: Subedit. (line 27) -* po-subedit-cycle-auxiliary, PO Mode command: Subedit. (line 35) -* po-subedit-exit, PO Mode command: Subedit. (line 20) -* po-subedit-mode-hook, PO Mode variable: Modifying Comments. (line 57) -* po-tags-search, PO Mode command: Marking. (line 56) -* po-undo, PO Mode command: Main PO Commands. (line 53) -* po-unfuzzy, PO Mode command: Fuzzy Entries. (line 44) -* po-validate, PO Mode command: Main PO Commands. (line 92) -* po-yank-comment, PO Mode command: Modifying Comments. (line 60) -* po-yank-msgstr, PO Mode command: Modifying Translations. - (line 98) -* q, PO Mode command: Main PO Commands. (line 62) -* Q, PO Mode command: Main PO Commands. (line 62) -* q, PO Mode command: Main PO Commands. (line 36) -* Q, PO Mode command: Main PO Commands. (line 33) -* r, PO Mode command: Entry Positioning. (line 39) -* RET, PO Mode command: Modifying Translations. - (line 22) -* S, PO Mode command: C Sources Context. (line 89) -* s, PO Mode command: C Sources Context. (line 53) -* S, PO Mode command: C Sources Context. (line 45) -* s, PO Mode command: C Sources Context. (line 37) -* starting a string translation: Modifying Translations. - (line 63) -* string normalization in entries: Normalizing. (line 30) -* subedit minor mode: Subedit. (line 6) -* T, PO Mode command: Translated Entries. (line 23) -* t, PO Mode command: Translated Entries. (line 23) -* T, PO Mode command: Translated Entries. (line 19) -* t, PO Mode command: Translated Entries. (line 16) -* TAB, PO Mode command: Fuzzy Entries. (line 36) -* TAGS, and marking translatable strings: Marking. (line 31) -* U, PO Mode command: Untranslated Entries. - (line 35) -* u, PO Mode command: Untranslated Entries. - (line 35) -* U, PO Mode command: Untranslated Entries. - (line 28) -* u, PO Mode command: Untranslated Entries. - (line 25) -* use the source, Luke: C Sources Context. (line 6) -* using obsolete translations to make new entries: Modifying Translations. - (line 124) -* using translation compendia: Compendium. (line 6) -* V, PO Mode command: Main PO Commands. (line 50) -* W, PO Mode command: Modifying Comments. (line 31) -* w, PO Mode command: Modifying Translations. - (line 34) -* x, PO Mode command: Entry Positioning. (line 42) -* Y, PO Mode command: Modifying Comments. (line 35) -* y, PO Mode command: Modifying Translations. - (line 38) - - -File: gettext.info, Node: Autoconf Macro Index, Next: Index, Prev: PO Mode Index, Up: Top - -Autoconf Macro Index -******************** - - -* Menu: - -* AM_GNU_GETTEXT: AM_GNU_GETTEXT. (line 6) -* AM_GNU_GETTEXT_INTL_SUBDIR: AM_GNU_GETTEXT_INTL_SUBDIR. - (line 6) -* AM_GNU_GETTEXT_NEED: AM_GNU_GETTEXT_NEED. (line 6) -* AM_GNU_GETTEXT_VERSION: AM_GNU_GETTEXT_VERSION. - (line 6) -* AM_ICONV: AM_ICONV. (line 6) -* AM_PO_SUBDIRS: AM_PO_SUBDIRS. (line 6) -* AM_XGETTEXT_OPTION: AM_XGETTEXT_OPTION. (line 6) - - -File: gettext.info, Node: Index, Prev: Autoconf Macro Index, Up: Top - -General Index -************* - - -* Menu: - -* _, a macro to mark strings for translation: Mark Keywords. (line 45) -* _nl_msg_cat_cntr: gettext grok. (line 62) -* ABOUT-NLS file: Installing Localizations. - (line 13) -* acconfig.h file: acconfig. (line 6) -* accumulating translations: Creating Compendia. (line 14) -* aclocal.m4 file: aclocal. (line 6) -* adding keywords, xgettext: xgettext Invocation. (line 119) -* ambiguities: Preparing Strings. (line 41) -* apply a filter to translations: msgfilter Invocation. - (line 8) -* apply command to all translations in a catalog: msgexec Invocation. - (line 8) -* Arabic digits: c-format. (line 28) -* attribute manipulation: msgattrib Invocation. - (line 8) -* attribute, fuzzy: Fuzzy Entries. (line 6) -* attributes of a PO file entry: Fuzzy Entries. (line 6) -* attributes, manipulating: Manipulating. (line 56) -* autoconf macros for gettext: autoconf macros. (line 6) -* autopoint program, usage: autopoint Invocation. - (line 6) -* auxiliary PO file: Auxiliary. (line 13) -* available translations: Installing Localizations. - (line 6) -* awk: gawk. (line 6) -* awk-format flag: PO Files. (line 149) -* backup old file, and msgmerge program: msgmerge Invocation. (line 65) -* bash: bash. (line 6) -* bibliography: References. (line 6) -* big picture: Overview. (line 6) -* bind_textdomain_codeset: Charset conversion. (line 28) -* Boost format strings: xgettext Invocation. (line 254) -* boost-format flag: PO Files. (line 198) -* bug report address: Introduction. (line 24) -* C and C-like languages: C. (line 6) -* C trigraphs: xgettext Invocation. (line 241) -* C#: C#. (line 6) -* C# mode, and msgfmt program: msgfmt Invocation. (line 36) -* C# mode, and msgunfmt program: msgunfmt Invocation. (line 19) -* C# resources mode, and msgfmt program: msgfmt Invocation. (line 40) -* C# resources mode, and msgunfmt program: msgunfmt Invocation. - (line 23) -* C#, string concatenation: Preparing Strings. (line 168) -* c-format flag: PO Files. (line 90) -* c-format, and xgettext: c-format Flag. (line 48) -* catalog encoding and msgexec output: msgexec Invocation. (line 25) -* catclose, a catgets function: Interface to catgets. - (line 44) -* catgets, a catgets function: Interface to catgets. - (line 25) -* catgets, X/Open specification: catgets. (line 6) -* catopen, a catgets function: Interface to catgets. - (line 13) -* character encoding: Aspects. (line 67) -* charset conversion at runtime: Charset conversion. (line 6) -* charset of PO files: Header Entry. (line 106) -* check format strings: msgfmt Invocation. (line 150) -* checking of translations: Manipulating. (line 41) -* clisp: Common Lisp. (line 6) -* clisp C sources: clisp C. (line 6) -* codeset: Aspects. (line 67) -* comments in PO files: PO Files. (line 307) -* comments, automatic: PO Files. (line 36) -* comments, extracted: PO Files. (line 36) -* comments, translator: PO Files. (line 36) -* Common Lisp: Common Lisp. (line 6) -* compare PO files: msgcmp Invocation. (line 8) -* comparison of interfaces: Comparison. (line 6) -* compatibility with X/Open msgfmt: msgfmt Invocation. (line 183) -* compendium: Compendium. (line 6) -* compendium, creating: Creating Compendia. (line 6) -* concatenate PO files: msgcat Invocation. (line 8) -* concatenating PO files into a compendium: Creating Compendia. - (line 14) -* concatenation of strings: Preparing Strings. (line 117) -* config.h.in file: config.h.in. (line 6) -* context: Contexts. (line 6) -* context, argument specification in xgettext: xgettext Invocation. - (line 119) -* context, in MO files: MO Files. (line 71) -* context, in PO files: PO Files. (line 202) -* control characters: Preparing Strings. (line 190) -* convert binary message catalog into PO file: msgunfmt Invocation. - (line 8) -* convert translations to a different encoding: msgconv Invocation. - (line 8) -* converting a package to use gettext: Prerequisites. (line 6) -* country codes: Country Codes. (line 6) -* create new PO file: msginit Invocation. (line 8) -* creating a new PO file: Creating. (line 6) -* creating compendia: Creating Compendia. (line 6) -* csharp-format flag: PO Files. (line 145) -* currency symbols: Aspects. (line 79) -* date format: Aspects. (line 84) -* dcngettext: Plural forms. (line 161) -* dcpgettext: Contexts. (line 56) -* dcpgettext_expr: Contexts. (line 112) -* debugging messages marked as format strings: xgettext Invocation. - (line 258) -* dialect: Manipulating. (line 28) -* disabling NLS: lib/gettext.h. (line 6) -* distribution tarball: Release Management. (line 6) -* dngettext: Plural forms. (line 153) -* dollar substitution: envsubst Invocation. (line 8) -* domain ambiguities: Ambiguities. (line 6) -* dpgettext: Contexts. (line 56) -* dpgettext_expr: Contexts. (line 112) -* duplicate elimination: Manipulating. (line 45) -* duplicate removal: msguniq Invocation. (line 8) -* editing comments in PO files: Modifying Comments. (line 6) -* Editing PO Files: Editing. (line 6) -* editing translations: Modifying Translations. - (line 6) -* elisp-format flag: PO Files. (line 125) -* Emacs Lisp: Emacs Lisp. (line 6) -* Emacs PO Mode: PO Mode. (line 6) -* encoding: Aspects. (line 67) -* encoding conversion: Manipulating. (line 17) -* encoding conversion at runtime: Charset conversion. (line 6) -* encoding for your language: Header Entry. (line 135) -* encoding list: Header Entry. (line 119) -* encoding of PO files: Header Entry. (line 106) -* environment variables: envsubst Invocation. (line 8) -* envsubst program, usage: envsubst Invocation. (line 6) -* eval_gettext function, usage: eval_gettext Invocation. - (line 6) -* eval_ngettext function, usage: eval_ngettext Invocation. - (line 6) -* evolution of packages: Overview. (line 127) -* extracting parts of a PO file into a compendium: Creating Compendia. - (line 65) -* FDL, GNU Free Documentation License: GNU FDL. (line 6) -* file format, .mo: MO Files. (line 6) -* file format, .po: PO Files. (line 6) -* files, .po and .mo: Files. (line 6) -* files, .pot: Overview. (line 67) -* filter messages according to attributes: msgattrib Invocation. - (line 8) -* find common messages: msgcomm Invocation. (line 8) -* force use of fuzzy entries: msgfmt Invocation. (line 199) -* format strings: c-format Flag. (line 6) -* Free Pascal: Pascal. (line 6) -* function attribute, __format__: xgettext Invocation. (line 205) -* function attribute, __format_arg__: xgettext Invocation. (line 219) -* fuzzy entries: Fuzzy Entries. (line 6) -* fuzzy flag: PO Files. (line 80) -* gawk: gawk. (line 6) -* gcc-internal-format flag: PO Files. (line 177) -* GCC-source: GCC-source. (line 6) -* generate binary message catalog from PO file: msgfmt Invocation. - (line 8) -* generate translation catalog in English: msgen Invocation. (line 8) -* gettext files: Adjusting Files. (line 6) -* gettext installation: Installation. (line 6) -* gettext interface: Interface to gettext. - (line 6) -* gettext program, usage: gettext Invocation. (line 6) -* gettext vs catgets: Comparison. (line 6) -* gettext, a programmer's view: gettext. (line 6) -* gettext.h file: lib/gettext.h. (line 6) -* gettextize program, usage: gettextize Invocation. - (line 34) -* gfc-internal-format flag: PO Files. (line 181) -* GNOME PO file editor: Gtranslator. (line 6) -* GPL, GNU General Public License: GNU GPL. (line 6) -* GUI programs: Contexts. (line 6) -* guile: Scheme. (line 6) -* hash table, inside MO files: MO Files. (line 55) -* he, she, and they: Introduction. (line 15) -* header entry of a PO file: Header Entry. (line 6) -* help option: Preparing Strings. (line 109) -* history of GNU gettext: History. (line 6) -* i18n: Concepts. (line 6) -* importing PO files: Normalizing. (line 55) -* include file libintl.h <1>: lib/gettext.h. (line 29) -* include file libintl.h <2>: Comparison. (line 33) -* include file libintl.h <3>: Importing. (line 11) -* include file libintl.h: Overview. (line 57) -* initialization: Triggering. (line 6) -* initialize new PO file: msginit Invocation. (line 8) -* initialize translations from a compendium: Using Compendia. (line 12) -* installing gettext: Installation. (line 6) -* interface to catgets: Interface to catgets. - (line 6) -* internationalization: Concepts. (line 16) -* inttypes.h: Preparing Strings. (line 133) -* ISO 3166: Country Codes. (line 6) -* ISO 639: Language Codes. (line 6) -* Java: Java. (line 6) -* Java mode, and msgfmt program: msgfmt Invocation. (line 30) -* Java mode, and msgunfmt program: msgunfmt Invocation. (line 16) -* Java, string concatenation: Preparing Strings. (line 168) -* java-format flag: PO Files. (line 141) -* KDE format strings: xgettext Invocation. (line 250) -* KDE PO file editor: KBabel. (line 6) -* kde-format flag: PO Files. (line 194) -* keyboard accelerator checking: msgfmt Invocation. (line 187) -* l10n: Concepts. (line 6) -* language codes: Language Codes. (line 6) -* language selection: Locale Environment Variables. - (line 6) -* language selection at runtime: gettext grok. (line 14) -* large package: Ambiguities. (line 6) -* LGPL, GNU Lesser General Public License: GNU LGPL. (line 6) -* libiconv library: AM_ICONV. (line 21) -* libintl for C#: C#. (line 178) -* libintl for Java: Java. (line 105) -* libintl library: AM_GNU_GETTEXT. (line 53) -* librep Lisp: librep. (line 6) -* librep-format flag: PO Files. (line 129) -* License, GNU FDL: GNU FDL. (line 6) -* License, GNU GPL: GNU GPL. (line 6) -* License, GNU LGPL: GNU LGPL. (line 6) -* Licenses: Licenses. (line 6) -* LINGUAS file: po/LINGUAS. (line 6) -* link with libintl: Overview. (line 62) -* Linux <1>: Header Entry. (line 132) -* Linux <2>: Overview. (line 62) -* Linux: Aspects. (line 125) -* Lisp: Common Lisp. (line 6) -* lisp-format flag: PO Files. (line 121) -* list of translation teams, where to find: Header Entry. (line 59) -* locale categories: Aspects. (line 61) -* locale category, LC_ALL: Triggering. (line 23) -* locale category, LC_COLLATE: Triggering. (line 53) -* locale category, LC_CTYPE <1>: Triggering. (line 23) -* locale category, LC_CTYPE: Aspects. (line 67) -* locale category, LC_MESSAGES <1>: Triggering. (line 53) -* locale category, LC_MESSAGES: Aspects. (line 108) -* locale category, LC_MONETARY <1>: Triggering. (line 53) -* locale category, LC_MONETARY: Aspects. (line 79) -* locale category, LC_NUMERIC <1>: Triggering. (line 53) -* locale category, LC_NUMERIC: Aspects. (line 94) -* locale category, LC_RESPONSES: Triggering. (line 53) -* locale category, LC_TIME <1>: Triggering. (line 53) -* locale category, LC_TIME: Aspects. (line 84) -* locale program: Header Entry. (line 112) -* localization: Concepts. (line 26) -* lookup message translation <1>: eval_gettext Invocation. - (line 8) -* lookup message translation: gettext Invocation. (line 9) -* lookup plural message translation <1>: eval_ngettext Invocation. - (line 8) -* lookup plural message translation: ngettext Invocation. (line 8) -* magic signature of MO files: MO Files. (line 9) -* Makefile.in.in extensions: po/Rules-*. (line 6) -* Makevars file: po/Makevars. (line 6) -* manipulating PO files: Manipulating. (line 6) -* marking Perl sources: Perl. (line 93) -* marking string initializers: Special cases. (line 6) -* marking strings that require translation: Mark Keywords. (line 6) -* marking strings, preparations: Preparing Strings. (line 6) -* marking translatable strings: Overview. (line 34) -* markup: Preparing Strings. (line 190) -* menu entries: Contexts. (line 6) -* menu, keyboard accelerator support: msgfmt Invocation. (line 187) -* merge PO files: msgcat Invocation. (line 8) -* merging two PO files: Manipulating. (line 10) -* message catalog files location: Locating Catalogs. (line 6) -* messages: Aspects. (line 108) -* migration from earlier versions of gettext: Prerequisites. (line 6) -* mkinstalldirs file: mkinstalldirs. (line 6) -* mnemonics of menu entries: msgfmt Invocation. (line 187) -* MO file's format: MO Files. (line 6) -* modify message attributes: msgattrib Invocation. - (line 62) -* msgattrib program, usage: msgattrib Invocation. - (line 6) -* msgcat program, usage: msgcat Invocation. (line 6) -* msgcmp program, usage: msgcmp Invocation. (line 6) -* msgcomm program, usage: msgcomm Invocation. (line 6) -* msgconv program, usage: msgconv Invocation. (line 6) -* msgctxt: PO Files. (line 202) -* msgen program, usage: msgen Invocation. (line 6) -* msgexec program, usage: msgexec Invocation. (line 6) -* msgfilter filter and catalog encoding: msgfilter Invocation. - (line 53) -* msgfilter program, usage: msgfilter Invocation. - (line 6) -* msgfmt program, usage: msgfmt Invocation. (line 6) -* msggrep program, usage: msggrep Invocation. (line 6) -* msgid: PO Files. (line 56) -* msgid_plural: PO Files. (line 222) -* msginit program, usage: msginit Invocation. (line 6) -* msgmerge program, usage: msgmerge Invocation. (line 6) -* msgstr: PO Files. (line 56) -* msgunfmt program, usage: msgunfmt Invocation. (line 6) -* msguniq program, usage: msguniq Invocation. (line 6) -* multi-line strings: Normalizing. (line 65) -* N_, a convenience macro: Comparison. (line 41) -* Native Language Support: Concepts. (line 51) -* Natural Language Support: Concepts. (line 51) -* newlines in PO files: PO Files. (line 302) -* ngettext: Plural forms. (line 84) -* ngettext program, usage: ngettext Invocation. (line 6) -* NLS: Concepts. (line 51) -* no-awk-format flag: PO Files. (line 150) -* no-boost-format flag: PO Files. (line 199) -* no-c-format flag: PO Files. (line 91) -* no-c-format, and xgettext: c-format Flag. (line 48) -* no-csharp-format flag: PO Files. (line 146) -* no-elisp-format flag: PO Files. (line 126) -* no-gcc-internal-format flag: PO Files. (line 178) -* no-gfc-internal-format flag: PO Files. (line 182) -* no-java-format flag: PO Files. (line 142) -* no-kde-format flag: PO Files. (line 195) -* no-librep-format flag: PO Files. (line 130) -* no-lisp-format flag: PO Files. (line 122) -* no-objc-format flag: PO Files. (line 110) -* no-object-pascal-format flag: PO Files. (line 154) -* no-perl-brace-format flag: PO Files. (line 170) -* no-perl-format flag: PO Files. (line 166) -* no-php-format flag: PO Files. (line 174) -* no-python-format flag: PO Files. (line 118) -* no-qt-format flag: PO Files. (line 187) -* no-qt-plural-format flag: PO Files. (line 191) -* no-scheme-format flag: PO Files. (line 134) -* no-sh-format flag: PO Files. (line 114) -* no-smalltalk-format flag: PO Files. (line 138) -* no-tcl-format flag: PO Files. (line 162) -* no-ycp-format flag: PO Files. (line 158) -* nplurals, in a PO file header: Plural forms. (line 178) -* number format: Aspects. (line 94) -* objc-format flag: PO Files. (line 109) -* Object Pascal: Pascal. (line 6) -* object-pascal-format flag: PO Files. (line 153) -* obsolete entries: Obsolete Entries. (line 6) -* optimization of gettext functions: Optimized gettext. (line 6) -* orthography: Manipulating. (line 28) -* outdigits: c-format. (line 28) -* output to stdout, xgettext: xgettext Invocation. (line 48) -* overview of gettext: Overview. (line 6) -* package and version declaration in configure.ac: configure.ac. - (line 9) -* package build and installation options: Installers. (line 6) -* package distributor's view of gettext: Installers. (line 6) -* package installer's view of gettext: Installers. (line 6) -* package maintainer's view of gettext: Maintainers. (line 6) -* paragraphs: Preparing Strings. (line 101) -* Pascal: Pascal. (line 6) -* Perl: Perl. (line 6) -* Perl default keywords: Default Keywords. (line 6) -* Perl invalid string interpolation: Interpolation I. (line 6) -* Perl long lines: Long Lines. (line 6) -* Perl parentheses: Parentheses. (line 6) -* Perl pitfalls: Perl Pitfalls. (line 6) -* Perl quote-like expressions: Quote-like Expressions. - (line 6) -* Perl special keywords for hash-lookups: Special Keywords. (line 6) -* Perl valid string interpolation: Interpolation II. (line 6) -* perl-brace-format flag: PO Files. (line 169) -* perl-format flag: PO Files. (line 165) -* pgettext: Contexts. (line 33) -* pgettext_expr: Contexts. (line 112) -* PHP: PHP. (line 6) -* php-format flag: PO Files. (line 173) -* Pike: Pike. (line 6) -* plural form formulas: Plural forms. (line 198) -* plural forms: Plural forms. (line 6) -* plural forms, in MO files: MO Files. (line 74) -* plural forms, in PO files: PO Files. (line 222) -* plural forms, translating: Translating plural forms. - (line 6) -* plural, in a PO file header: Plural forms. (line 178) -* PO files' format: PO Files. (line 6) -* PO mode (Emacs) commands: Main PO Commands. (line 6) -* PO template file: Template. (line 6) -* po_file_domains: libgettextpo. (line 41) -* po_file_free: libgettextpo. (line 36) -* po_file_read: libgettextpo. (line 30) -* po_message_iterator: libgettextpo. (line 50) -* po_message_iterator_free: libgettextpo. (line 57) -* po_message_msgid: libgettextpo. (line 70) -* po_message_msgid_plural: libgettextpo. (line 75) -* po_message_msgstr: libgettextpo. (line 80) -* po_message_msgstr_plural: libgettextpo. (line 86) -* po_next_message: libgettextpo. (line 62) -* portability problems with sed: msgfilter Invocation. - (line 64) -* POTFILES.in file: po/POTFILES.in. (line 6) -* preparing programs for translation: Sources. (line 6) -* preparing shell scripts for translation: Preparing Shell Scripts. - (line 6) -* problems with catgets interface: Problems with catgets. - (line 6) -* programming languages: Language Implementors. - (line 6) -* Python: Python. (line 6) -* python-format flag: PO Files. (line 117) -* Qt format strings: xgettext Invocation. (line 246) -* Qt mode, and msgfmt program: msgfmt Invocation. (line 46) -* qt-format flag: PO Files. (line 186) -* qt-plural-format flag: PO Files. (line 190) -* quotation marks <1>: po/Rules-*. (line 11) -* quotation marks: Header Entry. (line 186) -* quote characters, use in PO files: Header Entry. (line 186) -* range: flag: PO Files. (line 253) -* recode-sr-latin program: msgfilter Invocation. - (line 92) -* related reading: References. (line 6) -* release: Release Management. (line 6) -* RST: RST. (line 6) -* Scheme: Scheme. (line 6) -* scheme-format flag: PO Files. (line 133) -* scripting languages: Language Implementors. - (line 6) -* search messages in a catalog: msggrep Invocation. (line 8) -* selecting message language: Locale Environment Variables. - (line 6) -* sentences: Preparing Strings. (line 44) -* setting up gettext at build time: Installers. (line 6) -* setting up gettext at run time: Locale Environment Variables. - (line 6) -* several domains: Ambiguities. (line 6) -* sex: Introduction. (line 15) -* sh-format flag: PO Files. (line 113) -* she, he, and they: Introduction. (line 15) -* shell format string: envsubst Invocation. (line 8) -* shell scripts: sh. (line 6) -* Smalltalk: Smalltalk. (line 6) -* smalltalk-format flag: PO Files. (line 137) -* sorting msgcat output: msgcat Invocation. (line 151) -* sorting msgmerge output: msgmerge Invocation. (line 187) -* sorting msgunfmt output: msgunfmt Invocation. (line 153) -* sorting output of xgettext: xgettext Invocation. (line 328) -* specifying plural form in a PO file: Plural forms. (line 178) -* standard output, and msgcat: msgcat Invocation. (line 47) -* standard output, and msgmerge program: msgmerge Invocation. (line 56) -* string concatenation: Preparing Strings. (line 117) -* string normalization in entries: Normalizing. (line 6) -* style: Preparing Strings. (line 24) -* supported languages, xgettext: xgettext Invocation. (line 56) -* Tcl: Tcl. (line 6) -* Tcl mode, and msgfmt program: msgfmt Invocation. (line 43) -* Tcl mode, and msgunfmt program: msgunfmt Invocation. (line 26) -* tcl-format flag: PO Files. (line 161) -* template PO file: Overview. (line 67) -* testing .po files for equivalence: xgettext Invocation. (line 338) -* Tk's scripting language: Tcl. (line 6) -* translated entries: Translated Entries. (line 6) -* translating menu entries: Contexts. (line 6) -* translation aspects: Aspects. (line 6) -* Translation Matrix: Installing Localizations. - (line 6) -* Translation Project: Why. (line 17) -* turning off NLS support: lib/gettext.h. (line 6) -* tutorial of gettext usage: Overview. (line 6) -* unify duplicate translations: msguniq Invocation. (line 8) -* untranslated entries: Untranslated Entries. - (line 6) -* update translations from a compendium: Using Compendia. (line 20) -* upgrading to new versions of gettext: Prerequisites. (line 6) -* version control for backup files, msgmerge: msgmerge Invocation. - (line 71) -* wxWidgets library: wxWidgets. (line 6) -* xargs, and output from msgexec: msgexec Invocation. (line 14) -* xgettext program, usage: xgettext Invocation. (line 6) -* xmodmap program, and typing quotation marks: Header Entry. (line 198) -* YaST2 scripting language: YCP. (line 6) -* YCP: YCP. (line 6) -* ycp-format flag: PO Files. (line 157) - - - -Tag Table: -Node: Top2956 -Node: Introduction17401 -Node: Why19024 -Ref: Why-Footnote-122238 -Node: Concepts22394 -Node: Aspects25815 -Node: Files32349 -Node: Overview34258 -Node: Users44194 -Node: System Installation45105 -Node: Setting the GUI Locale46797 -Node: Setting the POSIX Locale48173 -Node: Locale Names49112 -Node: Locale Environment Variables51517 -Node: The LANGUAGE variable53730 -Node: Installing Localizations55630 -Node: PO Files56985 -Ref: PO Files-Footnote-169122 -Node: Sources69249 -Node: Importing70475 -Node: Triggering71158 -Node: Preparing Strings74358 -Node: Mark Keywords83401 -Node: Marking87861 -Node: c-format Flag95591 -Node: Special cases99510 -Node: Bug Report Address102253 -Node: Names104218 -Node: Libraries108503 -Node: Template111540 -Node: xgettext Invocation112265 -Node: Creating127823 -Node: msginit Invocation128708 -Node: Header Entry131610 -Node: Updating140573 -Node: msgmerge Invocation140788 -Node: Editing146578 -Node: KBabel146936 -Node: Gtranslator147074 -Node: PO Mode147216 -Node: Installation148870 -Node: Main PO Commands150834 -Node: Entry Positioning155922 -Node: Normalizing161390 -Node: Translated Entries165884 -Node: Fuzzy Entries167242 -Node: Untranslated Entries170423 -Node: Obsolete Entries172355 -Node: Modifying Translations175580 -Node: Modifying Comments183549 -Node: Subedit187976 -Node: C Sources Context191872 -Node: Auxiliary196996 -Node: Compendium200212 -Node: Creating Compendia200827 -Node: Using Compendia203311 -Node: Manipulating204251 -Node: msgcat Invocation208079 -Node: msgconv Invocation212833 -Node: msggrep Invocation216288 -Node: msgfilter Invocation222446 -Node: msguniq Invocation228985 -Node: msgcomm Invocation233150 -Node: msgcmp Invocation237471 -Node: msgattrib Invocation239628 -Node: msgen Invocation244589 -Node: msgexec Invocation248441 -Node: Colorizing251020 -Node: The --color option252049 -Node: The TERM variable253681 -Node: The --style option255133 -Node: Style rules256441 -Node: Customizing less263183 -Node: libgettextpo264586 -Node: Binaries269702 -Node: msgfmt Invocation270046 -Node: msgunfmt Invocation277198 -Node: MO Files281636 -Node: Programmers290214 -Node: catgets291396 -Node: Interface to catgets292810 -Node: Problems with catgets294819 -Node: gettext295734 -Node: Interface to gettext297237 -Node: Ambiguities299567 -Node: Locating Catalogs302282 -Ref: Locating Catalogs-Footnote-1303512 -Ref: Locating Catalogs-Footnote-2303738 -Node: Charset conversion303887 -Node: Contexts306341 -Node: Plural forms311847 -Ref: Plural forms-Footnote-1327784 -Node: Optimized gettext327906 -Node: Comparison329245 -Node: Using libintl.a333515 -Node: gettext grok333958 -Node: Temp Programmers336599 -Node: Temp Implementations337127 -Node: Temp catgets338507 -Node: Temp WSI340208 -Node: Temp Notes342210 -Node: Translators342713 -Node: Trans Intro 0343248 -Node: Trans Intro 1345997 -Node: Discussions347961 -Node: Organization351619 -Node: Central Coordination353695 -Node: National Teams354838 -Node: Sub-Cultures357365 -Node: Organizational Ideas358302 -Node: Mailing Lists359323 -Node: Information Flow361146 -Node: Translating plural forms363400 -Node: Prioritizing messages366769 -Node: Maintainers371076 -Node: Flat and Non-Flat373032 -Node: Prerequisites374525 -Node: gettextize Invocation378682 -Node: Adjusting Files386091 -Node: po/POTFILES.in387880 -Node: po/LINGUAS389129 -Node: po/Makevars390821 -Node: po/Rules-*391763 -Node: configure.ac393234 -Node: config.guess396256 -Node: mkinstalldirs397611 -Node: aclocal398016 -Node: acconfig400030 -Node: config.h.in400530 -Node: Makefile401998 -Node: src/Makefile404595 -Node: lib/gettext.h409316 -Node: autoconf macros411564 -Node: AM_GNU_GETTEXT412406 -Node: AM_GNU_GETTEXT_VERSION416371 -Node: AM_GNU_GETTEXT_NEED416826 -Node: AM_GNU_GETTEXT_INTL_SUBDIR417719 -Node: AM_PO_SUBDIRS418374 -Node: AM_XGETTEXT_OPTION419169 -Node: AM_ICONV420039 -Node: CVS Issues422254 -Node: Distributed CVS422845 -Node: Files under CVS424773 -Node: autopoint Invocation428049 -Node: Release Management429893 -Node: Installers430406 -Node: Programming Languages431633 -Node: Language Implementors432459 -Node: Programmers for other Languages437287 -Node: Translators for other Languages437871 -Node: c-format439568 -Node: objc-format441287 -Node: sh-format441642 -Node: python-format442447 -Node: lisp-format442888 -Node: elisp-format443217 -Node: librep-format443710 -Node: scheme-format444113 -Node: smalltalk-format444392 -Node: java-format444895 -Node: csharp-format445346 -Node: awk-format445724 -Node: object-pascal-format446052 -Node: ycp-format446438 -Node: tcl-format446840 -Node: perl-format447138 -Node: php-format447886 -Node: gcc-internal-format448254 -Node: gfc-internal-format449309 -Node: qt-format450006 -Node: qt-plural-format450447 -Node: kde-format450802 -Node: boost-format451215 -Node: Maintainers for other Languages451763 -Node: List of Programming Languages453001 -Node: C454284 -Node: sh455584 -Node: Preparing Shell Scripts456858 -Node: gettext.sh460250 -Node: gettext Invocation460800 -Node: ngettext Invocation462724 -Node: envsubst Invocation464485 -Node: eval_gettext Invocation465906 -Node: eval_ngettext Invocation466367 -Node: bash466881 -Node: Python468860 -Node: Common Lisp471183 -Node: clisp C471983 -Node: Emacs Lisp472698 -Node: librep473424 -Node: Scheme474159 -Node: Smalltalk474943 -Node: Java475977 -Node: C#481773 -Node: gawk490999 -Node: Pascal491911 -Node: wxWidgets493219 -Node: YCP494126 -Node: Tcl494865 -Node: Perl496275 -Node: General Problems499283 -Node: Default Keywords504771 -Node: Special Keywords505726 -Node: Quote-like Expressions507242 -Node: Interpolation I509520 -Node: Interpolation II513313 -Node: Parentheses515681 -Node: Long Lines517202 -Node: Perl Pitfalls519050 -Node: PHP523295 -Node: Pike524226 -Node: GCC-source524887 -Node: List of Data Formats525634 -Node: POT526103 -Node: RST526361 -Node: Glade526587 -Node: Conclusion526947 -Node: History527453 -Node: References531723 -Node: Language Codes533370 -Node: Usual Language Codes533885 -Node: Rare Language Codes538247 -Node: Country Codes539916 -Node: Licenses545805 -Node: GNU GPL547650 -Node: GNU LGPL566833 -Node: GNU FDL594972 -Node: Program Index617361 -Node: Option Index619247 -Node: Variable Index668348 -Node: PO Mode Index671605 -Node: Autoconf Macro Index685441 -Node: Index686248 - -End Tag Table - - -Local Variables: -coding: utf-8 -End: diff --git a/gtk+-mingw/share/info/libffi.info b/gtk+-mingw/share/info/libffi.info deleted file mode 100644 index 402f760..0000000 --- a/gtk+-mingw/share/info/libffi.info +++ /dev/null @@ -1,617 +0,0 @@ -This is ../libffi/doc/libffi.info, produced by makeinfo version 4.13 -from ../libffi/doc/libffi.texi. - -This manual is for Libffi, a portable foreign-function interface -library. - - Copyright (C) 2008, 2010, 2011 Red Hat, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2, or - (at your option) any later version. A copy of the license is - included in the section entitled "GNU General Public License". - - -INFO-DIR-SECTION Development -START-INFO-DIR-ENTRY -* libffi: (libffi). Portable foreign-function interface library. -END-INFO-DIR-ENTRY - - -File: libffi.info, Node: Top, Next: Introduction, Up: (dir) - -libffi -****** - -This manual is for Libffi, a portable foreign-function interface -library. - - Copyright (C) 2008, 2010, 2011 Red Hat, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2, or - (at your option) any later version. A copy of the license is - included in the section entitled "GNU General Public License". - - -* Menu: - -* Introduction:: What is libffi? -* Using libffi:: How to use libffi. -* Missing Features:: Things libffi can't do. -* Index:: Index. - - -File: libffi.info, Node: Introduction, Next: Using libffi, Prev: Top, Up: Top - -1 What is libffi? -***************** - -Compilers for high level languages generate code that follow certain -conventions. These conventions are necessary, in part, for separate -compilation to work. One such convention is the "calling convention". -The calling convention is a set of assumptions made by the compiler -about where function arguments will be found on entry to a function. A -calling convention also specifies where the return value for a function -is found. The calling convention is also sometimes called the "ABI" or -"Application Binary Interface". - - Some programs may not know at the time of compilation what arguments -are to be passed to a function. For instance, an interpreter may be -told at run-time about the number and types of arguments used to call a -given function. `Libffi' can be used in such programs to provide a -bridge from the interpreter program to compiled code. - - The `libffi' library provides a portable, high level programming -interface to various calling conventions. This allows a programmer to -call any function specified by a call interface description at run time. - - FFI stands for Foreign Function Interface. A foreign function -interface is the popular name for the interface that allows code -written in one language to call code written in another language. The -`libffi' library really only provides the lowest, machine dependent -layer of a fully featured foreign function interface. A layer must -exist above `libffi' that handles type conversions for values passed -between the two languages. - - -File: libffi.info, Node: Using libffi, Next: Missing Features, Prev: Introduction, Up: Top - -2 Using libffi -************** - -* Menu: - -* The Basics:: The basic libffi API. -* Simple Example:: A simple example. -* Types:: libffi type descriptions. -* Multiple ABIs:: Different passing styles on one platform. -* The Closure API:: Writing a generic function. -* Closure Example:: A closure example. - - -File: libffi.info, Node: The Basics, Next: Simple Example, Up: Using libffi - -2.1 The Basics -============== - -`Libffi' assumes that you have a pointer to the function you wish to -call and that you know the number and types of arguments to pass it, as -well as the return type of the function. - - The first thing you must do is create an `ffi_cif' object that -matches the signature of the function you wish to call. This is a -separate step because it is common to make multiple calls using a -single `ffi_cif'. The "cif" in `ffi_cif' stands for Call InterFace. -To prepare a call interface object, use the function `ffi_prep_cif'. - - -- Function: ffi_status ffi_prep_cif (ffi_cif *CIF, ffi_abi ABI, - unsigned int NARGS, ffi_type *RTYPE, ffi_type **ARGTYPES) - This initializes CIF according to the given parameters. - - ABI is the ABI to use; normally `FFI_DEFAULT_ABI' is what you - want. *note Multiple ABIs:: for more information. - - NARGS is the number of arguments that this function accepts. - - RTYPE is a pointer to an `ffi_type' structure that describes the - return type of the function. *Note Types::. - - ARGTYPES is a vector of `ffi_type' pointers. ARGTYPES must have - NARGS elements. If NARGS is 0, this argument is ignored. - - `ffi_prep_cif' returns a `libffi' status code, of type - `ffi_status'. This will be either `FFI_OK' if everything worked - properly; `FFI_BAD_TYPEDEF' if one of the `ffi_type' objects is - incorrect; or `FFI_BAD_ABI' if the ABI parameter is invalid. - - If the function being called is variadic (varargs) then -`ffi_prep_cif_var' must be used instead of `ffi_prep_cif'. - - -- Function: ffi_status ffi_prep_cif_var (ffi_cif *CIF, ffi_abi - varabi, unsigned int NFIXEDARGS, unsigned int varntotalargs, - ffi_type *RTYPE, ffi_type **ARGTYPES) - This initializes CIF according to the given parameters for a call - to a variadic function. In general it's operation is the same as - for `ffi_prep_cif' except that: - - NFIXEDARGS is the number of fixed arguments, prior to any variadic - arguments. It must be greater than zero. - - NTOTALARGS the total number of arguments, including variadic and - fixed arguments. - - Note that, different cif's must be prepped for calls to the same - function when different numbers of arguments are passed. - - Also note that a call to `ffi_prep_cif_var' with - NFIXEDARGS=NOTOTALARGS is NOT equivalent to a call to - `ffi_prep_cif'. - - - To call a function using an initialized `ffi_cif', use the -`ffi_call' function: - - -- Function: void ffi_call (ffi_cif *CIF, void *FN, void *RVALUE, void - **AVALUES) - This calls the function FN according to the description given in - CIF. CIF must have already been prepared using `ffi_prep_cif'. - - RVALUE is a pointer to a chunk of memory that will hold the result - of the function call. This must be large enough to hold the - result and must be suitably aligned; it is the caller's - responsibility to ensure this. If CIF declares that the function - returns `void' (using `ffi_type_void'), then RVALUE is ignored. - If RVALUE is `NULL', then the return value is discarded. - - AVALUES is a vector of `void *' pointers that point to the memory - locations holding the argument values for a call. If CIF declares - that the function has no arguments (i.e., NARGS was 0), then - AVALUES is ignored. Note that argument values may be modified by - the callee (for instance, structs passed by value); the burden of - copying pass-by-value arguments is placed on the caller. - - -File: libffi.info, Node: Simple Example, Next: Types, Prev: The Basics, Up: Using libffi - -2.2 Simple Example -================== - -Here is a trivial example that calls `puts' a few times. - - #include <stdio.h> - #include <ffi.h> - - int main() - { - ffi_cif cif; - ffi_type *args[1]; - void *values[1]; - char *s; - int rc; - - /* Initialize the argument info vectors */ - args[0] = &ffi_type_pointer; - values[0] = &s; - - /* Initialize the cif */ - if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, - &ffi_type_uint, args) == FFI_OK) - { - s = "Hello World!"; - ffi_call(&cif, puts, &rc, values); - /* rc now holds the result of the call to puts */ - - /* values holds a pointer to the function's arg, so to - call puts() again all we need to do is change the - value of s */ - s = "This is cool!"; - ffi_call(&cif, puts, &rc, values); - } - - return 0; - } - - -File: libffi.info, Node: Types, Next: Multiple ABIs, Prev: Simple Example, Up: Using libffi - -2.3 Types -========= - -* Menu: - -* Primitive Types:: Built-in types. -* Structures:: Structure types. -* Type Example:: Structure type example. - - -File: libffi.info, Node: Primitive Types, Next: Structures, Up: Types - -2.3.1 Primitive Types ---------------------- - -`Libffi' provides a number of built-in type descriptors that can be -used to describe argument and return types: - -`ffi_type_void' - The type `void'. This cannot be used for argument types, only for - return values. - -`ffi_type_uint8' - An unsigned, 8-bit integer type. - -`ffi_type_sint8' - A signed, 8-bit integer type. - -`ffi_type_uint16' - An unsigned, 16-bit integer type. - -`ffi_type_sint16' - A signed, 16-bit integer type. - -`ffi_type_uint32' - An unsigned, 32-bit integer type. - -`ffi_type_sint32' - A signed, 32-bit integer type. - -`ffi_type_uint64' - An unsigned, 64-bit integer type. - -`ffi_type_sint64' - A signed, 64-bit integer type. - -`ffi_type_float' - The C `float' type. - -`ffi_type_double' - The C `double' type. - -`ffi_type_uchar' - The C `unsigned char' type. - -`ffi_type_schar' - The C `signed char' type. (Note that there is not an exact - equivalent to the C `char' type in `libffi'; ordinarily you should - either use `ffi_type_schar' or `ffi_type_uchar' depending on - whether `char' is signed.) - -`ffi_type_ushort' - The C `unsigned short' type. - -`ffi_type_sshort' - The C `short' type. - -`ffi_type_uint' - The C `unsigned int' type. - -`ffi_type_sint' - The C `int' type. - -`ffi_type_ulong' - The C `unsigned long' type. - -`ffi_type_slong' - The C `long' type. - -`ffi_type_longdouble' - On platforms that have a C `long double' type, this is defined. - On other platforms, it is not. - -`ffi_type_pointer' - A generic `void *' pointer. You should use this for all pointers, - regardless of their real type. - - Each of these is of type `ffi_type', so you must take the address -when passing to `ffi_prep_cif'. - - -File: libffi.info, Node: Structures, Next: Type Example, Prev: Primitive Types, Up: Types - -2.3.2 Structures ----------------- - -Although `libffi' has no special support for unions or bit-fields, it -is perfectly happy passing structures back and forth. You must first -describe the structure to `libffi' by creating a new `ffi_type' object -for it. - - -- ffi_type: - The `ffi_type' has the following members: - `size_t size' - This is set by `libffi'; you should initialize it to zero. - - `unsigned short alignment' - This is set by `libffi'; you should initialize it to zero. - - `unsigned short type' - For a structure, this should be set to `FFI_TYPE_STRUCT'. - - `ffi_type **elements' - This is a `NULL'-terminated array of pointers to `ffi_type' - objects. There is one element per field of the struct. - - -File: libffi.info, Node: Type Example, Prev: Structures, Up: Types - -2.3.3 Type Example ------------------- - -The following example initializes a `ffi_type' object representing the -`tm' struct from Linux's `time.h'. - - Here is how the struct is defined: - - struct tm { - int tm_sec; - int tm_min; - int tm_hour; - int tm_mday; - int tm_mon; - int tm_year; - int tm_wday; - int tm_yday; - int tm_isdst; - /* Those are for future use. */ - long int __tm_gmtoff__; - __const char *__tm_zone__; - }; - - Here is the corresponding code to describe this struct to `libffi': - - { - ffi_type tm_type; - ffi_type *tm_type_elements[12]; - int i; - - tm_type.size = tm_type.alignment = 0; - tm_type.elements = &tm_type_elements; - - for (i = 0; i < 9; i++) - tm_type_elements[i] = &ffi_type_sint; - - tm_type_elements[9] = &ffi_type_slong; - tm_type_elements[10] = &ffi_type_pointer; - tm_type_elements[11] = NULL; - - /* tm_type can now be used to represent tm argument types and - return types for ffi_prep_cif() */ - } - - -File: libffi.info, Node: Multiple ABIs, Next: The Closure API, Prev: Types, Up: Using libffi - -2.4 Multiple ABIs -================= - -A given platform may provide multiple different ABIs at once. For -instance, the x86 platform has both `stdcall' and `fastcall' functions. - - `libffi' provides some support for this. However, this is -necessarily platform-specific. - - -File: libffi.info, Node: The Closure API, Next: Closure Example, Prev: Multiple ABIs, Up: Using libffi - -2.5 The Closure API -=================== - -`libffi' also provides a way to write a generic function - a function -that can accept and decode any combination of arguments. This can be -useful when writing an interpreter, or to provide wrappers for -arbitrary functions. - - This facility is called the "closure API". Closures are not -supported on all platforms; you can check the `FFI_CLOSURES' define to -determine whether they are supported on the current platform. - - Because closures work by assembling a tiny function at runtime, they -require special allocation on platforms that have a non-executable -heap. Memory management for closures is handled by a pair of functions: - - -- Function: void *ffi_closure_alloc (size_t SIZE, void **CODE) - Allocate a chunk of memory holding SIZE bytes. This returns a - pointer to the writable address, and sets *CODE to the - corresponding executable address. - - SIZE should be sufficient to hold a `ffi_closure' object. - - -- Function: void ffi_closure_free (void *WRITABLE) - Free memory allocated using `ffi_closure_alloc'. The argument is - the writable address that was returned. - - Once you have allocated the memory for a closure, you must construct -a `ffi_cif' describing the function call. Finally you can prepare the -closure function: - - -- Function: ffi_status ffi_prep_closure_loc (ffi_closure *CLOSURE, - ffi_cif *CIF, void (*FUN) (ffi_cif *CIF, void *RET, void - **ARGS, void *USER_DATA), void *USER_DATA, void *CODELOC) - Prepare a closure function. - - CLOSURE is the address of a `ffi_closure' object; this is the - writable address returned by `ffi_closure_alloc'. - - CIF is the `ffi_cif' describing the function parameters. - - USER_DATA is an arbitrary datum that is passed, uninterpreted, to - your closure function. - - CODELOC is the executable address returned by `ffi_closure_alloc'. - - FUN is the function which will be called when the closure is - invoked. It is called with the arguments: - CIF - The `ffi_cif' passed to `ffi_prep_closure_loc'. - - RET - A pointer to the memory used for the function's return value. - FUN must fill this, unless the function is declared as - returning `void'. - - ARGS - A vector of pointers to memory holding the arguments to the - function. - - USER_DATA - The same USER_DATA that was passed to `ffi_prep_closure_loc'. - - `ffi_prep_closure_loc' will return `FFI_OK' if everything went ok, - and something else on error. - - After calling `ffi_prep_closure_loc', you can cast CODELOC to the - appropriate pointer-to-function type. - - You may see old code referring to `ffi_prep_closure'. This function -is deprecated, as it cannot handle the need for separate writable and -executable addresses. - - -File: libffi.info, Node: Closure Example, Prev: The Closure API, Up: Using libffi - -2.6 Closure Example -=================== - -A trivial example that creates a new `puts' by binding `fputs' with -`stdin'. - - #include <stdio.h> - #include <ffi.h> - - /* Acts like puts with the file given at time of enclosure. */ - void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[], - FILE *stream) - { - *ret = fputs(*(char **)args[0], stream); - } - - int main() - { - ffi_cif cif; - ffi_type *args[1]; - ffi_closure *closure; - - int (*bound_puts)(char *); - int rc; - - /* Allocate closure and bound_puts */ - closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts); - - if (closure) - { - /* Initialize the argument info vectors */ - args[0] = &ffi_type_pointer; - - /* Initialize the cif */ - if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, - &ffi_type_uint, args) == FFI_OK) - { - /* Initialize the closure, setting stream to stdout */ - if (ffi_prep_closure_loc(closure, &cif, puts_binding, - stdout, bound_puts) == FFI_OK) - { - rc = bound_puts("Hello World!"); - /* rc now holds the result of the call to fputs */ - } - } - } - - /* Deallocate both closure, and bound_puts */ - ffi_closure_free(closure); - - return 0; - } - - -File: libffi.info, Node: Missing Features, Next: Index, Prev: Using libffi, Up: Top - -3 Missing Features -****************** - -`libffi' is missing a few features. We welcome patches to add support -for these. - - * Variadic closures. - - * There is no support for bit fields in structures. - - * The closure API is - - * The "raw" API is undocumented. - - Note that variadic support is very new and tested on a relatively -small number of platforms. - - -File: libffi.info, Node: Index, Prev: Missing Features, Up: Top - -Index -***** - - -* Menu: - -* : Structures. (line 12) -* ABI: Introduction. (line 13) -* Application Binary Interface: Introduction. (line 13) -* calling convention: Introduction. (line 13) -* cif: The Basics. (line 14) -* closure API: The Closure API. (line 13) -* closures: The Closure API. (line 13) -* FFI: Introduction. (line 31) -* ffi_call: The Basics. (line 63) -* ffi_closure_alloc: The Closure API. (line 19) -* ffi_closure_free: The Closure API. (line 26) -* FFI_CLOSURES: The Closure API. (line 13) -* ffi_prep_cif: The Basics. (line 16) -* ffi_prep_cif_var: The Basics. (line 39) -* ffi_prep_closure_loc: The Closure API. (line 34) -* ffi_status <1>: The Closure API. (line 37) -* ffi_status: The Basics. (line 18) -* ffi_type: Structures. (line 11) -* ffi_type_double: Primitive Types. (line 41) -* ffi_type_float: Primitive Types. (line 38) -* ffi_type_longdouble: Primitive Types. (line 71) -* ffi_type_pointer: Primitive Types. (line 75) -* ffi_type_schar: Primitive Types. (line 47) -* ffi_type_sint: Primitive Types. (line 62) -* ffi_type_sint16: Primitive Types. (line 23) -* ffi_type_sint32: Primitive Types. (line 29) -* ffi_type_sint64: Primitive Types. (line 35) -* ffi_type_sint8: Primitive Types. (line 17) -* ffi_type_slong: Primitive Types. (line 68) -* ffi_type_sshort: Primitive Types. (line 56) -* ffi_type_uchar: Primitive Types. (line 44) -* ffi_type_uint: Primitive Types. (line 59) -* ffi_type_uint16: Primitive Types. (line 20) -* ffi_type_uint32: Primitive Types. (line 26) -* ffi_type_uint64: Primitive Types. (line 32) -* ffi_type_uint8: Primitive Types. (line 14) -* ffi_type_ulong: Primitive Types. (line 65) -* ffi_type_ushort: Primitive Types. (line 53) -* ffi_type_void: Primitive Types. (line 10) -* Foreign Function Interface: Introduction. (line 31) -* void <1>: The Closure API. (line 20) -* void: The Basics. (line 65) - - - -Tag Table: -Node: Top712 -Node: Introduction1460 -Node: Using libffi3096 -Node: The Basics3582 -Node: Simple Example7224 -Node: Types8251 -Node: Primitive Types8534 -Node: Structures10354 -Node: Type Example11214 -Node: Multiple ABIs12437 -Node: The Closure API12808 -Node: Closure Example15752 -Node: Missing Features17311 -Node: Index17764 - -End Tag Table diff --git a/gtk+-mingw/share/info/libtool.info b/gtk+-mingw/share/info/libtool.info deleted file mode 100644 index 9a1263a..0000000 --- a/gtk+-mingw/share/info/libtool.info +++ /dev/null @@ -1,140 +0,0 @@ -This is doc/libtool.info, produced by makeinfo version 4.13 from -./doc/libtool.texi. - -INFO-DIR-SECTION GNU programming tools -START-INFO-DIR-ENTRY -* Libtool: (libtool). Generic shared library support script. -END-INFO-DIR-ENTRY - -INFO-DIR-SECTION Individual utilities -START-INFO-DIR-ENTRY -* libtool-invocation: (libtool)Invoking libtool. - Running the `libtool' script. -* libtoolize: (libtool)Invoking libtoolize. Adding libtool support. -END-INFO-DIR-ENTRY - - This file documents GNU Libtool 2.4.2 - - Copyright (C) 1996-2011 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled "GNU -Free Documentation License". - - -Indirect: -libtool.info-1: 999 -libtool.info-2: 284584 - -Tag Table: -(Indirect) -Node: Top999 -Node: Introduction8193 -Node: Motivation10020 -Node: Issues11340 -Node: Other implementations12818 -Node: Postmortem13361 -Node: Libtool paradigm14981 -Node: Using libtool15926 -Node: Creating object files18029 -Node: Linking libraries21766 -Ref: Linking libraries-Footnote-125593 -Node: Linking executables25734 -Ref: Linking executables-Footnote-130985 -Ref: Linking executables-Footnote-231278 -Node: Wrapper executables31358 -Node: Debugging executables33581 -Node: Installing libraries36404 -Ref: Installing libraries-Footnote-139566 -Node: Installing executables39637 -Node: Static libraries40473 -Node: Invoking libtool43750 -Node: Compile mode49393 -Node: Link mode52354 -Node: Execute mode61728 -Node: Install mode62508 -Node: Finish mode64881 -Node: Uninstall mode65743 -Node: Clean mode66184 -Node: Integrating libtool66643 -Node: Autoconf macros69477 -Node: Makefile rules73324 -Node: Using Automake74427 -Ref: Using Automake-Footnote-176008 -Node: Configuring76408 -Node: LT_INIT77660 -Ref: LT_INIT-Footnote-192591 -Node: Configure notes92844 -Node: Distributing96023 -Node: Invoking libtoolize96940 -Node: Autoconf and LTLIBOBJS103128 -Node: Static-only libraries103872 -Ref: Static-only libraries-Footnote-1105199 -Node: Other languages105308 -Node: C++ libraries106016 -Node: Tags107454 -Node: Versioning108868 -Node: Interfaces110236 -Node: Libtool versioning110869 -Node: Updating version info113082 -Node: Release numbers116110 -Node: Library tips117966 -Node: C header files120772 -Ref: C header files-Footnote-1124446 -Node: Inter-library dependencies124655 -Node: Dlopened modules127372 -Node: Building modules129259 -Node: Dlpreopening130460 -Node: Linking with dlopened modules136117 -Node: Finding the dlname141046 -Ref: Finding the dlname-Footnote-1142364 -Node: Dlopen issues142417 -Node: Using libltdl143472 -Node: Libltdl interface145314 -Ref: Libltdl interface-Footnote-1158964 -Node: Modules for libltdl159258 -Node: Thread Safety in libltdl161784 -Node: User defined module data162797 -Node: Module loaders for libltdl170290 -Ref: Module loaders for libltdl-Footnote-1179561 -Node: Distributing libltdl179667 -Ref: Distributing libltdl-Footnote-1193478 -Ref: Distributing libltdl-Footnote-2193774 -Node: Trace interface193924 -Node: FAQ194760 -Node: Stripped link flags195098 -Node: Troubleshooting196544 -Node: Libtool test suite197067 -Node: Test descriptions197845 -Node: When tests fail210238 -Node: Reporting bugs211242 -Node: Maintaining212860 -Node: New ports213603 -Node: Information sources214296 -Node: Porting inter-library dependencies216764 -Node: Tested platforms219490 -Node: Platform quirks227920 -Node: References229101 -Node: Compilers229951 -Ref: Compilers-Footnote-1231527 -Node: Reloadable objects231843 -Node: Multiple dependencies232202 -Node: Archivers233099 -Node: Cross compiling233689 -Node: File name conversion239701 -Node: File Name Conversion Failure242540 -Node: Native MinGW File Name Conversion243788 -Node: Cygwin/Windows File Name Conversion245351 -Node: Unix/Windows File Name Conversion246724 -Node: LT_CYGPATH247493 -Node: Cygwin to MinGW Cross250738 -Node: Windows DLLs255042 -Node: libtool script contents262320 -Node: Cheap tricks282713 -Node: GNU Free Documentation License284584 -Node: Combined Index309759 - -End Tag Table diff --git a/gtk+-mingw/share/info/libtool.info-1 b/gtk+-mingw/share/info/libtool.info-1 deleted file mode 100644 index 6d16648..0000000 --- a/gtk+-mingw/share/info/libtool.info-1 +++ /dev/null @@ -1,6698 +0,0 @@ -This is doc/libtool.info, produced by makeinfo version 4.13 from -./doc/libtool.texi. - -INFO-DIR-SECTION GNU programming tools -START-INFO-DIR-ENTRY -* Libtool: (libtool). Generic shared library support script. -END-INFO-DIR-ENTRY - -INFO-DIR-SECTION Individual utilities -START-INFO-DIR-ENTRY -* libtool-invocation: (libtool)Invoking libtool. - Running the `libtool' script. -* libtoolize: (libtool)Invoking libtoolize. Adding libtool support. -END-INFO-DIR-ENTRY - - This file documents GNU Libtool 2.4.2 - - Copyright (C) 1996-2011 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled "GNU -Free Documentation License". - - -File: libtool.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) - -Shared library support for GNU -****************************** - -This file documents GNU Libtool, a script that allows package developers -to provide generic shared library support. This edition documents -version 2.4.2. - - *Note Reporting bugs::, for information on how to report problems -with GNU Libtool. - -* Menu: - -* Introduction:: What the heck is libtool? -* Libtool paradigm:: How libtool's view of libraries is different. -* Using libtool:: Example of using libtool to build libraries. -* Invoking libtool:: Running the `libtool' script. -* Integrating libtool:: Using libtool in your own packages. -* Other languages:: Using libtool without a C compiler. -* Versioning:: Using library interface versions. -* Library tips:: Tips for library interface design. -* Inter-library dependencies:: Libraries that depend on other libraries. -* Dlopened modules:: `dlopen'ing libtool-created libraries. -* Using libltdl:: Libtool's portable `dlopen' wrapper library. -* Trace interface:: Libtool's trace interface. -* FAQ:: Frequently Asked Questions -* Troubleshooting:: When libtool doesn't work as advertised. -* Maintaining:: Information used by the libtool maintainer. -* GNU Free Documentation License:: License for this manual. -* Combined Index:: Full index. - - --- The Detailed Node Listing --- - -Introduction - -* Motivation:: Why does GNU need a libtool? -* Issues:: The problems that need to be addressed. -* Other implementations:: How other people have solved these issues. -* Postmortem:: Learning from past difficulties. - -Using libtool - -* Creating object files:: Compiling object files for libraries. -* Linking libraries:: Creating libraries from object files. -* Linking executables:: Linking object files against libtool libraries. -* Debugging executables:: Running GDB on libtool-generated programs. -* Installing libraries:: Making libraries available to users. -* Installing executables:: Making programs available to users. -* Static libraries:: When shared libraries are not wanted. - -Linking executables - -* Wrapper executables:: Wrapper executables for some platforms. - -Invoking `libtool' - -* Compile mode:: Creating library object files. -* Link mode:: Generating executables and libraries. -* Execute mode:: Debugging libtool-generated programs. -* Install mode:: Making libraries and executables public. -* Finish mode:: Completing a library installation. -* Uninstall mode:: Removing installed executables and libraries. -* Clean mode:: Removing uninstalled executables and libraries. - -Integrating libtool with your package - -* Autoconf macros:: Autoconf macros exported by libtool. -* Makefile rules:: Writing `Makefile' rules for libtool. -* Using Automake:: Automatically supporting libtool. -* Configuring:: Configuring libtool for a host system. -* Distributing:: What files to distribute with your package. -* Static-only libraries:: Sometimes shared libraries are just a pain. - -Configuring libtool - -* LT_INIT:: Configuring `libtool' in `configure.ac'. -* Configure notes:: Platform-specific notes for configuration. - -Including libtool in your package - -* Invoking libtoolize:: `libtoolize' command line options. -* Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation. - -Using libtool with other languages - -* C++ libraries:: Writing libraries for C++ -* Tags:: Tags - -Library interface versions - -* Interfaces:: What are library interfaces? -* Libtool versioning:: Libtool's versioning system. -* Updating version info:: Changing version information before releases. -* Release numbers:: Breaking binary compatibility for aesthetics. - -Tips for interface design - -* C header files:: How to write portable include files. - -Dlopened modules - -* Building modules:: Creating dlopenable objects and libraries. -* Dlpreopening:: Dlopening that works on static platforms. -* Linking with dlopened modules:: Using dlopenable modules in libraries. -* Finding the dlname:: Choosing the right file to `dlopen'. -* Dlopen issues:: Unresolved problems that need your attention. - -Using libltdl - -* Libltdl interface:: How to use libltdl in your programs. -* Modules for libltdl:: Creating modules that can be `dlopen'ed. -* Thread Safety in libltdl:: Registering callbacks for multi-thread safety. -* User defined module data:: Associating data with loaded modules. -* Module loaders for libltdl:: Creating user defined module loaders. -* Distributing libltdl:: How to distribute libltdl with your package. - -Frequently Asked Questions about libtool - -* Stripped link flags:: Dropped flags when creating a library - -Troubleshooting - -* Libtool test suite:: Libtool's self-tests. -* Reporting bugs:: How to report problems with libtool. - -The libtool test suite - -* Test descriptions:: The contents of the old test suite. -* When tests fail:: What to do when a test fails. - -Maintenance notes for libtool - -* New ports:: How to port libtool to new systems. -* Tested platforms:: When libtool was last tested. -* Platform quirks:: Information about different library systems. -* libtool script contents:: Configuration information that libtool uses. -* Cheap tricks:: Making libtool maintainership easier. - -Porting libtool to new systems - -* Information sources:: Where to find relevant documentation -* Porting inter-library dependencies:: Implementation details explained - -Platform quirks - -* References:: Finding more information. -* Compilers:: Creating object files from source files. -* Reloadable objects:: Binding object files together. -* Multiple dependencies:: Removing duplicate dependent libraries. -* Archivers:: Programs that create static archives. -* Cross compiling:: Issues that arise when cross compiling. -* File name conversion:: Converting file names between platforms. -* Windows DLLs:: Windows header defines. - -File name conversion - -* File Name Conversion Failure:: What happens when file name conversion fails -* Native MinGW File Name Conversion:: MSYS file name conversion idiosyncrasies -* Cygwin/Windows File Name Conversion:: Using `cygpath' to convert Cygwin file names -* Unix/Windows File Name Conversion:: Using Wine to convert Unix paths -* LT_CYGPATH:: Invoking `cygpath' from other environments -* Cygwin to MinGW Cross:: Other notes concerning MinGW cross - - -File: libtool.info, Node: Introduction, Next: Libtool paradigm, Prev: Top, Up: Top - -1 Introduction -************** - -In the past, if you were a source code package developer and wanted to -take advantage of the power of shared libraries, you needed to write -custom support code for each platform on which your package ran. You -also had to design a configuration interface so that the package -installer could choose what sort of libraries were built. - - GNU Libtool simplifies your job by encapsulating both the -platform-specific dependencies, and the user interface, in a single -script. GNU Libtool is designed so that the complete functionality of -each host type is available via a generic interface, but nasty quirks -are hidden from the programmer. - - GNU Libtool's consistent interface is reassuring... users don't need -to read obscure documentation in order to have their favorite source -package build shared libraries. They just run your package `configure' -script (or equivalent), and libtool does all the dirty work. - - There are several examples throughout this document. All assume the -same environment: we want to build a library, `libhello', in a generic -way. - - `libhello' could be a shared library, a static library, or both... -whatever is available on the host system, as long as libtool has been -ported to it. - - This chapter explains the original design philosophy of libtool. -Feel free to skip to the next chapter, unless you are interested in -history, or want to write code to extend libtool in a consistent way. - -* Menu: - -* Motivation:: Why does GNU need a libtool? -* Issues:: The problems that need to be addressed. -* Other implementations:: How other people have solved these issues. -* Postmortem:: Learning from past difficulties. - - -File: libtool.info, Node: Motivation, Next: Issues, Up: Introduction - -1.1 Motivation for writing libtool -================================== - -Since early 1995, several different GNU developers have recognized the -importance of having shared library support for their packages. The -primary motivation for such a change is to encourage modularity and -reuse of code (both conceptually and physically) in GNU programs. - - Such a demand means that the way libraries are built in GNU packages -needs to be general, to allow for any library type the package installer -might want. The problem is compounded by the absence of a standard -procedure for creating shared libraries on different platforms. - - The following sections outline the major issues facing shared library -support in GNU, and how shared library support could be standardized -with libtool. - - The following specifications were used in developing and evaluating -this system: - - 1. The system must be as elegant as possible. - - 2. The system must be fully integrated with the GNU Autoconf and - Automake utilities, so that it will be easy for GNU maintainers to - use. However, the system must not require these tools, so that it - can be used by non-GNU packages. - - 3. Portability to other (non-GNU) architectures and tools is - desirable. - - -File: libtool.info, Node: Issues, Next: Other implementations, Prev: Motivation, Up: Introduction - -1.2 Implementation issues -========================= - -The following issues need to be addressed in any reusable shared library -system, specifically libtool: - - 1. The package installer should be able to control what sort of - libraries are built. - - 2. It can be tricky to run dynamically linked programs whose - libraries have not yet been installed. `LD_LIBRARY_PATH' must be - set properly (if it is supported), or programs fail to run. - - 3. The system must operate consistently even on hosts that don't - support shared libraries. - - 4. The commands required to build shared libraries may differ wildly - from host to host. These need to be determined at configure time - in a consistent way. - - 5. It is not always obvious with what prefix or suffix a shared - library should be installed. This makes it difficult for - `Makefile' rules, since they generally assume that file names are - the same from host to host. - - 6. The system needs a simple library version number abstraction, so - that shared libraries can be upgraded in place. The programmer - should be informed how to design the interfaces to the library to - maximize binary compatibility. - - 7. The install `Makefile' target should warn the package installer to - set the proper environment variables (`LD_LIBRARY_PATH' or - equivalent), or run `ldconfig'. - - -File: libtool.info, Node: Other implementations, Next: Postmortem, Prev: Issues, Up: Introduction - -1.3 Other implementations -========================= - -Even before libtool was developed, many free software packages built and -installed their own shared libraries. At first, these packages were -examined to avoid reinventing existing features. - - Now it is clear that none of these packages have documented the -details of shared library systems that libtool requires. So, other -packages have been more or less abandoned as influences. - - -File: libtool.info, Node: Postmortem, Prev: Other implementations, Up: Introduction - -1.4 A postmortem analysis of other implementations -================================================== - -In all fairness, each of the implementations that were examined do the -job that they were intended to do, for a number of different host -systems. However, none of these solutions seem to function well as a -generalized, reusable component. - - Most were too complex to use (much less modify) without understanding -exactly what the implementation does, and they were generally not -documented. - - The main difficulty is that different vendors have different views of -what libraries are, and none of the packages that were examined seemed -to be confident enough to settle on a single paradigm that just _works_. - - Ideally, libtool would be a standard that would be implemented as -series of extensions and modifications to existing library systems to -make them work consistently. However, it is not an easy task to -convince operating system developers to mend their evil ways, and -people want to build shared libraries right now, even on buggy, broken, -confused operating systems. - - For this reason, libtool was designed as an independent shell script. -It isolates the problems and inconsistencies in library building that -plague `Makefile' writers by wrapping the compiler suite on different -platforms with a consistent, powerful interface. - - With luck, libtool will be useful to and used by the GNU community, -and that the lessons that were learned in writing it will be taken up by -designers of future library systems. - - -File: libtool.info, Node: Libtool paradigm, Next: Using libtool, Prev: Introduction, Up: Top - -2 The libtool paradigm -********************** - -At first, libtool was designed to support an arbitrary number of library -object types. After libtool was ported to more platforms, a new -paradigm gradually developed for describing the relationship between -libraries and programs. - - In summary, "libraries are programs with multiple entry points, and -more formally defined interfaces." - - Version 0.7 of libtool was a complete redesign and rewrite of -libtool to reflect this new paradigm. So far, it has proved to be -successful: libtool is simpler and more useful than before. - - The best way to introduce the libtool paradigm is to contrast it with -the paradigm of existing library systems, with examples from each. It -is a new way of thinking, so it may take a little time to absorb, but -when you understand it, the world becomes simpler. - - -File: libtool.info, Node: Using libtool, Next: Invoking libtool, Prev: Libtool paradigm, Up: Top - -3 Using libtool -*************** - -It makes little sense to talk about using libtool in your own packages -until you have seen how it makes your life simpler. The examples in -this chapter introduce the main features of libtool by comparing the -standard library building procedure to libtool's operation on two -different platforms: - -`a23' - An Ultrix 4.2 platform with only static libraries. - -`burger' - A NetBSD/i386 1.2 platform with shared libraries. - - You can follow these examples on your own platform, using the -preconfigured libtool script that was installed with libtool (*note -Configuring::). - - Source files for the following examples are taken from the `demo' -subdirectory of the libtool distribution. Assume that we are building a -library, `libhello', out of the files `foo.c' and `hello.c'. - - Note that the `foo.c' source file uses the `cos' math library -function, which is usually found in the standalone math library, and not -the C library (*note Trigonometric Functions: (libc)Trig Functions.). -So, we need to add `-lm' to the end of the link line whenever we link -`foo.lo' into an executable or a library (*note Inter-library -dependencies::). - - The same rule applies whenever you use functions that don't appear in -the standard C library... you need to add the appropriate `-lNAME' flag -to the end of the link line when you link against those objects. - - After we have built that library, we want to create a program by -linking `main.o' against `libhello'. - -* Menu: - -* Creating object files:: Compiling object files for libraries. -* Linking libraries:: Creating libraries from object files. -* Linking executables:: Linking object files against libtool libraries. -* Debugging executables:: Running GDB on libtool-generated programs. -* Installing libraries:: Making libraries available to users. -* Installing executables:: Making programs available to users. -* Static libraries:: When shared libraries are not wanted. - - -File: libtool.info, Node: Creating object files, Next: Linking libraries, Up: Using libtool - -3.1 Creating object files -========================= - -To create an object file from a source file, the compiler is invoked -with the `-c' flag (and any other desired flags): - - burger$ gcc -g -O -c main.c - burger$ - - The above compiler command produces an object file, usually named -`main.o', from the source file `main.c'. - - For most library systems, creating object files that become part of a -static library is as simple as creating object files that are linked to -form an executable: - - burger$ gcc -g -O -c foo.c - burger$ gcc -g -O -c hello.c - burger$ - - Shared libraries, however, may only be built from -"position-independent code" (PIC). So, special flags must be passed to -the compiler to tell it to generate PIC rather than the standard -position-dependent code. - - Since this is a library implementation detail, libtool hides the -complexity of PIC compiler flags and uses separate library object files -(the PIC one lives in the `.libs' subdirectory and the static one lives -in the current directory). On systems without shared libraries, the -PIC library object files are not created, whereas on systems where all -code is PIC, such as AIX, the static ones are not created. - - To create library object files for `foo.c' and `hello.c', simply -invoke libtool with the standard compilation command as arguments -(*note Compile mode::): - - a23$ libtool --mode=compile gcc -g -O -c foo.c - gcc -g -O -c foo.c -o foo.o - a23$ libtool --mode=compile gcc -g -O -c hello.c - gcc -g -O -c hello.c -o hello.o - a23$ - - Note that libtool silently creates an additional control file on each -`compile' invocation. The `.lo' file is the libtool object, which -Libtool uses to determine what object file may be built into a shared -library. On `a23', only static libraries are supported so the library -objects look like this: - - # foo.lo - a libtool object file - # Generated by ltmain.sh (GNU libtool) 2.4.2 - # - # Please DO NOT delete this file! - # It is necessary for linking the library. - - # Name of the PIC object. - pic_object=none - - # Name of the non-PIC object. - non_pic_object='foo.o' - - On shared library systems, libtool automatically generates an -additional PIC object by inserting the appropriate PIC generation flags -into the compilation command: - - burger$ libtool --mode=compile gcc -g -O -c foo.c - mkdir .libs - gcc -g -O -c foo.c -fPIC -DPIC -o .libs/foo.o - gcc -g -O -c foo.c -o foo.o >/dev/null 2>&1 - burger$ - - Note that Libtool automatically created `.libs' directory upon its -first execution, where PIC library object files will be stored. - - Since `burger' supports shared libraries, and requires PIC objects -to build them, Libtool has compiled a PIC object this time, and made a -note of it in the libtool object: - - # foo.lo - a libtool object file - # Generated by ltmain.sh (GNU libtool) 2.4.2 - # - # Please DO NOT delete this file! - # It is necessary for linking the library. - - # Name of the PIC object. - pic_object='.libs/foo.o' - - # Name of the non-PIC object. - non_pic_object='foo.o' - - Notice that the second run of GCC has its output discarded. This is -done so that compiler warnings aren't annoyingly duplicated. If you -need to see both sets of warnings (you might have conditional code -inside `#ifdef PIC' for example), you can turn off suppression with the -`-no-suppress' option to libtool's compile mode: - - burger$ libtool --mode=compile gcc -no-suppress -g -O -c hello.c - gcc -g -O -c hello.c -fPIC -DPIC -o .libs/hello.o - gcc -g -O -c hello.c -o hello.o - burger$ - - -File: libtool.info, Node: Linking libraries, Next: Linking executables, Prev: Creating object files, Up: Using libtool - -3.2 Linking libraries -===================== - -Without libtool, the programmer would invoke the `ar' command to create -a static library: - - burger$ ar cru libhello.a hello.o foo.o - burger$ - - But of course, that would be too simple, so many systems require that -you run the `ranlib' command on the resulting library (to give it -better karma, or something): - - burger$ ranlib libhello.a - burger$ - - It seems more natural to use the C compiler for this task, given -libtool's "libraries are programs" approach. So, on platforms without -shared libraries, libtool simply acts as a wrapper for the system `ar' -(and possibly `ranlib') commands. - - Again, the libtool control file name (`.la' suffix) differs from the -standard library name (`.a' suffix). The arguments to libtool are the -same ones you would use to produce an executable named `libhello.la' -with your compiler (*note Link mode::): - - a23$ libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o - *** Warning: Linking the shared library libhello.la against the - *** non-libtool objects foo.o hello.o is not portable! - ar cru .libs/libhello.a - ranlib .libs/libhello.a - creating libhello.la - (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) - a23$ - - Aha! Libtool caught a common error... trying to build a library -from standard objects instead of special `.lo' object files. This -doesn't matter so much for static libraries, but on shared library -systems, it is of great importance. (Note that you may replace -`libhello.la' with `libhello.a' in which case libtool won't issue the -warning any more. But although this method works, this is not intended -to be used because it makes you lose the benefits of using Libtool.) - - So, let's try again, this time with the library object files. -Remember also that we need to add `-lm' to the link command line because -`foo.c' uses the `cos' math library function (*note Using libtool::). - - Another complication in building shared libraries is that we need to -specify the path to the directory in which they (eventually) will be -installed (in this case, `/usr/local/lib')(1): - - a23$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ - -rpath /usr/local/lib -lm - ar cru .libs/libhello.a foo.o hello.o - ranlib .libs/libhello.a - creating libhello.la - (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) - a23$ - - Now, let's try the same trick on the shared library platform: - - burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ - -rpath /usr/local/lib -lm - rm -fr .libs/libhello.a .libs/libhello.la - ld -Bshareable -o .libs/libhello.so.0.0 .libs/foo.o .libs/hello.o -lm - ar cru .libs/libhello.a foo.o hello.o - ranlib .libs/libhello.a - creating libhello.la - (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) - burger$ - - Now that's significantly cooler... Libtool just ran an obscure `ld' -command to create a shared library, as well as the static library. - - Note how libtool creates extra files in the `.libs' subdirectory, -rather than the current directory. This feature is to make it easier -to clean up the build directory, and to help ensure that other programs -fail horribly if you accidentally forget to use libtool when you should. - - Again, you may want to have a look at the `.la' file in order to see -what Libtool stores in it. In particular, you will see that Libtool -uses this file to remember the destination directory for the library -(the argument to `-rpath') as well as the dependency on the math -library (`-lm'). - - ---------- Footnotes ---------- - - (1) If you don't specify an `rpath', then libtool builds a libtool -convenience archive, not a shared library (*note Static libraries::). - - -File: libtool.info, Node: Linking executables, Next: Debugging executables, Prev: Linking libraries, Up: Using libtool - -3.3 Linking executables -======================= - -If you choose at this point to "install" the library (put it in a -permanent location) before linking executables against it, then you -don't need to use libtool to do the linking. Simply use the appropriate -`-L' and `-l' flags to specify the library's location. - - Some system linkers insist on encoding the full directory name of -each shared library in the resulting executable. Libtool has to work -around this misfeature by special magic to ensure that only permanent -directory names are put into installed executables. - - The importance of this bug must not be overlooked: it won't cause -programs to crash in obvious ways. It creates a security hole, and -possibly even worse, if you are modifying the library source code after -you have installed the package, you will change the behaviour of the -installed programs! - - So, if you want to link programs against the library before you -install it, you must use libtool to do the linking. - - Here's the old way of linking against an uninstalled library: - - burger$ gcc -g -O -o hell.old main.o libhello.a -lm - burger$ - - Libtool's way is almost the same(1) (*note Link mode::): - - a23$ libtool --mode=link gcc -g -O -o hell main.o libhello.la - gcc -g -O -o hell main.o ./.libs/libhello.a -lm - a23$ - - That looks too simple to be true. All libtool did was transform -`libhello.la' to `./.libs/libhello.a', but remember that `a23' has no -shared libraries. Notice that Libtool also remembered that -`libhello.la' depends on `-lm', so even though we didn't specify `-lm' -on the libtool command line(2) Libtool has added it to the `gcc' link -line for us. - - On `burger' Libtool links against the uninstalled shared library: - - burger$ libtool --mode=link gcc -g -O -o hell main.o libhello.la - gcc -g -O -o .libs/hell main.o -L./.libs -R/usr/local/lib -lhello -lm - creating hell - burger$ - - Now assume `libhello.la' had already been installed, and you want to -link a new program with it. You could figure out where it lives by -yourself, then run: - - burger$ gcc -g -O -o test test.o -L/usr/local/lib -lhello -lm - - However, unless `/usr/local/lib' is in the standard library search -path, you won't be able to run `test'. However, if you use libtool to -link the already-installed libtool library, it will do The Right Thing -(TM) for you: - - burger$ libtool --mode=link gcc -g -O -o test test.o \ - /usr/local/lib/libhello.la - gcc -g -O -o .libs/test test.o -Wl,--rpath \ - -Wl,/usr/local/lib /usr/local/lib/libhello.a -lm - creating test - burger$ - - Note that libtool added the necessary run-time path flag, as well as -`-lm', the library libhello.la depended upon. Nice, huh? - - Notice that the executable, `hell', was actually created in the -`.libs' subdirectory. Then, a wrapper script (or, on certain -platforms, a wrapper executable *note Wrapper executables::) was -created in the current directory. - - Since libtool created a wrapper script, you should use libtool to -install it and debug it too. However, since the program does not depend -on any uninstalled libtool library, it is probably usable even without -the wrapper script. - - On NetBSD 1.2, libtool encodes the installation directory of -`libhello', by using the `-R/usr/local/lib' compiler flag. Then, the -wrapper script guarantees that the executable finds the correct shared -library (the one in `./.libs') until it is properly installed. - - Let's compare the two different programs: - - burger$ time ./hell.old - Welcome to GNU Hell! - ** This is not GNU Hello. There is no built-in mail reader. ** - 0.21 real 0.02 user 0.08 sys - burger$ time ./hell - Welcome to GNU Hell! - ** This is not GNU Hello. There is no built-in mail reader. ** - 0.63 real 0.09 user 0.59 sys - burger$ - - The wrapper script takes significantly longer to execute, but at -least the results are correct, even though the shared library hasn't -been installed yet. - - So, what about all the space savings that shared libraries are -supposed to yield? - - burger$ ls -l hell.old libhello.a - -rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old - -rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a - burger$ ls -l .libs/hell .libs/libhello.* - -rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 .libs/hell - -rw-r--r-- 1 gord gord 4274 Nov 13 18:44 .libs/libhello.a - -rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 .libs/libhello.so.0.0 - burger$ - - Well, that sucks. Maybe I should just scrap this project and take up -basket weaving. - - Actually, it just proves an important point: shared libraries incur -overhead because of their (relative) complexity. In this situation, the -price of being dynamic is eight kilobytes, and the payoff is about four -kilobytes. So, having a shared `libhello' won't be an advantage until -we link it against at least a few more programs. - -* Menu: - -* Wrapper executables:: Wrapper executables for some platforms. - - ---------- Footnotes ---------- - - (1) However, you should avoid using `-L' or `-l' flags to link -against an uninstalled libtool library. Just specify the relative path -to the `.la' file, such as `../intl/libintl.la'. This is a design -decision to eliminate any ambiguity when linking against uninstalled -shared libraries. - - (2) And why should we? `main.o' doesn't directly depend on `-lm' -after all. - - -File: libtool.info, Node: Wrapper executables, Up: Linking executables - -3.3.1 Wrapper executables for uninstalled programs --------------------------------------------------- - -Some platforms, notably those hosted on Windows such as Cygwin and -MinGW, use a wrapper executable rather than a wrapper script to ensure -proper operation of uninstalled programs linked by libtool against -uninstalled shared libraries. The wrapper executable thus performs the -same function as the wrapper script used on other platforms, but allows -to satisfy the `make' rules for the program, whose name ends in -`$(EXEEXT)'. The actual program executable is created below .libs, and -its name will end in `$(EXEEXT)' and may or may not contain an `lt-' -prefix. This wrapper executable sets various environment values so -that the program executable may locate its (uninstalled) shared -libraries, and then launches the program executable. - - The wrapper executable provides a debug mode, enabled by passing the -command-line option `--lt-debug' (see below). When executing in debug -mode, diagnostic information will be printed to `stderr' before the -program executable is launched. - - Finally, the wrapper executable supports a number of command line -options that may be useful when debugging the operation of the wrapper -system. All of these options begin with `--lt-', and if present they -and their arguments will be removed from the argument list passed on to -the program executable. Therefore, the program executable may not -employ command line options that begin with `--lt-'. (In fact, the -wrapper executable will detect any command line options that begin with -`--lt-' and abort with an error message if the option is not -recognized). If this presents a problem, please contact the Libtool -team at the Libtool bug reporting address <bug-libtool@gnu.org>. - - These command line options include: - -`--lt-dump-script' - Causes the wrapper to print a copy of the wrapper _script_ to - `stdout', and exit. - -`--lt-debug' - Causes the wrapper to print diagnostic information to `stdout', - before launching the program executable. - - - For consistency, both the wrapper _script_ and the wrapper -_executable_ support these options. - - -File: libtool.info, Node: Debugging executables, Next: Installing libraries, Prev: Linking executables, Up: Using libtool - -3.4 Debugging executables -========================= - -If `hell' was a complicated program, you would certainly want to test -and debug it before installing it on your system. In the above -section, you saw how the libtool wrapper script makes it possible to run -the program directly, but unfortunately, this mechanism interferes with -the debugger: - - burger$ gdb hell - GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. - There is no warranty for GDB; type "show warranty" for details. - GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. - - "hell": not in executable format: File format not recognized - - (gdb) quit - burger$ - - Sad. It doesn't work because GDB doesn't know where the executable -lives. So, let's try again, by invoking GDB directly on the executable: - - burger$ gdb .libs/hell - GNU gdb 5.3 (i386-unknown-netbsd) - Copyright 2002 Free Software Foundation, Inc. - GDB is free software, covered by the GNU General Public License, - and you are welcome to change it and/or distribute copies of it - under certain conditions. Type "show copying" to see the conditions. - There is no warranty for GDB. Type "show warranty" for details. - (gdb) break main - Breakpoint 1 at 0x8048547: file main.c, line 29. - (gdb) run - Starting program: /home/src/libtool/demo/.libs/hell - /home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.0' - - Program exited with code 020. - (gdb) quit - burger$ - - Argh. Now GDB complains because it cannot find the shared library -that `hell' is linked against. So, we must use libtool in order to -properly set the library path and run the debugger. Fortunately, we can -forget all about the `.libs' directory, and just run it on the -executable wrapper (*note Execute mode::): - - burger$ libtool --mode=execute gdb hell - GNU gdb 5.3 (i386-unknown-netbsd) - Copyright 2002 Free Software Foundation, Inc. - GDB is free software, covered by the GNU General Public License, - and you are welcome to change it and/or distribute copies of it - under certain conditions. Type "show copying" to see the conditions. - There is no warranty for GDB. Type "show warranty" for details. - (gdb) break main - Breakpoint 1 at 0x8048547: file main.c, line 29. - (gdb) run - Starting program: /home/src/libtool/demo/.libs/hell - - Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29 - 29 printf ("Welcome to GNU Hell!\n"); - (gdb) quit - The program is running. Quit anyway (and kill it)? (y or n) y - burger$ - - -File: libtool.info, Node: Installing libraries, Next: Installing executables, Prev: Debugging executables, Up: Using libtool - -3.5 Installing libraries -======================== - -Installing libraries on a non-libtool system is quite -straightforward... just copy them into place:(1) - - burger$ su - Password: ******** - burger# cp libhello.a /usr/local/lib/libhello.a - burger# - - Oops, don't forget the `ranlib' command: - - burger# ranlib /usr/local/lib/libhello.a - burger# - - Libtool installation is quite simple, as well. Just use the -`install' or `cp' command that you normally would (*note Install -mode::): - - a23# libtool --mode=install cp libhello.la /usr/local/lib/libhello.la - cp libhello.la /usr/local/lib/libhello.la - cp .libs/libhello.a /usr/local/lib/libhello.a - ranlib /usr/local/lib/libhello.a - a23# - - Note that the libtool library `libhello.la' is also installed, to -help libtool with uninstallation (*note Uninstall mode::) and linking -(*note Linking executables::) and to help programs with dlopening -(*note Dlopened modules::). - - Here is the shared library example: - - burger# libtool --mode=install install -c libhello.la \ - /usr/local/lib/libhello.la - install -c .libs/libhello.so.0.0 /usr/local/lib/libhello.so.0.0 - install -c libhello.la /usr/local/lib/libhello.la - install -c .libs/libhello.a /usr/local/lib/libhello.a - ranlib /usr/local/lib/libhello.a - burger# - - It is safe to specify the `-s' (strip symbols) flag if you use a -BSD-compatible install program when installing libraries. Libtool will -either ignore the `-s' flag, or will run a program that will strip only -debugging and compiler symbols from the library. - - Once the libraries have been put in place, there may be some -additional configuration that you need to do before using them. First, -you must make sure that where the library is installed actually agrees -with the `-rpath' flag you used to build it. - - Then, running `libtool -n finish LIBDIR' can give you further hints -on what to do (*note Finish mode::): - - burger# libtool -n finish /usr/local/lib - PATH="$PATH:/sbin" ldconfig -m /usr/local/lib - ----------------------------------------------------------------- - Libraries have been installed in: - /usr/local/lib - - To link against installed libraries in a given directory, LIBDIR, - you must use the `-LLIBDIR' flag during linking. - - You will also need to do one of the following: - - add LIBDIR to the `LD_LIBRARY_PATH' environment variable - during execution - - add LIBDIR to the `LD_RUN_PATH' environment variable - during linking - - use the `-RLIBDIR' linker flag - - See any operating system documentation about shared libraries for - more information, such as the ld and ld.so manual pages. - ----------------------------------------------------------------- - burger# - - After you have completed these steps, you can go on to begin using -the installed libraries. You may also install any executables that -depend on libraries you created. - - ---------- Footnotes ---------- - - (1) Don't strip static libraries though, or they will be unusable. - - -File: libtool.info, Node: Installing executables, Next: Static libraries, Prev: Installing libraries, Up: Using libtool - -3.6 Installing executables -========================== - -If you used libtool to link any executables against uninstalled libtool -libraries (*note Linking executables::), you need to use libtool to -install the executables after the libraries have been installed (*note -Installing libraries::). - - So, for our Ultrix example, we would run: - - a23# libtool --mode=install -c hell /usr/local/bin/hell - install -c hell /usr/local/bin/hell - a23# - - On shared library systems that require wrapper scripts, libtool just -ignores the wrapper script and installs the correct binary: - - burger# libtool --mode=install -c hell /usr/local/bin/hell - install -c .libs/hell /usr/local/bin/hell - burger# - - -File: libtool.info, Node: Static libraries, Prev: Installing executables, Up: Using libtool - -3.7 Linking static libraries -============================ - -Why return to `ar' and `ranlib' silliness when you've had a taste of -libtool? Well, sometimes it is desirable to create a static archive -that can never be shared. The most frequent case is when you have a -set of object files that you use to build several different libraries. -You can create a "convenience library" out of those objects, and link -against that with the other libraries, instead of listing all the -object files every time. - - If you just want to link this convenience library into programs, then -you could just ignore libtool entirely, and use the old `ar' and -`ranlib' commands (or the corresponding GNU Automake `_LIBRARIES' -rules). You can even install a convenience library using GNU Libtool, -though you probably don't want to and hence GNU Automake doesn't allow -you to do so. - - burger$ libtool --mode=install ./install-sh -c libhello.a \ - /local/lib/libhello.a - ./install-sh -c libhello.a /local/lib/libhello.a - ranlib /local/lib/libhello.a - burger$ - - Using libtool for static library installation protects your library -from being accidentally stripped (if the installer used the `-s' flag), -as well as automatically running the correct `ranlib' command. - - But libtool libraries are more than just collections of object files: -they can also carry library dependency information, which old archives -do not. If you want to create a libtool static convenience library, you -can omit the `-rpath' flag and use `-static' to indicate that you're -only interested in a static library. When you link a program with such -a library, libtool will actually link all object files and dependency -libraries into the program. - - If you omit both `-rpath' and `-static', libtool will create a -convenience library that can be used to create other libtool libraries, -even shared ones. Just like in the static case, the library behaves as -an alias to a set of object files and dependency libraries, but in this -case the object files are suitable for inclusion in shared libraries. -But be careful not to link a single convenience library, directly or -indirectly, into a single program or library, otherwise you may get -errors about symbol redefinitions. - - The key is remembering that a convenience library contains PIC -objects, and can be linked where a list of PIC objects makes sense; -i.e. into a shared library. A static convenience library contains -non-PIC objects, so can be linked into an old static library, or a -program. - - When GNU Automake is used, you should use `noinst_LTLIBRARIES' -instead of `lib_LTLIBRARIES' for convenience libraries, so that the -`-rpath' option is not passed when they are linked. - - As a rule of thumb, link a libtool convenience library into at most -one libtool library, and never into a program, and link libtool static -convenience libraries only into programs, and only if you need to carry -library dependency information to the user of the static convenience -library. - - Another common situation where static linking is desirable is in -creating a standalone binary. Use libtool to do the linking and add the -`-all-static' flag. - - -File: libtool.info, Node: Invoking libtool, Next: Integrating libtool, Prev: Using libtool, Up: Top - -4 Invoking `libtool' -******************** - -The `libtool' program has the following synopsis: - - libtool [OPTION]... [MODE-ARG]... - -and accepts the following options: - -`--config' - Display libtool configuration variables and exit. - -`--debug' - Dump a trace of shell script execution to standard output. This - produces a lot of output, so you may wish to pipe it to `less' (or - `more') or redirect to a file. - -`-n' -`--dry-run' - Don't create, modify, or delete any files, just show what commands - would be executed by libtool. - -`--features' - Display basic configuration options. This provides a way for - packages to determine whether shared or static libraries will be - built. - -`--finish' - Same as `--mode=finish'. - -`-h' - Display short help message. - -`--help' - Display a help message and exit. If `--mode=MODE' is specified, - then detailed help for MODE is displayed. - -`--help-all' - Display help for the general options as well as detailed help for - each operation mode, and exit. - -`--mode=MODE' - Use MODE as the operation mode. When using libtool from the - command line, you can give just MODE (or a unique abbreviation of - it) as the first argument as a shorthand for the full - `--mode=MODE'. For example, the following are equivalent: - - $ libtool --mode=execute --dry-run gdb prog.exe - $ libtool execute --dry-run gdb prog.exe - $ libtool exe --dry-run gdb prog.exe - $ libtool e --dry-run gdb prog.exe - - MODE must be set to one of the following: - - `compile' - Compile a source file into a libtool object. - - `execute' - Automatically set the library path so that another program - can use uninstalled libtool-generated programs or libraries. - - `link' - Create a library or an executable. - - `install' - Install libraries or executables. - - `finish' - Complete the installation of libtool libraries on the system. - - `uninstall' - Delete installed libraries or executables. - - `clean' - Delete uninstalled libraries or executables. - -`--tag=TAG' - Use configuration variables from tag TAG (*note Tags::). - -`--preserve-dup-deps' - Do not remove duplicate dependencies in libraries. When building - packages with static libraries, the libraries may depend - circularly on each other (shared libs can too, but for those it - doesn't matter), so there are situations, where -la -lb -la is - required, and the second -la may not be stripped or the link will - fail. In cases where these duplications are required, this option - will preserve them, only stripping the libraries that libtool - knows it can safely. - -`--quiet' -`--silent' - Do not print out any progress or informational messages. - -`-v' -`--verbose' - Print out progress and informational messages (enabled by default), - as well as additional messages not ordinary seen by default. - -`--no-quiet' -`--no-silent' - Print out the progress and informational messages that are seen by - default. This option has no effect on whether the additional - messages seen in `--verbose' mode are shown. - -`--no-verbose' - Do not print out any additional informational messages beyond - those ordinarily seen by default. This option has no effect on - whether the ordinary progress and informational messages enabled - by `--no-quiet' are shown. - - Thus, there are now three different message levels (not counting - `--debug'), depending on whether the normal messages and/or the - additional verbose messages are displayed. Note that there is no - mechanism to diplay verbose messages, without also displaying - normal messages. - - *default* - Normal messages are displayed, verbose messages are not - displayed. In addition to being the default mode, it can be - forcibly achieved by using both option `--no-verbose' and - either option `--no-silent' or option `--no-quiet'. - - *silent* - Neither normal messages nor verbose messages are displayed. - This mode can be achieved using either option `--silent' or - option `--quiet'. - - *verbose* - Both normal messages and verbose messages are displayed. This - mode can be achieved using either option `-v' or option - `--verbose'. - -`--version' - Print libtool version information and exit. - - The current `libtool' implementation is done with a shell script -that needs to be invoked by the shell which `configure' chose for -configuring `libtool' (*note The Autoconf Manual: -(autoconf)config.status Invocation.). This shell is set in the -she-bang (`#!') line of the `libtool' script. Using a different shell -may cause undefined behavior. - - The MODE-ARGS are a variable number of arguments, depending on the -selected operation mode. In general, each MODE-ARG is interpreted by -programs libtool invokes, rather than libtool itself. - -* Menu: - -* Compile mode:: Creating library object files. -* Link mode:: Generating executables and libraries. -* Execute mode:: Debugging libtool-generated programs. -* Install mode:: Making libraries and executables public. -* Finish mode:: Completing a library installation. -* Uninstall mode:: Removing installed executables and libraries. -* Clean mode:: Removing uninstalled executables and libraries. - - -File: libtool.info, Node: Compile mode, Next: Link mode, Up: Invoking libtool - -4.1 Compile mode -================ - -For "compile" mode, MODE-ARGS is a compiler command to be used in -creating a "standard" object file. These arguments should begin with -the name of the C compiler, and contain the `-c' compiler flag so that -only an object file is created. - - Libtool determines the name of the output file by removing the -directory component from the source file name, then substituting the -source code suffix (e.g. `.c' for C source code) with the library -object suffix, `.lo'. - - If shared libraries are being built, any necessary PIC generation -flags are substituted into the compilation command. - - The following components of MODE-ARGS are treated specially: - -`-o' - Note that the `-o' option is now fully supported. It is emulated - on the platforms that don't support it (by locking and moving the - objects), so it is really easy to use libtool, just with minor - modifications to your Makefiles. Typing for example - libtool --mode=compile gcc -c foo/x.c -o foo/x.lo - will do what you expect. - - Note, however, that, if the compiler does not support `-c' and - `-o', it is impossible to compile `foo/x.c' without overwriting an - existing `./x.o'. Therefore, if you do have a source file - `./x.c', make sure you introduce dependencies in your `Makefile' - to make sure `./x.o' (or `./x.lo') is re-created after any - sub-directory's `x.lo': - - x.o x.lo: foo/x.lo bar/x.lo - - This will also ensure that make won't try to use a temporarily - corrupted `x.o' to create a program or library. It may cause - needless recompilation on platforms that support `-c' and `-o' - together, but it's the only way to make it safe for those that - don't. - -`-no-suppress' - If both PIC and non-PIC objects are being built, libtool will - normally suppress the compiler output for the PIC object - compilation to save showing very similar, if not identical - duplicate output for each object. If the `-no-suppress' option is - given in compile mode, libtool will show the compiler output for - both objects. - -`-prefer-pic' - Libtool will try to build only PIC objects. - -`-prefer-non-pic' - Libtool will try to build only non-PIC objects. - -`-shared' - Even if Libtool was configured with `--enable-static', the object - file Libtool builds will not be suitable for static linking. - Libtool will signal an error if it was configured with - `--disable-shared', or if the host does not support shared - libraries. - -`-static' - Even if libtool was configured with `--disable-static', the object - file Libtool builds *will* be suitable for static linking. - -`-Wc,FLAG' -`-Xcompiler FLAG' - Pass a flag directly to the compiler. With `-Wc,', multiple flags - may be separated by commas, whereas `-Xcompiler ' passes through - commas unchanged. - - -File: libtool.info, Node: Link mode, Next: Execute mode, Prev: Compile mode, Up: Invoking libtool - -4.2 Link mode -============= - -"Link" mode links together object files (including library objects) to -form another library or to create an executable program. - - MODE-ARGS consist of a command using the C compiler to create an -output file (with the `-o' flag) from several object files. - - The following components of MODE-ARGS are treated specially: - -`-all-static' - If OUTPUT-FILE is a program, then do not link it against any - shared libraries at all. If OUTPUT-FILE is a library, then only - create a static library. In general, this flag cannot be used - together with `disable-static' (*note LT_INIT::). - -`-avoid-version' - Tries to avoid versioning (*note Versioning::) for libraries and - modules, i.e. no version information is stored and no symbolic - links are created. If the platform requires versioning, this - option has no effect. - -`-bindir' - Pass the absolute name of the directory for installing executable - programs (*note Directory Variables: (standards)Directory - Variables.). `libtool' may use this value to install shared - libraries there on systems that do not provide for any library - hardcoding and use the directory of a program and the `PATH' - variable as library search path. This is typically used for DLLs - on Windows or other systems using the PE (Portable Executable) - format. On other systems, `-bindir' is ignored. The default - value used is `LIBDIR/../bin' for libraries installed to `LIBDIR'. - You should not use `-bindir' for modules. - -`-dlopen FILE' - Same as `-dlpreopen FILE', if native dlopening is not supported on - the host platform (*note Dlopened modules::) or if the program is - linked with `-static', `-static-libtool-libs', or `-all-static'. - Otherwise, no effect. If FILE is `self' Libtool will make sure - that the program can `dlopen' itself, either by enabling - `-export-dynamic' or by falling back to `-dlpreopen self'. - -`-dlpreopen FILE' - Link FILE into the output program, and add its symbols to the list - of preloaded symbols (*note Dlpreopening::). If FILE is `self', - the symbols of the program itself will be added to preloaded - symbol lists. If FILE is `force' Libtool will make sure that a - preloaded symbol list is always _defined_, regardless of whether - it's empty or not. - -`-export-dynamic' - Allow symbols from OUTPUT-FILE to be resolved with `dlsym' (*note - Dlopened modules::). - -`-export-symbols SYMFILE' - Tells the linker to export only the symbols listed in SYMFILE. - The symbol file should end in `.sym' and must contain the name of - one symbol per line. This option has no effect on some platforms. - By default all symbols are exported. - -`-export-symbols-regex REGEX' - Same as `-export-symbols', except that only symbols matching the - regular expression REGEX are exported. By default all symbols are - exported. - -`-LLIBDIR' - Search LIBDIR for required libraries that have already been - installed. - -`-lNAME' - OUTPUT-FILE requires the installed library `libNAME'. This option - is required even when OUTPUT-FILE is not an executable. - -`-module' - Creates a library that can be dlopened (*note Dlopened modules::). - This option doesn't work for programs. Module names don't need to - be prefixed with `lib'. In order to prevent name clashes, - however, `libNAME' and `NAME' must not be used at the same time in - your package. - -`-no-fast-install' - Disable fast-install mode for the executable OUTPUT-FILE. Useful - if the program won't be necessarily installed. - -`-no-install' - Link an executable OUTPUT-FILE that can't be installed and - therefore doesn't need a wrapper script on systems that allow - hardcoding of library paths. Useful if the program is only used - in the build tree, e.g., for testing or generating other files. - -`-no-undefined' - Declare that OUTPUT-FILE does not depend on any libraries other - than the ones listed on the command line, i.e., after linking, it - will not have unresolved symbols. Some platforms require all - symbols in shared libraries to be resolved at library creation - (*note Inter-library dependencies::), and using this parameter - allows `libtool' to assume that this will not happen. - -`-o OUTPUT-FILE' - Create OUTPUT-FILE from the specified objects and libraries. - -`-objectlist FILE' - Use a list of object files found in FILE to specify objects. - -`-precious-files-regex REGEX' - Prevents removal of files from the temporary output directory whose - names match this regular expression. You might specify `\.bbg?$' - to keep those files created with `gcc -ftest-coverage' for example. - -`-release RELEASE' - Specify that the library was generated by release RELEASE of your - package, so that users can easily tell which versions are newer - than others. Be warned that no two releases of your package will - be binary compatible if you use this flag. If you want binary - compatibility, use the `-version-info' flag instead (*note - Versioning::). - -`-rpath LIBDIR' - If OUTPUT-FILE is a library, it will eventually be installed in - LIBDIR. If OUTPUT-FILE is a program, add LIBDIR to the run-time - path of the program. On platforms that don't support hardcoding - library paths into executables and only search PATH for shared - libraries, such as when OUTPUT-FILE is a Windows (or other PE - platform) DLL, the `.la' control file will be installed in LIBDIR, - but see `-bindir' above for the eventual destination of the `.dll' - or other library file itself. - -`-R LIBDIR' - If OUTPUT-FILE is a program, add LIBDIR to its run-time path. If - OUTPUT-FILE is a library, add `-RLIBDIR' to its DEPENDENCY_LIBS, - so that, whenever the library is linked into a program, LIBDIR - will be added to its run-time path. - -`-shared' - If OUTPUT-FILE is a program, then link it against any uninstalled - shared libtool libraries (this is the default behavior). If - OUTPUT-FILE is a library, then only create a shared library. In - the later case, libtool will signal an error if it was configured - with `--disable-shared', or if the host does not support shared - libraries. - -`-shrext SUFFIX' - If OUTPUT-FILE is a libtool library, replace the system's standard - file name extension for shared libraries with SUFFIX (most systems - use `.so' here). This option is helpful in certain cases where an - application requires that shared libraries (typically modules) - have an extension other than the default one. Please note you - must supply the full file name extension including any leading dot. - -`-static' - If OUTPUT-FILE is a program, then do not link it against any - uninstalled shared libtool libraries. If OUTPUT-FILE is a - library, then only create a static library. - -`-static-libtool-libs' - If OUTPUT-FILE is a program, then do not link it against any - shared libtool libraries. If OUTPUT-FILE is a library, then only - create a static library. - -`-version-info CURRENT[:REVISION[:AGE]]' - If OUTPUT-FILE is a libtool library, use interface version - information CURRENT, REVISION, and AGE to build it (*note - Versioning::). Do *not* use this flag to specify package release - information, rather see the `-release' flag. - -`-version-number MAJOR[:MINOR[:REVISION]]' - If OUTPUT-FILE is a libtool library, compute interface version - information so that the resulting library uses the specified - major, minor and revision numbers. This is designed to permit - libtool to be used with existing projects where identical version - numbers are already used across operating systems. New projects - should use the `-version-info' flag instead. - -`-weak LIBNAME' - if OUTPUT-FILE is a libtool library, declare that it provides a - weak LIBNAME interface. This is a hint to libtool that there is - no need to append LIBNAME to the list of dependency libraries of - OUTPUT-FILE, because linking against OUTPUT-FILE already supplies - the same interface (*note Linking with dlopened modules::). - -`-Wc,FLAG' -`-Xcompiler FLAG' - Pass a linker-specific flag directly to the compiler. With `-Wc,', - multiple flags may be separated by commas, whereas `-Xcompiler ' - passes through commas unchanged. - -`-Wl,FLAG' -`-Xlinker FLAG' - Pass a linker-specific flag directly to the linker. - -`-XCClinker FLAG' - Pass a link-specific flag to the compiler driver (`CC') during - linking. - - If the OUTPUT-FILE ends in `.la', then a libtool library is created, -which must be built only from library objects (`.lo' files). The -`-rpath' option is required. In the current implementation, libtool -libraries may not depend on other uninstalled libtool libraries (*note -Inter-library dependencies::). - - If the OUTPUT-FILE ends in `.a', then a standard library is created -using `ar' and possibly `ranlib'. - - If OUTPUT-FILE ends in `.o' or `.lo', then a reloadable object file -is created from the input files (generally using `ld -r'). This method -is often called "partial linking". - - Otherwise, an executable program is created. - - -File: libtool.info, Node: Execute mode, Next: Install mode, Prev: Link mode, Up: Invoking libtool - -4.3 Execute mode -================ - -For "execute" mode, the library path is automatically set, then a -program is executed. - - The first of the MODE-ARGS is treated as a program name, with the -rest as arguments to that program. - - The following components of MODE-ARGS are treated specially: - -`-dlopen FILE' - Add the directory containing FILE to the library path. - - This mode sets the library path environment variable according to any -`-dlopen' flags. - - If any of the ARGS are libtool executable wrappers, then they are -translated into the name of their corresponding uninstalled binary, and -any of their required library directories are added to the library path. - - -File: libtool.info, Node: Install mode, Next: Finish mode, Prev: Execute mode, Up: Invoking libtool - -4.4 Install mode -================ - -In "install" mode, libtool interprets most of the elements of MODE-ARGS -as an installation command beginning with `cp', or a BSD-compatible -`install' program. - - The following components of MODE-ARGS are treated specially: - -`-inst-prefix-dir INST-PREFIX-DIR' - When installing into a temporary staging area, rather than the - final `prefix', this argument is used to reflect the temporary - path, in much the same way `automake' uses `DESTDIR'. For - instance, if `prefix' is `/usr/local', but INST-PREFIX-DIR is - `/tmp', then the object will be installed under `/tmp/usr/local/'. - If the installed object is a libtool library, then the internal - fields of that library will reflect only `prefix', not - INST-PREFIX-DIR: - - # Directory that this library needs to be installed in: - libdir='/usr/local/lib' - - not - - # Directory that this library needs to be installed in: - libdir='/tmp/usr/local/lib' - - `inst-prefix' is also used to insure that if the installed object - must be relinked upon installation, that it is relinked against - the libraries in INST-PREFIX-DIR/`prefix', not `prefix'. - - In truth, this option is not really intended for use when calling - libtool directly; it is automatically used when `libtool - --mode=install' calls `libtool --mode=relink'. Libtool does this - by analyzing the destination path given in the original `libtool - --mode=install' command and comparing it to the expected - installation path established during `libtool --mode=link'. - - Thus, end-users need change nothing, and `automake'-style `make - install DESTDIR=/tmp' will Just Work(tm) most of the time. For - systems where fast installation can not be turned on, relinking - may be needed. In this case, a `DESTDIR' install will fail. - - Currently it is not generally possible to install into a temporary - staging area that contains needed third-party libraries which are - not yet visible at their final location. - - The rest of the MODE-ARGS are interpreted as arguments to the `cp' -or `install' command. - - The command is run, and any necessary unprivileged post-installation -commands are also completed. - - -File: libtool.info, Node: Finish mode, Next: Uninstall mode, Prev: Install mode, Up: Invoking libtool - -4.5 Finish mode -=============== - -"Finish" mode has two functions. One is to help system administrators -install libtool libraries so that they can be located and linked into -user programs. To invoke this functionality, pass the name of a library -directory as MODE-ARG. Running this command may require superuser -privileges, and the `--dry-run' option may be useful. - - The second is to facilitate transferring libtool libraries to a -native compilation environment after they were built in a -cross-compilation environment. Cross-compilation environments may rely -on recent libtool features, and running libtool in finish mode will -make it easier to work with older versions of libtool. This task is -performed whenever the MODE-ARG is a `.la' file. - - -File: libtool.info, Node: Uninstall mode, Next: Clean mode, Prev: Finish mode, Up: Invoking libtool - -4.6 Uninstall mode -================== - -"Uninstall" mode deletes installed libraries, executables and objects. - - The first MODE-ARG is the name of the program to use to delete files -(typically `/bin/rm'). - - The remaining MODE-ARGS are either flags for the deletion program -(beginning with a `-'), or the names of files to delete. - - -File: libtool.info, Node: Clean mode, Prev: Uninstall mode, Up: Invoking libtool - -4.7 Clean mode -============== - -"Clean" mode deletes uninstalled libraries, executables, objects and -libtool's temporary files associated with them. - - The first MODE-ARG is the name of the program to use to delete files -(typically `/bin/rm'). - - The remaining MODE-ARGS are either flags for the deletion program -(beginning with a `-'), or the names of files to delete. - - -File: libtool.info, Node: Integrating libtool, Next: Other languages, Prev: Invoking libtool, Up: Top - -5 Integrating libtool with your package -*************************************** - -This chapter describes how to integrate libtool with your packages so -that your users can install hassle-free shared libraries. - - There are several ways in which Libtool may be integrated in your -package, described in the following sections. Typically, the Libtool -macro files as well as `ltmain.sh' are copied into your package using -`libtoolize' and `aclocal' after setting up the `configure.ac' and -toplevel `Makefile.am', then `autoconf' adds the needed tests to the -`configure' script. These individual steps are often automated with -`autoreconf'. - - Here is a diagram showing how such a typical Libtool configuration -works when preparing a package for distribution, assuming that `m4' has -been chosen as location for additional Autoconf macros, and `build-aux' -as location for auxiliary build tools (*note The Autoconf Manual: -(autoconf)Input.): - - libtool.m4 -----. .--> aclocal.m4 -----. - ltoptions.m4 ---+ .-> aclocal* -+ +--> autoconf* - ltversion.m4 ---+--+ `--> [copy in m4/] --+ | - ltsugar.m4 -----+ | ^ | \/ - lt~obsolete.m4 -+ +-> libtoolize* -----' | configure - [ltdl.m4] ------+ | | - `----------------------------------' - - ltmain.sh -----------> libtoolize* -> [copy in build-aux/] - - During configuration, the `libtool' script is generated either -through `config.status' or `config.lt': - - .--> config.status* --. - configure* --+ +--> libtool - `--> [config.lt*] ----' ^ - | - ltmain.sh --------------------------------' - - At `make' run time, `libtool' is then invoked as needed as a wrapper -around compilers, linkers, install and cleanup programs. - - There are alternatives choices to several parts of the setup; for -example, the Libtool macro files can either be copied or symlinked into -the package, or copied into `aclocal.m4'. As another example, an -external, pre-configured `libtool' script may be used, by-passing most -of the tests and package-specific setup for Libtool. - -* Menu: - -* Autoconf macros:: Autoconf macros exported by libtool. -* Makefile rules:: Writing `Makefile' rules for libtool. -* Using Automake:: Automatically supporting libtool. -* Configuring:: Configuring libtool for a host system. -* Distributing:: What files to distribute with your package. -* Static-only libraries:: Sometimes shared libraries are just a pain. - - -File: libtool.info, Node: Autoconf macros, Next: Makefile rules, Up: Integrating libtool - -5.1 Autoconf macros exported by libtool -======================================= - -Libtool uses a number of macros to interrogate the host system when it -is being built, and you can use some of them yourself too. Although -there are a great many other macros in the libtool installed m4 files, -these do not form part of the published interface, and are subject to -change between releases. - -Macros in the `LT_CMD_' namespace check for various shell commands: - - -- Macro: LT_CMD_MAX_LEN - Finds the longest command line that can be safely passed to - `$SHELL' without being truncated, and store in the shell variable - `$max_cmd_len'. It is only an approximate value, but command - lines of this length or shorter are guaranteed not to be truncated. - -Macros in the `LT_FUNC_' namespace check characteristics of library -functions: - - -- Macro: LT_FUNC_DLSYM_USCORE - `AC_DEFINE' the preprocessor symbol `DLSYM_USCORE' if we have to - add an underscore to symbol-names passed in to `dlsym'. - -Macros in the `LT_LIB_' namespace check characteristics of system -libraries: - - -- Macro: LT_LIB_M - Set `LIBM' to the math library or libraries required on this - machine, if any. - - -- Macro: LT_LIB_DLLOAD - This is the macro used by `libltdl' to determine which dlloaders - to use on this machine, if any. Several shell variables are set - (and `AC_SUBST'ed) depending on the dlload interfaces are - available on this machine. `LT_DLLOADERS' contains a list of - libtool libraries that can be used, and if necessary also sets - `LIBADD_DLOPEN' if additional system libraries are required by the - `dlopen' loader, and `LIBADD_SHL_LOAD' if additional system - libraries are required by the `shl_load' loader, respectively. - Finally some symbols are set in `config.h' depending on the - loaders that are found to work: `HAVE_LIBDL', `HAVE_SHL_LOAD', - `HAVE_DYLD', `HAVE_DLD'. - -Macros in the `LT_PATH_' namespace search the system for the full path -to particular system commands: - - -- Macro: LT_PATH_LD - Add a `--with-gnu-ld' option to `configure'. Try to find the path - to the linker used by `$CC', and whether it is the GNU linker. - The result is stored in the shell variable `$LD', which is - `AC_SUBST'ed. - - -- Macro: LT_PATH_NM - Try to find a BSD-compatible `nm' or a MS-compatible `dumpbin' - command on this machine. The result is stored in the shell - variable `$NM', which is `AC_SUBST'ed. - -Macros in the `LT_SYS_' namespace probe for system characteristics: - - -- Macro: LT_SYS_DLOPEN_SELF - Tests whether a program can dlopen itself, and then also whether - the same program can still dlopen itself when statically linked. - Results are stored in the shell variables `$enable_dlopen_self' and - `enable_dlopen_self_static' respectively. - - -- Macro: LT_SYS_DLOPEN_DEPLIBS - Define the preprocessor symbol `LTDL_DLOPEN_DEPLIBS' if the OS - needs help to load dependent libraries for `dlopen' (or - equivalent). - - -- Macro: LT_SYS_DLSEARCH_PATH - Define the preprocessor symbol `LT_DLSEARCH_PATH' to the system - default library search path. - - -- Macro: LT_SYS_MODULE_EXT - Define the preprocessor symbol `LT_MODULE_EXT' to the extension - used for runtime loadable modules. If you use libltdl to open - modules, then you can simply use the libtool library extension, - `.la'. - - -- Macro: LT_SYS_MODULE_PATH - Define the preprocessor symbol `LT_MODULE_PATH_VAR' to the name of - the shell environment variable that determines the run-time module - search path. - - -- Macro: LT_SYS_SYMBOL_USCORE - Set the shell variable `sys_symbol_underscore' to `no' unless the - compiler prefixes global symbols with an underscore. - - -File: libtool.info, Node: Makefile rules, Next: Using Automake, Prev: Autoconf macros, Up: Integrating libtool - -5.2 Writing `Makefile' rules for libtool -======================================== - -Libtool is fully integrated with Automake (*note Introduction: -(automake)Top.), starting with Automake version 1.2. - - If you want to use libtool in a regular `Makefile' (or -`Makefile.in'), you are on your own. If you're not using Automake, and -you don't know how to incorporate libtool into your package you need to -do one of the following: - - 1. Download the latest Automake distribution from your nearest GNU - mirror, install it, and start using it. - - 2. Learn how to write `Makefile' rules by hand. They're sometimes - complex, but if you're clever enough to write rules for compiling - your old libraries, then you should be able to figure out new - rules for libtool libraries (hint: examine the `Makefile.in' in - the `tests/demo' subdirectory of the libtool distribution... note - especially that it was automatically generated from the - `Makefile.am' by Automake). - - -File: libtool.info, Node: Using Automake, Next: Configuring, Prev: Makefile rules, Up: Integrating libtool - -5.3 Using Automake with libtool -=============================== - -Libtool library support is implemented under the `LTLIBRARIES' primary. - - Here are some samples from the Automake `Makefile.am' in the libtool -distribution's `demo' subdirectory. - - First, to link a program against a libtool library, just use the -`program_LDADD'(1) variable: - - bin_PROGRAMS = hell hell_static - - # Build hell from main.c and libhello.la - hell_SOURCES = main.c - hell_LDADD = libhello.la - - # Create a statically linked version of hell. - hell_static_SOURCES = main.c - hell_static_LDADD = libhello.la - hell_static_LDFLAGS = -static - - You may use the `program_LDFLAGS' variable to stuff in any flags you -want to pass to libtool while linking `program' (such as `-static' to -avoid linking uninstalled shared libtool libraries). - - Building a libtool library is almost as trivial... note the use of -`libhello_la_LDFLAGS' to pass the `-version-info' (*note Versioning::) -option to libtool: - - # Build a libtool library, libhello.la for installation in libdir. - lib_LTLIBRARIES = libhello.la - libhello_la_SOURCES = hello.c foo.c - libhello_la_LDFLAGS = -version-info 3:12:1 - - The `-rpath' option is passed automatically by Automake (except for -libraries listed as `noinst_LTLIBRARIES'), so you should not specify it. - - *Note Building a Shared Library: (automake)A Shared Library, for -more information. - - ---------- Footnotes ---------- - - (1) Since GNU Automake 1.5, the flags `-dlopen' or `-dlpreopen' -(*note Link mode::) can be employed with the `program_LDADD' variable. -Unfortunately, older releases didn't accept these flags, so if you are -stuck with an ancient Automake, we recommend quoting the flag itself, -and setting `program_DEPENDENCIES' too: - - program_LDADD = "-dlopen" libfoo.la - program_DEPENDENCIES = libfoo.la - - -File: libtool.info, Node: Configuring, Next: Distributing, Prev: Using Automake, Up: Integrating libtool - -5.4 Configuring libtool -======================= - -Libtool requires intimate knowledge of your compiler suite and operating -system in order to be able to create shared libraries and link against -them properly. When you install the libtool distribution, a -system-specific libtool script is installed into your binary directory. - - However, when you distribute libtool with your own packages (*note -Distributing::), you do not always know the compiler suite and -operating system that are used to compile your package. - - For this reason, libtool must be "configured" before it can be used. -This idea should be familiar to anybody who has used a GNU `configure' -script. `configure' runs a number of tests for system features, then -generates the `Makefile's (and possibly a `config.h' header file), -after which you can run `make' and build the package. - - Libtool adds its own tests to your `configure' script in order to -generate a libtool script for the installer's host machine. - -* Menu: - -* LT_INIT:: Configuring `libtool' in `configure.ac'. -* Configure notes:: Platform-specific notes for configuration. - - -File: libtool.info, Node: LT_INIT, Next: Configure notes, Up: Configuring - -5.4.1 The `LT_INIT' macro -------------------------- - -If you are using GNU Autoconf (or Automake), you should add a call to -`LT_INIT' to your `configure.ac' file. This macro adds many new tests -to the `configure' script so that the generated libtool script will -understand the characteristics of the host. It's the most important of -a number of macros defined by Libtool: - - -- Macro: LT_PREREQ (VERSION) - Ensure that a recent enough version of Libtool is being used. If - the version of Libtool used for `LT_INIT' is earlier than VERSION, - print an error message to the standard error output and exit with - failure (exit status is 63). For example: - - LT_PREREQ([2.4.2]) - - -- Macro: LT_INIT (OPTIONS) - -- Macro: AC_PROG_LIBTOOL - -- Macro: AM_PROG_LIBTOOL - Add support for the `--enable-shared', `--disable-shared', - `--enable-static', `--disable-static', `--with-pic', and - `--without-pic' `configure' flags.(1) `AC_PROG_LIBTOOL' and - `AM_PROG_LIBTOOL' are deprecated names for older versions of this - macro; `autoupdate' will upgrade your `configure.ac' files. - - By default, this macro turns on shared libraries if they are - available, and also enables static libraries if they don't - conflict with the shared libraries. You can modify these defaults - by passing either `disable-shared' or `disable-static' in the - option list to `LT_INIT', or using `AC_DISABLE_SHARED' or - `AC_DISABLE_STATIC'. - - # Turn off shared libraries during beta-testing, since they - # make the build process take too long. - LT_INIT([disable-shared]) - - The user may specify modified forms of the configure flags - `--enable-shared' and `--enable-static' to choose whether shared - or static libraries are built based on the name of the package. - For example, to have shared `bfd' and `gdb' libraries built, but - not shared `libg++', you can run all three `configure' scripts as - follows: - - trick$ ./configure --enable-shared=bfd,gdb - - In general, specifying `--enable-shared=PKGS' is the same as - configuring with `--enable-shared' every package named in the - comma-separated PKGS list, and every other package with - `--disable-shared'. The `--enable-static=PKGS' flag behaves - similarly, but it uses `--enable-static' and `--disable-static'. - The same applies to the `--enable-fast-install=PKGS' flag, which - uses `--enable-fast-install' and `--disable-fast-install'. - - The package name `default' matches any packages that have not set - their name in the `PACKAGE' environment variable. - - The `--with-pic' and `--without-pic' configure flags can be used - to specify whether or not `libtool' uses PIC objects. By default, - `libtool' uses PIC objects for shared libraries and non-PIC - objects for static libraries. The `--with-pic' option also - accepts a comma-separated list of package names. Specifying - `--with-pic=PKGS' is the same as configuring every package in PKGS - with `--with-pic' and every other package with the default - configuration. The package name `default' is treated the same as - for `--enable-shared' and `--enable-static'. - - This macro also sets the shell variable `LIBTOOL_DEPS', that you - can use to automatically update the libtool script if it becomes - out-of-date. In order to do that, add to your `configure.ac': - - LT_INIT - AC_SUBST([LIBTOOL_DEPS]) - - and, to `Makefile.in' or `Makefile.am': - - LIBTOOL_DEPS = @LIBTOOL_DEPS@ - libtool: $(LIBTOOL_DEPS) - $(SHELL) ./config.status libtool - - If you are using GNU Automake, you can omit the assignment, as - Automake will take care of it. You'll obviously have to create - some dependency on `libtool'. - - Aside from `disable-static' and `disable-shared', there are other - options that you can pass to `LT_INIT' to modify its behaviour. - Here is a full list: - - `dlopen' - Enable checking for dlopen support. This option should be - used if the package makes use of the `-dlopen' and - `-dlpreopen' libtool flags, otherwise libtool will assume - that the system does not support dlopening. - - `win32-dll' - This option should be used if the package has been ported to - build clean dlls on win32 platforms. Usually this means that - any library data items are exported with - `__declspec(dllexport)' and imported with - `__declspec(dllimport)'. If this macro is not used, libtool - will assume that the package libraries are not dll clean and - will build only static libraries on win32 hosts. - - Provision must be made to pass `-no-undefined' to `libtool' - in link mode from the package `Makefile'. Naturally, if you - pass `-no-undefined', you must ensure that all the library - symbols *really are* defined at link time! - - `disable-fast-install' - Change the default behaviour for `LT_INIT' to disable - optimization for fast installation. The user may still - override this default, depending on platform support, by - specifying `--enable-fast-install' to `configure'. - - `shared' - Change the default behaviour for `LT_INIT' to enable shared - libraries. This is the default on all systems where Libtool - knows how to create shared libraries. The user may still - override this default by specifying `--disable-shared' to - `configure'. - - `disable-shared' - Change the default behaviour for `LT_INIT' to disable shared - libraries. The user may still override this default by - specifying `--enable-shared' to `configure'. - - `static' - Change the default behaviour for `LT_INIT' to enable static - libraries. This is the default on all systems where shared - libraries have been disabled for some reason, and on most - systems where shared libraries have been enabled. If shared - libraries are enabled, the user may still override this - default by specifying `--disable-static' to `configure'. - - `disable-static' - Change the default behaviour for `LT_INIT' to disable static - libraries. The user may still override this default by - specifying `--enable-static' to `configure'. - - `pic-only' - Change the default behaviour for `libtool' to try to use only - PIC objects. The user may still override this default by - specifying `--without-pic' to `configure'. - - `no-pic' - Change the default behaviour of `libtool' to try to use only - non-PIC objects. The user may still override this default by - specifying `--with-pic' to `configure'. - - - - -- Macro: LT_LANG (LANGUAGE) - Enable `libtool' support for the language given if it has not yet - already been enabled. Languages accepted are "C++", "Fortran 77", - "Java", "Go", and "Windows Resource". - - If Autoconf language support macros such as `AC_PROG_CXX' are used - in your `configure.ac', Libtool language support will automatically - be enabled. - - Conversely using `LT_LANG' to enable language support for Libtool - will automatically enable Autoconf language support as well. - - Both of the following examples are therefore valid ways of adding - C++ language support to Libtool. - - LT_INIT - LT_LANG([C++]) - - LT_INIT - AC_PROG_CXX - - - -- Macro: AC_LIBTOOL_DLOPEN - This macro is deprecated, the `dlopen' option to `LT_INIT' should - be used instead. - - -- Macro: AC_LIBTOOL_WIN32_DLL - This macro is deprecated, the `win32-dll' option to `LT_INIT' - should be used instead. - - -- Macro: AC_DISABLE_FAST_INSTALL - This macro is deprecated, the `disable-fast-install' option to - `LT_INIT' should be used instead. - - -- Macro: AC_DISABLE_SHARED - -- Macro: AM_DISABLE_SHARED - Change the default behaviour for `LT_INIT' to disable shared - libraries. The user may still override this default by specifying - `--enable-shared'. The option `disable-shared' to `LT_INIT' is a - shorthand for this. `AM_DISABLE_SHARED' is a deprecated alias for - `AC_DISABLE_SHARED'. - - -- Macro: AC_ENABLE_SHARED - -- Macro: AM_ENABLE_SHARED - Change the default behaviour for `LT_INIT' to enable shared - libraries. This is the default on all systems where Libtool knows - how to create shared libraries. The user may still override this - default by specifying `--disable-shared'. The option `shared' to - `LT_INIT' is a shorthand for this. `AM_ENABLE_SHARED' is a - deprecated alias for `AC_ENABLE_SHARED'. - - -- Macro: AC_DISABLE_STATIC - -- Macro: AM_DISABLE_STATIC - Change the default behaviour for `LT_INIT' to disable static - libraries. The user may still override this default by specifying - `--enable-static'. The option `disable-static' to `LT_INIT' is a - shorthand for this. `AM_DISABLE_STATIC' is a deprecated alias for - `AC_DISABLE_STATIC'. - - -- Macro: AC_ENABLE_STATIC - -- Macro: AM_ENABLE_STATIC - Change the default behaviour for `LT_INIT' to enable static - libraries. This is the default on all systems where shared - libraries have been disabled for some reason, and on most systems - where shared libraries have been enabled. If shared libraries are - enabled, the user may still override this default by specifying - `--disable-static'. The option `static' to `LT_INIT' is a - shorthand for this. `AM_ENABLE_STATIC' is a deprecated alias for - `AC_ENABLE_STATIC'. - - The tests in `LT_INIT' also recognize the following environment -variables: - - -- Variable: CC - The C compiler that will be used by the generated `libtool'. If - this is not set, `LT_INIT' will look for `gcc' or `cc'. - - -- Variable: CFLAGS - Compiler flags used to generate standard object files. If this is - not set, `LT_INIT' will not use any such flags. It affects only - the way `LT_INIT' runs tests, not the produced `libtool'. - - -- Variable: CPPFLAGS - C preprocessor flags. If this is not set, `LT_INIT' will not use - any such flags. It affects only the way `LT_INIT' runs tests, not - the produced `libtool'. - - -- Variable: LD - The system linker to use (if the generated `libtool' requires one). - If this is not set, `LT_INIT' will try to find out what is the - linker used by `CC'. - - -- Variable: LDFLAGS - The flags to be used by `libtool' when it links a program. If - this is not set, `LT_INIT' will not use any such flags. It - affects only the way `LT_INIT' runs tests, not the produced - `libtool'. - - -- Variable: LIBS - The libraries to be used by `LT_INIT' when it links a program. If - this is not set, `LT_INIT' will not use any such flags. It - affects only the way `LT_INIT' runs tests, not the produced - `libtool'. - - -- Variable: NM - Program to use rather than checking for `nm'. - - -- Variable: RANLIB - Program to use rather than checking for `ranlib'. - - -- Variable: LN_S - A command that creates a link of a program, a soft-link if - possible, a hard-link otherwise. `LT_INIT' will check for a - suitable program if this variable is not set. - - -- Variable: DLLTOOL - Program to use rather than checking for `dlltool'. Only meaningful - for Cygwin/MS-Windows. - - -- Variable: OBJDUMP - Program to use rather than checking for `objdump'. Only meaningful - for Cygwin/MS-Windows. - - -- Variable: AS - Program to use rather than checking for `as'. Only used on - Cygwin/MS-Windows at the moment. - - -- Variable: MANIFEST_TOOL - Program to use rather than checking for `mt', the Manifest Tool. - Only used on Cygwin/MS-Windows at the moment. - - With 1.3 era libtool, if you wanted to know any details of what -libtool had discovered about your architecture and environment, you had -to run the script with `--config' and grep through the results. This -idiom was supported up to and including 1.5.x era libtool, where it was -possible to call the generated libtool script from `configure.ac' as -soon as `LT_INIT' had completed. However, one of the features of -libtool 1.4 was that the libtool configuration was migrated out of a -separate `ltconfig' file, and added to the `LT_INIT' macro (nee -`AC_PROG_LIBTOOL'), so the results of the configuration tests were -available directly to code in `configure.ac', rendering the call out to -the generated libtool script obsolete. - - Starting with libtool 2.0, the multipass generation of the libtool -script has been consolidated into a single `config.status' pass, which -happens after all the code in `configure.ac' has completed. The -implication of this is that the libtool script does not exist during -execution of code from `configure.ac', and so obviously it cannot be -called for `--config' details anymore. If you are upgrading projects -that used this idiom to libtool 2.0 or newer, you should replace those -calls with direct references to the equivalent Autoconf shell variables -that are set by the configure time tests before being passed to -`config.status' for inclusion in the generated libtool script. - - -- Macro: LT_OUTPUT - By default, the configured `libtool' script is generated by the - call to `AC_OUTPUT' command, and there is rarely any need to use - `libtool' from `configure'. However, sometimes it is necessary to - run configure time compile and link tests using `libtool'. You - can add `LT_OUTPUT' to your `configure.ac' any time after - `LT_INIT' and any `LT_LANG' calls; that done, `libtool' will be - created by a specially generated `config.lt' file, and available - for use in later tests. - - Also, when `LT_OUTPUT' is used, for backwards compatibility with - Automake regeneration rules, `config.status' will call `config.lt' - to regenerate `libtool', rather than generating the file itself. - - When you invoke the `libtoolize' program (*note Invoking -libtoolize::), it will tell you where to find a definition of -`LT_INIT'. If you use Automake, the `aclocal' program will -automatically add `LT_INIT' support to your `configure' script when it -sees the invocation of `LT_INIT' in `configure.ac'. - - Because of these changes, and the runtime version compatibility -checks Libtool now executes, we now advise *against* including a copy of -`libtool.m4' (and brethren) in `acinclude.m4'. Instead, you should set -your project macro directory with `AC_CONFIG_MACRO_DIR'. When you -`libtoolize' your project, a copy of the relevant macro definitions -will be placed in your `AC_CONFIG_MACRO_DIR', where `aclocal' can -reference them directly from `aclocal.m4'. - - ---------- Footnotes ---------- - - (1) `LT_INIT' requires that you define the `Makefile' variable -`top_builddir' in your `Makefile.in'. Automake does this -automatically, but Autoconf users should set it to the relative path to -the top of your build directory (`../..', for example). - - -File: libtool.info, Node: Configure notes, Prev: LT_INIT, Up: Configuring - -5.4.2 Platform-specific configuration notes -------------------------------------------- - -While Libtool tries to hide as many platform-specific features as -possible, some have to be taken into account when configuring either -the Libtool package or a libtoolized package. - - * You currently need GNU make to build the Libtool package itself. - - * On AIX there are two different styles of shared linking, one in - which symbols are bound at link-time and one in which symbols are - bound at runtime only, similar to ELF. In case of doubt use - `LDFLAGS=-Wl,-brtl' for the latter style. - - * On AIX, native tools are to be preferred over binutils; especially - for C++ code, if using the AIX Toolbox GCC 4.0 and binutils, - configure with `AR=/usr/bin/ar LD=/usr/bin/ld NM='/usr/bin/nm -B''. - - * On AIX, the `/bin/sh' is very slow due to its inefficient handling - of here-documents. A modern shell is preferable: - CONFIG_SHELL=/bin/bash; export $CONFIG_SHELL - $CONFIG_SHELL ./configure [...] - - * For C++ code with templates, it may be necessary to specify the - way the compiler will generate the instantiations. For Portland - pgCC version5, use `CXX='pgCC --one_instantiation_per_object'' and - avoid parallel `make'. - - * On Darwin, for C++ code with templates you need two level shared - libraries. Libtool builds these by default if - `MACOSX_DEPLOYMENT_TARGET' is set to 10.3 or later at `configure' - time. See `rdar://problem/4135857' for more information on this - issue. - - * The default shell on UNICOS 9, a ksh 88e variant, is too buggy to - correctly execute the libtool script. Users are advised to - install a modern shell such as GNU bash. - - * Some HP-UX `sed' programs are horribly broken, and cannot handle - libtool's requirements, so users may report unusual problems. - There is no workaround except to install a working `sed' (such as - GNU sed) on these systems. - - * The vendor-distributed NCR MP-RAS `cc' programs emits copyright on - standard error that confuse tests on size of `conftest.err'. The - workaround is to specify `CC' when run configure with `CC='cc - -Hnocopyr''. - - * Any earlier DG/UX system with ELF executables, such as R3.10 or - R4.10, is also likely to work, but hasn't been explicitly tested. - - * On Reliant Unix libtool has only been tested with the Siemens - C-compiler and an old version of `gcc' provided by Marco Walther. - - * `libtool.m4', `ltdl.m4' and the `configure.ac' files are marked to - use autoconf-mode, which is distributed with GNU Emacs 21, - Autoconf itself, and all recent releases of XEmacs. - - * When building on some GNU/Linux systems for multilib targets - `libtool' sometimes guesses the wrong paths that the linker and - dynamic linker search by default. If this occurs, you may override - libtool's guesses at `configure' time by setting the `autoconf' - cache variables `lt_cv_sys_lib_search_path_spec' and - `lt_cv_sys_lib_dlsearch_path_spec' respectively to the correct - search paths. - - - -File: libtool.info, Node: Distributing, Next: Static-only libraries, Prev: Configuring, Up: Integrating libtool - -5.5 Including libtool in your package -===================================== - -In order to use libtool, you need to include the following files with -your package: - -`config.guess' - Attempt to guess a canonical system name. - -`config.sub' - Canonical system name validation subroutine script. - -`install-sh' - BSD-compatible `install' replacement script. - -`ltmain.sh' - A generic script implementing basic libtool functionality. - - Note that the libtool script itself should _not_ be included with -your package. *Note Configuring::. - - You should use the `libtoolize' program, rather than manually -copying these files into your package. - -* Menu: - -* Invoking libtoolize:: `libtoolize' command line options. -* Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation. - - -File: libtool.info, Node: Invoking libtoolize, Next: Autoconf and LTLIBOBJS, Up: Distributing - -5.5.1 Invoking `libtoolize' ---------------------------- - -The `libtoolize' program provides a standard way to add libtool support -to your package. In the future, it may implement better usage -checking, or other features to make libtool even easier to use. - - The `libtoolize' program has the following synopsis: - - libtoolize [OPTION]... - -and accepts the following options: - -`--copy' -`-c' - Copy files from the libtool data directory rather than creating - symlinks. - -`--debug' - Dump a trace of shell script execution to standard output. This - produces a lot of output, so you may wish to pipe it to `less' (or - `more') or redirect to a file. - -`--dry-run' -`-n' - Don't run any commands that modify the file system, just print them - out. - -`--force' -`-f' - Replace existing libtool files. By default, `libtoolize' won't - overwrite existing files. - -`--help' - Display a help message and exit. - -`--ltdl [TARGET-DIRECTORY-NAME]' - Install libltdl in the TARGET-DIRECTORY-NAME subdirectory of your - package. Normally, the directory is extracted from the argument - to `LT_CONFIG_LTDL_DIR' in `configure.ac', though you can also - specify a subdirectory name here if you are not using Autoconf for - example. If `libtoolize' can't determine the target directory, - `libltdl' is used as the default. - -`--no-warn' - Normally, Libtoolize tries to diagnose use of deprecated libtool - macros and other stylistic issues. If you are deliberately using - outdated calling conventions, this option prevents Libtoolize from - explaining how to update your project's Libtool conventions. - -`--nonrecursive' - If passed in conjunction with `--ltdl', this option will cause the - `libltdl' installed by `libtoolize' to be set up for use with a - non-recursive `automake' build. To make use of it, you will need - to add the following to the `Makefile.am' of the parent project: - - ## libltdl/Makefile.inc appends to the following variables - ## so we set them here before including it: - BUILT_SOURCES = - - AM_CPPFLAGS = - AM_LDFLAGS = - - include_HEADERS = - noinst_LTLIBRARIES = - lib_LTLIBRARIES = - EXTRA_LTLIBRARIES = - - EXTRA_DIST = - - CLEANFILES = - MOSTLYCLEANFILES = - - include libltdl/Makefile.inc - - -`--quiet' -`-q' - Work silently. `libtoolize --quiet' is used by GNU Automake to - add libtool files to your package if necessary. - -`--recursive' - If passed in conjunction with `--ltdl', this option will cause the - `libtoolize' installed `libltdl' to be set up for use with a - recursive `automake' build. To make use of it, you will need to - adjust the parent project's `configure.ac': - - AC_CONFIG_FILES([libltdl/Makefile]) - - and `Makefile.am': - - SUBDIRS += libltdl - -`--subproject' - If passed in conjunction with `--ltdl', this option will cause the - `libtoolize' installed `libltdl' to be set up for independent - configuration and compilation as a self-contained subproject. To - make use of it, you should arrange for your build to call - `libltdl/configure', and then run `make' in the `libltdl' - directory (or the subdirectory you put libltdl into). If your - project uses Autoconf, you can use the supplied `LT_WITH_LTDL' - macro, or else call `AC_CONFIG_SUBDIRS' directly. - - Previous releases of `libltdl' built exclusively in this mode, but - now it is the default mode both for backwards compatibility and - because, for example, it is suitable for use in projects that wish - to use `libltdl', but not use the Autotools for their own build - process. - -`--verbose' -`-v' - Work noisily! Give a blow by blow account of what `libtoolize' is - doing. - -`--version' - Print `libtoolize' version information and exit. - - Sometimes it can be useful to pass options to `libtoolize' even -though it is called by another program, such as `autoreconf'. A -limited number of options are parsed from the environment variable -`LIBTOOLIZE_OPTIONS': currently `--debug', `--no-warn', `--quiet' and -`--verbose'. Multiple options passed in `LIBTOOLIZE_OPTIONS' must be -separated with a space, comma or a colon. - - By default, a warning is issued for unknown options found in -`LIBTOOLIZE_OPTIONS' unless the first such option is `--no-warn'. -Where `libtoolize' has always quit on receipt of an unknown option at -the command line, this and all previous releases of `libtoolize' will -continue unabated whatever the content of `LIBTOOLIZE_OPTIONS' (modulo -some possible warning messages). - - trick$ LIBTOOLIZE_OPTIONS=--no-warn,--quiet autoreconf --install - - If `libtoolize' detects an explicit call to `AC_CONFIG_MACRO_DIR' -(*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac', -it will put the Libtool macros in the specified directory. - - In the future other Autotools will automatically check the contents -of `AC_CONFIG_MACRO_DIR', but at the moment it is more portable to add -the macro directory to `ACLOCAL_AMFLAGS' in `Makefile.am', which is -where the tools currently look. If `libtoolize' doesn't see -`AC_CONFIG_MACRO_DIR', it too will honour the first `-I' argument in -`ACLOCAL_AMFLAGS' when choosing a directory to store libtool -configuration macros in. It is perfectly sensible to use both -`AC_CONFIG_MACRO_DIR' and `ACLOCAL_AMFLAGS', as long as they are kept -in synchronisation. - - ACLOCAL_AMFLAGS = -I m4 - - When you bootstrap your project with `aclocal', then you will need -to explicitly pass the same macro directory with `aclocal''s `-I' flag: - - trick$ aclocal -I m4 - - If `libtoolize' detects an explicit call to `AC_CONFIG_AUX_DIR' -(*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac', it -will put the other support files in the specified directory. Otherwise -they too end up in the project root directory. - - Unless `--no-warn' is passed, `libtoolize' displays hints for adding -libtool support to your package, as well. - - -File: libtool.info, Node: Autoconf and LTLIBOBJS, Prev: Invoking libtoolize, Up: Distributing - -5.5.2 Autoconf and `LTLIBOBJS' ------------------------------- - -People used to add code like the following to their `configure.ac': - - LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'` - AC_SUBST([LTLIBOBJS]) - -This is no longer required (since Autoconf 2.54), and doesn't take -Automake's deansification support into account either, so doesn't work -correctly even with ancient Autoconfs! - - Provided you are using a recent (2.54 or better) incarnation of -Autoconf, the call to `AC_OUTPUT' takes care of setting `LTLIBOBJS' up -correctly, so you can simply delete such snippets from your -`configure.ac' if you had them. - - -File: libtool.info, Node: Static-only libraries, Prev: Distributing, Up: Integrating libtool - -5.6 Static-only libraries -========================= - -When you are developing a package, it is often worthwhile to configure -your package with the `--disable-shared' flag, or to override the -defaults for `LT_INIT' by using the `disable-shared' option (*note The -`LT_INIT' macro: LT_INIT.). This prevents libtool from building shared -libraries, which has several advantages: - - * compilation is twice as fast, which can speed up your development - cycle, - - * debugging is easier because you don't need to deal with any - complexities added by shared libraries, and - - * you can see how libtool behaves on static-only platforms. - - You may want to put a small note in your package `README' to let -other developers know that `--disable-shared' can save them time. The -following example note is taken from the GIMP(1) distribution `README': - - The GIMP uses GNU Libtool in order to build shared libraries on a - variety of systems. While this is very nice for making usable - binaries, it can be a pain when trying to debug a program. For that - reason, compilation of shared libraries can be turned off by - specifying the `--disable-shared' option to `configure'. - - ---------- Footnotes ---------- - - (1) GNU Image Manipulation Program, for those who haven't taken the -plunge. See `http://www.gimp.org/'. - - -File: libtool.info, Node: Other languages, Next: Versioning, Prev: Integrating libtool, Up: Top - -6 Using libtool with other languages -************************************ - -Libtool was first implemented in order to add support for writing shared -libraries in the C language. However, over time, libtool is being -integrated with other languages, so that programmers are free to reap -the benefits of shared libraries in their favorite programming language. - - This chapter describes how libtool interacts with other languages, -and what special considerations you need to make if you do not use C. - -* Menu: - -* C++ libraries:: Writing libraries for C++ -* Tags:: Tags - - -File: libtool.info, Node: C++ libraries, Next: Tags, Up: Other languages - -6.1 Writing libraries for C++ -============================= - -Creating libraries of C++ code should be a fairly straightforward -process, because its object files differ from C ones in only three ways: - - 1. Because of name mangling, C++ libraries are only usable by the C++ - compiler that created them. This decision was made by the - designers of C++ in order to protect users from conflicting - implementations of features such as constructors, exception - handling, and RTTI. - - 2. On some systems, the C++ compiler must take special actions for the - dynamic linker to run dynamic (i.e., run-time) initializers. This - means that we should not call `ld' directly to link such - libraries, and we should use the C++ compiler instead. - - 3. C++ compilers will link some Standard C++ library in by default, - but libtool does not know which are these libraries, so it cannot - even run the inter-library dependence analyzer to check how to - link it in. Therefore, running `ld' to link a C++ program or - library is deemed to fail. - - Because of these three issues, Libtool has been designed to always -use the C++ compiler to compile and link C++ programs and libraries. In -some instances the `main()' function of a program must also be compiled -with the C++ compiler for static C++ objects to be properly initialized. - - -File: libtool.info, Node: Tags, Prev: C++ libraries, Up: Other languages - -6.2 Tags -======== - -Libtool supports multiple languages through the use of tags. -Technically a tag corresponds to a set of configuration variables -associated with a language. These variables tell `libtool' how it -should create objects and libraries for each language. - - Tags are defined at `configure'-time for each language activated in -the package (see `LT_LANG' in *note LT_INIT::). Here is the -correspondence between language names and tags names. - -Language name Tag name -C CC -C++ CXX -Java GCJ -Fortran 77 F77 -Fortran FC -Go GO -Windows Resource RC - - `libtool' tries to automatically infer which tag to use from the -compiler command being used to compile or link. If it can't infer a -tag, then it defaults to the configuration for the `C' language. - - The tag can also be specified using `libtool''s `--tag=TAG' option -(*note Invoking libtool::). It is a good idea to do so in `Makefile' -rules, because that will allow users to substitute the compiler without -relying on `libtool' inference heuristics. When no tag is specified, -`libtool' will default to `CC'; this tag always exists. - - Finally, the set of tags available in a particular project can be -retrieved by tracing for the `LT_SUPPORTED_TAG' macro (*note Trace -interface::). - - -File: libtool.info, Node: Versioning, Next: Library tips, Prev: Other languages, Up: Top - -7 Library interface versions -**************************** - -The most difficult issue introduced by shared libraries is that of -creating and resolving runtime dependencies. Dependencies on programs -and libraries are often described in terms of a single name, such as -`sed'. So, one may say "libtool depends on sed," and that is good -enough for most purposes. - - However, when an interface changes regularly, we need to be more -specific: "Gnus 5.1 requires Emacs 19.28 or above." Here, the -description of an interface consists of a name, and a "version number." - - Even that sort of description is not accurate enough for some -purposes. What if Emacs 20 changes enough to break Gnus 5.1? - - The same problem exists in shared libraries: we require a formal -version system to describe the sorts of dependencies that programs have -on shared libraries, so that the dynamic linker can guarantee that -programs are linked only against libraries that provide the interface -they require. - -* Menu: - -* Interfaces:: What are library interfaces? -* Libtool versioning:: Libtool's versioning system. -* Updating version info:: Changing version information before releases. -* Release numbers:: Breaking binary compatibility for aesthetics. - - -File: libtool.info, Node: Interfaces, Next: Libtool versioning, Up: Versioning - -7.1 What are library interfaces? -================================ - -Interfaces for libraries may be any of the following (and more): - - * global variables: both names and types - - * global functions: argument types and number, return types, and - function names - - * standard input, standard output, standard error, and file formats - - * sockets, pipes, and other inter-process communication protocol - formats - - Note that static functions do not count as interfaces, because they -are not directly available to the user of the library. - - -File: libtool.info, Node: Libtool versioning, Next: Updating version info, Prev: Interfaces, Up: Versioning - -7.2 Libtool's versioning system -=============================== - -Libtool has its own formal versioning system. It is not as flexible as -some, but it is definitely the simplest of the more powerful versioning -systems. - - Think of a library as exporting several sets of interfaces, -arbitrarily represented by integers. When a program is linked against -a library, it may use any subset of those interfaces. - - Libtool's description of the interfaces that a program uses is -simple: it encodes the least and the greatest interface numbers in the -resulting binary (FIRST-INTERFACE, LAST-INTERFACE). - - The dynamic linker is guaranteed that if a library supports _every_ -interface number between FIRST-INTERFACE and LAST-INTERFACE, then the -program can be relinked against that library. - - Note that this can cause problems because libtool's compatibility -requirements are actually stricter than is necessary. - - Say `libhello' supports interfaces 5, 16, 17, 18, and 19, and that -libtool is used to link `test' against `libhello'. - - Libtool encodes the numbers 5 and 19 in `test', and the dynamic -linker will only link `test' against libraries that support _every_ -interface between 5 and 19. So, the dynamic linker refuses to link -`test' against `libhello'! - - In order to eliminate this problem, libtool only allows libraries to -declare consecutive interface numbers. So, `libhello' can declare at -most that it supports interfaces 16 through 19. Then, the dynamic -linker will link `test' against `libhello'. - - So, libtool library versions are described by three integers: - -CURRENT - The most recent interface number that this library implements. - -REVISION - The implementation number of the CURRENT interface. - -AGE - The difference between the newest and oldest interfaces that this - library implements. In other words, the library implements all the - interface numbers in the range from number `CURRENT - AGE' to - `CURRENT'. - - If two libraries have identical CURRENT and AGE numbers, then the -dynamic linker chooses the library with the greater REVISION number. - - -File: libtool.info, Node: Updating version info, Next: Release numbers, Prev: Libtool versioning, Up: Versioning - -7.3 Updating library version information -======================================== - -If you want to use libtool's versioning system, then you must specify -the version information to libtool using the `-version-info' flag -during link mode (*note Link mode::). - - This flag accepts an argument of the form -`CURRENT[:REVISION[:AGE]]'. So, passing `-version-info 3:12:1' sets -CURRENT to 3, REVISION to 12, and AGE to 1. - - If either REVISION or AGE are omitted, they default to 0. Also note -that AGE must be less than or equal to the CURRENT interface number. - - Here are a set of rules to help you update your library version -information: - - 1. Start with version information of `0:0:0' for each libtool library. - - 2. Update the version information only immediately before a public - release of your software. More frequent updates are unnecessary, - and only guarantee that the current interface number gets larger - faster. - - 3. If the library source code has changed at all since the last - update, then increment REVISION (`C:R:A' becomes `C:r+1:A'). - - 4. If any interfaces have been added, removed, or changed since the - last update, increment CURRENT, and set REVISION to 0. - - 5. If any interfaces have been added since the last public release, - then increment AGE. - - 6. If any interfaces have been removed or changed since the last - public release, then set AGE to 0. - - *_Never_* try to set the interface numbers so that they correspond -to the release number of your package. This is an abuse that only -fosters misunderstanding of the purpose of library versions. Instead, -use the `-release' flag (*note Release numbers::), but be warned that -every release of your package will not be binary compatible with any -other release. - - The following explanation may help to understand the above rules a -bit better: consider that there are three possible kinds of reactions -from users of your library to changes in a shared library: - - 1. Programs using the previous version may use the new version as - drop-in replacement, and programs using the new version can also - work with the previous one. In other words, no recompiling nor - relinking is needed. In this case, bump REVISION only, don't touch - CURRENT nor AGE. - - 2. Programs using the previous version may use the new version as - drop-in replacement, but programs using the new version may use - APIs not present in the previous one. In other words, a program - linking against the new version may fail with "unresolved symbols" - if linking against the old version at runtime: set REVISION to 0, - bump CURRENT and AGE. - - 3. Programs may need to be changed, recompiled, relinked in order to - use the new version. Bump CURRENT, set REVISION and AGE to 0. - -In the above description, _programs_ using the library in question may -also be replaced by other libraries using it. - - -File: libtool.info, Node: Release numbers, Prev: Updating version info, Up: Versioning - -7.4 Managing release information -================================ - -Often, people want to encode the name of the package release into the -shared library so that it is obvious to the user which package their -programs are linked against. This convention is used especially on -GNU/Linux: - - trick$ ls /usr/lib/libbfd* - /usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2 - /usr/lib/libbfd.so - trick$ - - On `trick', `/usr/lib/libbfd.so' is a symbolic link to -`libbfd.so.2.7.0.2', which was distributed as a part of -`binutils-2.7.0.2'. - - Unfortunately, this convention conflicts directly with libtool's -idea of library interface versions, because the library interface -rarely changes at the same time that the release number does, and the -library suffix is never the same across all platforms. - - So, in order to accommodate both views, you can use the `-release' -flag in order to set release information for libraries for which you do -not want to use `-version-info'. For the `libbfd' example, the next -release that uses libtool should be built with `-release 2.9.0', which -will produce the following files on GNU/Linux: - - trick$ ls /usr/lib/libbfd* - /usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a - /usr/lib/libbfd.so - trick$ - - In this case, `/usr/lib/libbfd.so' is a symbolic link to -`libbfd-2.9.0.so'. This makes it obvious that the user is dealing with -`binutils-2.9.0', without compromising libtool's idea of interface -versions. - - Note that this option causes a modification of the library name, so -do not use it unless you want to break binary compatibility with any -past library releases. In general, you should only use `-release' for -package-internal libraries or for ones whose interfaces change very -frequently. - - -File: libtool.info, Node: Library tips, Next: Inter-library dependencies, Prev: Versioning, Up: Top - -8 Tips for interface design -*************************** - -Writing a good library interface takes a lot of practice and thorough -understanding of the problem that the library is intended to solve. - - If you design a good interface, it won't have to change often, you -won't have to keep updating documentation, and users won't have to keep -relearning how to use the library. - - Here is a brief list of tips for library interface design that may -help you in your exploits: - -Plan ahead - Try to make every interface truly minimal, so that you won't need - to delete entry points very often. - -Avoid interface changes - Some people love redesigning and changing entry points just for - the heck of it (note: _renaming_ a function is considered changing - an entry point). Don't be one of those people. If you must - redesign an interface, then try to leave compatibility functions - behind so that users don't need to rewrite their existing code. - -Use opaque data types - The fewer data type definitions a library user has access to, the - better. If possible, design your functions to accept a generic - pointer (that you can cast to an internal data type), and provide - access functions rather than allowing the library user to directly - manipulate the data. That way, you have the freedom to change the - data structures without changing the interface. - - This is essentially the same thing as using abstract data types and - inheritance in an object-oriented system. - -Use header files - If you are careful to document each of your library's global - functions and variables in header files, and include them in your - library source files, then the compiler will let you know if you - make any interface changes by accident (*note C header files::). - -Use the `static' keyword (or equivalent) whenever possible - The fewer global functions your library has, the more flexibility - you'll have in changing them. Static functions and variables may - change forms as often as you like... your users cannot access - them, so they aren't interface changes. - -Be careful with array dimensions - The number of elements in a global array is part of an interface, - even if the header just declares `extern int foo[];'. This is - because on i386 and some other SVR4/ELF systems, when an - application references data in a shared library the size of that - data (whatever its type) is included in the application - executable. If you might want to change the size of an array or - string then provide a pointer not the actual array. - -* Menu: - -* C header files:: How to write portable include files. - - -File: libtool.info, Node: C header files, Up: Library tips - -8.1 Writing C header files -========================== - -Writing portable C header files can be difficult, since they may be read -by different types of compilers: - -C++ compilers - C++ compilers require that functions be declared with full - prototypes, since C++ is more strongly typed than C. C functions - and variables also need to be declared with the `extern "C"' - directive, so that the names aren't mangled. *Note C++ - libraries::, for other issues relevant to using C++ with libtool. - -ANSI C compilers - ANSI C compilers are not as strict as C++ compilers, but functions - should be prototyped to avoid unnecessary warnings when the header - file is `#include'd. - -non-ANSI C compilers - Non-ANSI compilers will report errors if functions are prototyped. - - These complications mean that your library interface headers must use -some C preprocessor magic in order to be usable by each of the above -compilers. - - `foo.h' in the `tests/demo' subdirectory of the libtool distribution -serves as an example for how to write a header file that can be safely -installed in a system directory. - - Here are the relevant portions of that file: - - /* BEGIN_C_DECLS should be used at the beginning of your declarations, - so that C++ compilers don't mangle their names. Use END_C_DECLS at - the end of C declarations. */ - #undef BEGIN_C_DECLS - #undef END_C_DECLS - #ifdef __cplusplus - # define BEGIN_C_DECLS extern "C" { - # define END_C_DECLS } - #else - # define BEGIN_C_DECLS /* empty */ - # define END_C_DECLS /* empty */ - #endif - - /* PARAMS is a macro used to wrap function prototypes, so that - compilers that don't understand ANSI C prototypes still work, - and ANSI C compilers can issue warnings about type mismatches. */ - #undef PARAMS - #if defined (__STDC__) || defined (_AIX) \ - || (defined (__mips) && defined (_SYSTYPE_SVR4)) \ - || defined(WIN32) || defined(__cplusplus) - # define PARAMS(protos) protos - #else - # define PARAMS(protos) () - #endif - - These macros are used in `foo.h' as follows: - - #ifndef FOO_H - #define FOO_H 1 - - /* The above macro definitions. */ - #include "..." - - BEGIN_C_DECLS - - int foo PARAMS((void)); - int hello PARAMS((void)); - - END_C_DECLS - - #endif /* !FOO_H */ - - Note that the `#ifndef FOO_H' prevents the body of `foo.h' from -being read more than once in a given compilation. - - Also the only thing that must go outside the -`BEGIN_C_DECLS'/`END_C_DECLS' pair are `#include' lines. Strictly -speaking it is only C symbol names that need to be protected, but your -header files will be more maintainable if you have a single pair of -these macros around the majority of the header contents. - - You should use these definitions of `PARAMS', `BEGIN_C_DECLS', and -`END_C_DECLS' into your own headers. Then, you may use them to create -header files that are valid for C++, ANSI, and non-ANSI compilers(1). - - Do not be naive about writing portable code. Following the tips -given above will help you miss the most obvious problems, but there are -definitely other subtle portability issues. You may need to cope with -some of the following issues: - - * Pre-ANSI compilers do not always support the `void *' generic - pointer type, and so need to use `char *' in its place. - - * The `const', `inline' and `signed' keywords are not supported by - some compilers, especially pre-ANSI compilers. - - * The `long double' type is not supported by many compilers. - - ---------- Footnotes ---------- - - (1) We used to recommend `__P', `__BEGIN_DECLS' and `__END_DECLS'. -This was bad advice since symbols (even preprocessor macro names) that -begin with an underscore are reserved for the use of the compiler. - - -File: libtool.info, Node: Inter-library dependencies, Next: Dlopened modules, Prev: Library tips, Up: Top - -9 Inter-library dependencies -**************************** - -By definition, every shared library system provides a way for -executables to depend on libraries, so that symbol resolution is -deferred until runtime. - - An "inter-library dependency" is one in which a library depends on -other libraries. For example, if the libtool library `libhello' uses -the `cos' function, then it has an inter-library dependency on `libm', -the math library that implements `cos'. - - Some shared library systems provide this feature in an -internally-consistent way: these systems allow chains of dependencies of -potentially infinite length. - - However, most shared library systems are restricted in that they only -allow a single level of dependencies. In these systems, programs may -depend on shared libraries, but shared libraries may not depend on other -shared libraries. - - In any event, libtool provides a simple mechanism for you to declare -inter-library dependencies: for every library `libNAME' that your own -library depends on, simply add a corresponding `-lNAME' option to the -link line when you create your library. To make an example of our -`libhello' that depends on `libm': - - burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ - -rpath /usr/local/lib -lm - burger$ - - When you link a program against `libhello', you don't need to -specify the same `-l' options again: libtool will do that for you, in -order to guarantee that all the required libraries are found. This -restriction is only necessary to preserve compatibility with static -library systems and simple dynamic library systems. - - Some platforms, such as Windows, do not even allow you this -flexibility. In order to build a shared library, it must be entirely -self-contained or it must have dependencies known at link time (that is, -have references only to symbols that are found in the `.lo' files or -the specified `-l' libraries), and you need to specify the -`-no-undefined' flag. By default, libtool builds only static libraries -on these kinds of platforms. - - The simple-minded inter-library dependency tracking code of libtool -releases prior to 1.2 was disabled because it was not clear when it was -possible to link one library with another, and complex failures would -occur. A more complex implementation of this concept was re-introduced -before release 1.3, but it has not been ported to all platforms that -libtool supports. The default, conservative behavior is to avoid -linking one library with another, introducing their inter-dependencies -only when a program is linked with them. - - -File: libtool.info, Node: Dlopened modules, Next: Using libltdl, Prev: Inter-library dependencies, Up: Top - -10 Dlopened modules -******************* - -It can sometimes be confusing to discuss "dynamic linking", because the -term is used to refer to two different concepts: - - 1. Compiling and linking a program against a shared library, which is - resolved automatically at run time by the dynamic linker. In this - process, dynamic linking is transparent to the application. - - 2. The application calling functions such as `dlopen' that load - arbitrary, user-specified modules at runtime. This type of dynamic - linking is explicitly controlled by the application. - - To mitigate confusion, this manual refers to the second type of -dynamic linking as "dlopening" a module. - - The main benefit to dlopening object modules is the ability to access -compiled object code to extend your program, rather than using an -interpreted language. In fact, dlopen calls are frequently used in -language interpreters to provide an efficient way to extend the -language. - - Libtool provides support for dlopened modules. However, you should -indicate that your package is willing to use such support, by using the -`LT_INIT' option `dlopen' in `configure.ac'. If this option is not -given, libtool will assume no dlopening mechanism is available, and -will try to simulate it. - - This chapter discusses how you as a dlopen application developer -might use libtool to generate dlopen-accessible modules. - -* Menu: - -* Building modules:: Creating dlopenable objects and libraries. -* Dlpreopening:: Dlopening that works on static platforms. -* Linking with dlopened modules:: Using dlopenable modules in libraries. -* Finding the dlname:: Choosing the right file to `dlopen'. -* Dlopen issues:: Unresolved problems that need your attention. - - -File: libtool.info, Node: Building modules, Next: Dlpreopening, Up: Dlopened modules - -10.1 Building modules to dlopen -=============================== - -On some operating systems, a program symbol must be specially declared -in order to be dynamically resolved with the `dlsym' (or equivalent) -function. Libtool provides the `-export-dynamic' and `-module' link -flags (*note Link mode::), for you to make that declaration. You need -to use these flags if you are linking an application program that -dlopens other modules or a libtool library that will also be dlopened. - - For example, if we wanted to build a shared library, `hello', that -would later be dlopened by an application, we would add `-module' to -the other link flags: - - burger$ libtool --mode=link gcc -module -o hello.la foo.lo \ - hello.lo -rpath /usr/local/lib -lm - burger$ - - If symbols from your _executable_ are needed to satisfy unresolved -references in a library you want to dlopen you will have to use the flag -`-export-dynamic'. You should use `-export-dynamic' while linking the -executable that calls dlopen: - - burger$ libtool --mode=link gcc -export-dynamic -o helldl main.o - burger$ - - -File: libtool.info, Node: Dlpreopening, Next: Linking with dlopened modules, Prev: Building modules, Up: Dlopened modules - -10.2 Dlpreopening -================= - -Libtool provides special support for dlopening libtool object and -libtool library files, so that their symbols can be resolved _even on -platforms without any `dlopen' and `dlsym' functions_. - - Consider the following alternative ways of loading code into your -program, in order of increasing "laziness": - - 1. Linking against object files that become part of the program - executable, whether or not they are referenced. If an object file - cannot be found, then the compile time linker refuses to create - the executable. - - 2. Declaring a static library to the linker, so that it is searched - at link time in order to satisfy any undefined references in the - above object files. If the static library cannot be found, then - the compile time linker refuses to create the executable. - - 3. Declaring a shared library to the runtime linker, so that it is - searched at runtime in order to satisfy any undefined references - in the above files. If the shared library cannot be found, then - the dynamic linker aborts the program before it runs. - - 4. Dlopening a module, so that the application can resolve its own, - dynamically-computed references. If there is an error opening the - module, or the module is not found, then the application can - recover without crashing. - - Libtool emulates `-dlopen' on static platforms by linking objects -into the program at compile time, and creating data structures that -represent the program's symbol table. In order to use this feature, -you must declare the objects you want your application to dlopen by -using the `-dlopen' or `-dlpreopen' flags when you link your program -(*note Link mode::). - - -- Data Type: lt_dlsymlist typedef struct { const char *NAME; - void *ADDRESS; } lt_dlsymlist - The NAME attribute is a null-terminated character string of the - symbol name, such as `"fprintf"'. The ADDRESS attribute is a - generic pointer to the appropriate object, such as `&fprintf'. - - -- Variable: const lt_dlsymlist lt_preloaded_symbols[] - An array of `lt_dlsymlist' structures, representing all the - preloaded symbols linked into the program proper. For each module - `-dlpreopen'ed by the Libtool linked program there is an element - with the NAME of the module and an ADDRESS of `0', followed by all - symbols exported from this file. For the executable itself the - special name `@PROGRAM@' is used. The last element of all has a - NAME and ADDRESS of `0'. - - To facilitate inclusion of symbol lists into libraries, - `lt_preloaded_symbols' is `#define'd to a suitably unique name in - `ltdl.h'. - - This variable may not be declared `const' on some systems due to - relocation issues. - - Some compilers may allow identifiers that are not valid in ANSI C, -such as dollar signs. Libtool only recognizes valid ANSI C symbols (an -initial ASCII letter or underscore, followed by zero or more ASCII -letters, digits, and underscores), so non-ANSI symbols will not appear -in `lt_preloaded_symbols'. - - -- Function: int lt_dlpreload (const lt_dlsymlist *PRELOADED) - Register the list of preloaded modules PRELOADED. If PRELOADED is - `NULL', then all previously registered symbol lists, except the - list set by `lt_dlpreload_default', are deleted. Return 0 on - success. - - -- Function: int lt_dlpreload_default (const lt_dlsymlist *PRELOADED) - Set the default list of preloaded modules to PRELOADED, which - won't be deleted by `lt_dlpreload'. Note that this function does - _not_ require libltdl to be initialized using `lt_dlinit' and can - be used in the program to register the default preloaded modules. - Instead of calling this function directly, most programs will use - the macro `LTDL_SET_PRELOADED_SYMBOLS'. - - Return 0 on success. - - -- Macro: LTDL_SET_PRELOADED_SYMBOLS - Set the default list of preloaded symbols. Should be used in your - program to initialize libltdl's list of preloaded modules. - - #include <ltdl.h> - - int main() { - /* ... */ - LTDL_SET_PRELOADED_SYMBOLS(); - /* ... */ - } - - -- Function Type: int lt_dlpreload_callback_func (lt_dlhandle HANDLE) - Functions of this type can be passed to `lt_dlpreload_open', which - in turn will call back into a function thus passed for each - preloaded module that it opens. - - -- Function: int lt_dlpreload_open (const char *ORIGINATOR, - lt_dlpreload_callback_func *FUNC) - Load all of the preloaded modules for ORIGINATOR. For every - module opened in this way, call FUNC. - - To open all of the modules preloaded into `libhell.la' (presumably - from within the `libhell.a' initialisation code): - - #define preloaded_symbols lt_libhell_LTX_preloaded_symbols - - static int hell_preload_callback (lt_dlhandle handle); - - int - hell_init (void) - { - ... - if (lt_dlpreload (&preloaded_symbols) == 0) - { - lt_dlpreload_open ("libhell", preload_callback); - } - ... - } - - Note that to prevent clashes between multiple preloaded modules, - the preloaded symbols are accessed via a mangled symbol name: to - get the symbols preloaded into `libhell', you must prefix - `preloaded_symbols' with `lt_'; the originator name, `libhell' in - this case; and `_LTX_'. That is, - `lt_libhell_LTX_preloaded_symbols' here. - - -File: libtool.info, Node: Linking with dlopened modules, Next: Finding the dlname, Prev: Dlpreopening, Up: Dlopened modules - -10.3 Linking with dlopened modules -================================== - -When, say, an interpreter application uses dlopened modules to extend -the list of methods it provides, an obvious abstraction for the -maintainers of the interpreter is to have all methods (including the -built in ones supplied with the interpreter) accessed through dlopen. -For one thing, the dlopening functionality will be tested even during -routine invocations. For another, only one subsystem has to be written -for getting methods into the interpreter. - - The downside of this abstraction is, of course, that environments -that provide only static linkage can't even load the intrinsic -interpreter methods. Not so! We can statically link those methods by -*dlpreopening* them. - - Unfortunately, since platforms such as AIX and cygwin require that -all library symbols must be resolved at compile time, the interpreter -maintainers will need to provide a library to both its own dlpreopened -modules, and third-party modules loaded by dlopen. In itself, that is -not so bad, except that the interpreter too must provide those same -symbols otherwise it will be impossible to resolve all the symbols -required by the modules as they are loaded. Things are even worse if -the code that loads the modules for the interpreter is itself in a -library - and that is usually the case for any non-trivial application. -Modern platforms take care of this by automatically loading all of a -module's dependency libraries as the module is loaded (libltdl can do -this even on platforms that can't do it by themselves). In the end, -this leads to problems with duplicated symbols and prevents modules -from loading, and prevents the application from compiling when modules -are preloaded. - - ,-------------. ,------------------. ,-----------------. - | Interpreter |----> Module------------> Third-party | - `-------------' | Loader | |Dlopened Modules | - | | | `-----------------' - |,-------v--------.| | - || Dlpreopened || | - || Modules || | - |`----------------'| | - | | | | - |,-------v--------.| ,--------v--------. - ||Module Interface|| |Module Interface | - || Library || | Library | - |`----------------'| `-----------------' - `------------------' - - Libtool has the concept of "weak library interfaces" to circumvent -this problem. Recall that the code that dlopens method-provider -modules for the interpreter application resides in a library: All of -the modules and the dlopener library itself should be linked against -the common library that resolves the module symbols at compile time. -To guard against duplicate symbol definitions, and for dlpreopened -modules to work at all in this scenario, the dlopener library must -declare that it provides a weak library interface to the common symbols -in the library it shares with the modules. That way, when `libtool' -links the *Module Loader* library with some *Dlpreopened Modules* that -were in turn linked against the *Module Interface Library*, it knows -that the *Module Loader* provides an already loaded *Module Interface -Library* to resolve symbols for the *Dlpreopened Modules*, and doesn't -ask the compiler driver to link an identical *Module Interface Library* -dependency library too. - - In conjunction with Automake, the `Makefile.am' for the *Module -Loader* might look like this: - - lib_LTLIBRARIES = libinterface.la libloader.la - - libinterface_la_SOURCES = interface.c interface.h - libinterface_la_LDFLAGS = -version-info 3:2:1 - - libloader_la_SOURCES = loader.c - libloader_la_LDFLAGS = -weak libinterface.la \ - -version-info 3:2:1 \ - -dlpreopen ../modules/intrinsics.la - libloader_la_LIBADD = $(libinterface_la_OBJECTS) - - And the `Makefile.am' for the `intrinsics.la' module in a sibling -`modules' directory might look like this: - - AM_CPPFLAGS = -I$(srcdir)/../libloader - AM_LDFLAGS = -no-undefined -module -avoid-version \ - -export-dynamic - - noinst_LTLIBRARIES = intrinsics.la - - intrinsics_la_LIBADD = ../libloader/libinterface.la - - ../libloader/libinterface.la: - cd ../libloader && $(MAKE) $(AM_MAKEFLAGS) libinterface.la - - For a more complex example, see the sources of `libltdl' in the -Libtool distribution, which is built with the help of the `-weak' -option. - - -File: libtool.info, Node: Finding the dlname, Next: Dlopen issues, Prev: Linking with dlopened modules, Up: Dlopened modules - -10.4 Finding the correct name to dlopen -======================================= - -After a library has been linked with `-module', it can be dlopened. -Unfortunately, because of the variation in library names, your package -needs to determine the correct file to dlopen. - - The most straightforward and flexible implementation is to determine -the name at runtime, by finding the installed `.la' file, and searching -it for the following lines: - - # The name that we can `dlopen'. - dlname='DLNAME' - - If DLNAME is empty, then the library cannot be dlopened. Otherwise, -it gives the dlname of the library. So, if the library was installed -as `/usr/local/lib/libhello.la', and the DLNAME was `libhello.so.3', -then `/usr/local/lib/libhello.so.3' should be dlopened. - - If your program uses this approach, then it should search the -directories listed in the `LD_LIBRARY_PATH'(1) environment variable, as -well as the directory where libraries will eventually be installed. -Searching this variable (or equivalent) will guarantee that your -program can find its dlopened modules, even before installation, -provided you have linked them using libtool. - - ---------- Footnotes ---------- - - (1) `LIBPATH' on AIX, and `SHLIB_PATH' on HP-UX. - - -File: libtool.info, Node: Dlopen issues, Prev: Finding the dlname, Up: Dlopened modules - -10.5 Unresolved dlopen issues -============================= - -The following problems are not solved by using libtool's dlopen support: - - * Dlopen functions are generally only available on shared library - platforms. If you want your package to be portable to static - platforms, you have to use either libltdl (*note Using libltdl::) - or develop your own alternatives to dlopening dynamic code. Most - reasonable solutions involve writing wrapper functions for the - `dlopen' family, which do package-specific tricks when dlopening - is unsupported or not available on a given platform. - - * There are major differences in implementations of the `dlopen' - family of functions. Some platforms do not even use the same - function names (notably HP-UX, with its `shl_load' family). - - * The application developer must write a custom search function in - order to discover the correct module filename to supply to - `dlopen'. - - -File: libtool.info, Node: Using libltdl, Next: Trace interface, Prev: Dlopened modules, Up: Top - -11 Using libltdl -**************** - -Libtool provides a small library, called `libltdl', that aims at hiding -the various difficulties of dlopening libraries from programmers. It -consists of a few headers and small C source files that can be -distributed with applications that need dlopening functionality. On -some platforms, whose dynamic linkers are too limited for a simple -implementation of `libltdl' services, it requires GNU DLD, or it will -only emulate dynamic linking with libtool's dlpreopening mechanism. - -libltdl supports currently the following dynamic linking mechanisms: - - * `dlopen' (POSIX compliant systems, GNU/Linux, etc.) - - * `shl_load' (HP-UX) - - * `LoadLibrary' (Win16 and Win32) - - * `load_add_on' (BeOS) - - * `NSAddImage' or `NSLinkModule' (Darwin and Mac OS X) - - * GNU DLD (emulates dynamic linking for static libraries) - - * libtool's dlpreopen (see *note Dlpreopening::) - -libltdl is licensed under the terms of the GNU Lesser General Public -License, with the following exception: - - As a special exception to the GNU Lesser General Public License, - if you distribute this file as part of a program or library that - is built using GNU Libtool, you may include it under the same - distribution terms that you use for the rest of that program. - -* Menu: - -* Libltdl interface:: How to use libltdl in your programs. -* Modules for libltdl:: Creating modules that can be `dlopen'ed. -* Thread Safety in libltdl:: Registering callbacks for multi-thread safety. -* User defined module data:: Associating data with loaded modules. -* Module loaders for libltdl:: Creating user defined module loaders. -* Distributing libltdl:: How to distribute libltdl with your package. - - -File: libtool.info, Node: Libltdl interface, Next: Modules for libltdl, Up: Using libltdl - -11.1 How to use libltdl in your programs -======================================== - -The libltdl API is similar to the POSIX dlopen interface, which is very -simple but powerful. - -To use libltdl in your program you have to include the header file -`ltdl.h': - - #include <ltdl.h> - -The early releases of libltdl used some symbols that violated the POSIX -namespace conventions. These symbols are now deprecated, and have been -replaced by those described here. If you have code that relies on the -old deprecated symbol names, defining `LT_NON_POSIX_NAMESPACE' before -you include `ltdl.h' provides conversion macros. Whichever set of -symbols you use, the new API is not binary compatible with the last, so -you will need to recompile your application in order to use this -version of libltdl. - -Note that libltdl is not well tested in a multithreaded environment, -though the intention is that it should work (*note Using libltdl in a -multi threaded environment: Thread Safety in libltdl.). It was -reported that GNU/Linux's glibc 2.0's `dlopen' with `RTLD_LAZY' (which -libltdl uses by default) is not thread-safe, but this problem is -supposed to be fixed in glibc 2.1. On the other hand, `RTLD_NOW' was -reported to introduce problems in multi-threaded applications on -FreeBSD. Working around these problems is left as an exercise for the -reader; contributions are certainly welcome. - -The following macros are defined by including `ltdl.h': - - -- Macro: LT_PATHSEP_CHAR - `LT_PATHSEP_CHAR' is the system-dependent path separator, that is, - `;' on Windows and `:' everywhere else. - - -- Macro: LT_DIRSEP_CHAR - If `LT_DIRSEP_CHAR' is defined, it can be used as directory - separator in addition to `/'. On Windows, this contains `\'. - -The following types are defined in `ltdl.h': - - -- Type: lt_dlhandle - `lt_dlhandle' is a module "handle". Every lt_dlopened module has - a handle associated with it. - - -- Type: lt_dladvise - `lt_dladvise' is used to control optional module loading modes. - If it is not used, the default mode of the underlying system module - loader is used. - - -- Type: lt_dlsymlist - `lt_dlsymlist' is a symbol list for dlpreopened modules. This - structure is described in *note Dlpreopening::. - -libltdl provides the following functions: - - -- Function: int lt_dlinit (void) - Initialize libltdl. This function must be called before using - libltdl and may be called several times. Return 0 on success, - otherwise the number of errors. - - -- Function: int lt_dlexit (void) - Shut down libltdl and close all modules. This function will only - then shut down libltdl when it was called as many times as - `lt_dlinit' has been successfully called. Return 0 on success, - otherwise the number of errors. - - -- Function: lt_dlhandle lt_dlopen (const char *FILENAME) - Open the module with the file name FILENAME and return a handle - for it. `lt_dlopen' is able to open libtool dynamic modules, - preloaded static modules, the program itself and native dynamic - modules(1). - - Unresolved symbols in the module are resolved using its dependency - libraries and previously dlopened modules. If the executable using - this module was linked with the `-export-dynamic' flag, then the - global symbols in the executable will also be used to resolve - references in the module. - - If FILENAME is `NULL' and the program was linked with - `-export-dynamic' or `-dlopen self', `lt_dlopen' will return a - handle for the program itself, which can be used to access its - symbols. - - If libltdl cannot find the library and the file name FILENAME does - not have a directory component it will additionally look in the - following search paths for the module (in the following order): - - 1. user-defined search path: This search path can be changed by - the program using the functions `lt_dlsetsearchpath', - `lt_dladdsearchdir' and `lt_dlinsertsearchdir'. - - 2. libltdl's search path: This search path is the value of the - environment variable `LTDL_LIBRARY_PATH'. - - 3. system library search path: The system dependent library - search path (e.g. on GNU/Linux it is `LD_LIBRARY_PATH'). - - Each search path must be a list of absolute directories separated - by `LT_PATHSEP_CHAR', for example, `"/usr/lib/mypkg:/lib/foo"'. - The directory names may not contain the path separator. - - If the same module is loaded several times, the same handle is - returned. If `lt_dlopen' fails for any reason, it returns `NULL'. - - -- Function: lt_dlhandle lt_dlopenext (const char *FILENAME) - The same as `lt_dlopen', except that it tries to append different - file name extensions to the file name. If the file with the file - name FILENAME cannot be found libltdl tries to append the - following extensions: - - 1. the libtool archive extension `.la' - - 2. the extension used for native dynamically loadable modules on - the host platform, e.g., `.so', `.sl', etc. - - This lookup strategy was designed to allow programs that don't - have knowledge about native dynamic libraries naming conventions - to be able to `dlopen' such libraries as well as libtool modules - transparently. - - -- Function: lt_dlhandle lt_dlopenadvise (const char *FILENAME, - lt_dladvise ADVISE) - The same as `lt_dlopen', except that it also requires an additional - argument which may contain additional hints to the underlying - system module loader. The ADVISE parameter is opaque and can only - be accessed with the functions documented below. - - Note that this function does not change the content of ADVISE, so - unlike the other calls in this API takes a direct `lt_dladvise' - type, and not a pointer to the same. - - -- Function: int lt_dladvise_init (lt_dladvise *ADVISE) - The ADVISE parameter can be used to pass hints to the module - loader when using `lt_dlopenadvise' to perform the loading. The - ADVISE parameter needs to be initialised by this function before - it can be used. Any memory used by ADVISE needs to be recycled - with `lt_dladvise_destroy' when it is no longer needed. - - On failure, `lt_dladvise_init' returns non-zero and sets an error - message that can be retrieved with `lt_dlerror'. - - -- Function: int lt_dladvise_destroy (lt_dladvise *ADVISE) - Recycle the memory used by ADVISE. For an example, see the - documentation for `lt_dladvise_ext'. - - On failure, `lt_dladvise_destroy' returns non-zero and sets an - error message that can be retrieved with `lt_dlerror'. - - -- Function: int lt_dladvise_ext (lt_dladvise *ADVISE) - Set the `ext' hint on ADVISE. Passing an ADVISE parameter to - `lt_dlopenadvise' with this hint set causes it to try to append - different file name extensions like `lt_dlopenext'. - - The following example is equivalent to calling `lt_dlopenext - (filename)': - - lt_dlhandle - my_dlopenext (const char *filename) - { - lt_dlhandle handle = 0; - lt_dladvise advise; - - if (!lt_dladvise_init (&advise) && !lt_dladvise_ext (&advise)) - handle = lt_dlopenadvise (filename, advise); - - lt_dladvise_destroy (&advise); - - return handle; - } - - On failure, `lt_dladvise_ext' returns non-zero and sets an error - message that can be retrieved with `lt_dlerror'. - - -- Function: int lt_dladvise_global (lt_dladvise *ADVISE) - Set the `symglobal' hint on ADVISE. Passing an ADVISE parameter - to `lt_dlopenadvise' with this hint set causes it to try to make - the loaded module's symbols globally available for resolving - unresolved symbols in subsequently loaded modules. - - If neither the `symglobal' nor the `symlocal' hints are set, or if - a module is loaded without using the `lt_dlopenadvise' call in any - case, then the visibility of the module's symbols will be as per - the default for the underlying module loader and OS. Even if a - suitable hint is passed, not all loaders are able to act upon it in - which case `lt_dlgetinfo' will reveal whether the hint was actually - followed. - - On failure, `lt_dladvise_global' returns non-zero and sets an error - message that can be retrieved with `lt_dlerror'. - - -- Function: int lt_dladvise_local (lt_dladvise *ADVISE) - Set the `symlocal' hint on ADVISE. Passing an ADVISE parameter to - `lt_dlopenadvise' with this hint set causes it to try to keep the - loaded module's symbols hidden so that they are not visible to - subsequently loaded modules. - - If neither the `symglobal' nor the `symlocal' hints are set, or if - a module is loaded without using the `lt_dlopenadvise' call in any - case, then the visibility of the module's symbols will be as per - the default for the underlying module loader and OS. Even if a - suitable hint is passed, not all loaders are able to act upon it in - which case `lt_dlgetinfo' will reveal whether the hint was actually - followed. - - On failure, `lt_dladvise_local' returns non-zero and sets an error - message that can be retrieved with `lt_dlerror'. - - -- Function: int lt_dladvise_resident (lt_dladvise *ADVISE) - Set the `resident' hint on ADVISE. Passing an ADVISE parameter to - `lt_dlopenadvise' with this hint set causes it to try to make the - loaded module resident in memory, so that it cannot be unloaded - with a later call to `lt_dlclose'. - - On failure, `lt_dladvise_resident' returns non-zero and sets an - error message that can be retrieved with `lt_dlerror'. - - -- Function: int lt_dladvise_preload (lt_dladvise *ADVISE) - Set the `preload' hint on ADVISE. Passing an ADVISE parameter to - `lt_dlopenadvise' with this hint set causes it to load only - preloaded modules, so that if a suitable preloaded module is not - found, `lt_dlopenadvise' will return `NULL'. - - -- Function: int lt_dlclose (lt_dlhandle HANDLE) - Decrement the reference count on the module HANDLE. If it drops - to zero and no other module depends on this module, then the - module is unloaded. Return 0 on success. - - -- Function: void * lt_dlsym (lt_dlhandle HANDLE, const char *NAME) - Return the address in the module HANDLE, where the symbol given by - the null-terminated string NAME is loaded. If the symbol cannot - be found, `NULL' is returned. - - -- Function: const char * lt_dlerror (void) - Return a human readable string describing the most recent error - that occurred from any of libltdl's functions. Return `NULL' if - no errors have occurred since initialization or since it was last - called. - - -- Function: int lt_dladdsearchdir (const char *SEARCH_DIR) - Append the search directory SEARCH_DIR to the current user-defined - library search path. Return 0 on success. - - -- Function: int lt_dlinsertsearchdir (const char *BEFORE, - const char *SEARCH_DIR) - Insert the search directory SEARCH_DIR into the user-defined - library search path, immediately before the element starting at - address BEFORE. If BEFORE is `NULL', then SEARCH_DIR is appending - as if `lt_dladdsearchdir' had been called. Return 0 on success. - - -- Function: int lt_dlsetsearchpath (const char *SEARCH_PATH) - Replace the current user-defined library search path with - SEARCH_PATH, which must be a list of absolute directories separated - by `LT_PATHSEP_CHAR'. Return 0 on success. - - -- Function: const char * lt_dlgetsearchpath (void) - Return the current user-defined library search path. - - -- Function: int lt_dlforeachfile (const char *SEARCH_PATH, - int (*FUNC) (const char *FILENAME, void * DATA), void * DATA) - In some applications you may not want to load individual modules - with known names, but rather find all of the modules in a set of - directories and load them all during initialisation. With this - function you can have libltdl scan the `LT_PATHSEP_CHAR'-delimited - directory list in SEARCH_PATH for candidates, and pass them, along - with DATA to your own callback function, FUNC. If SEARCH_PATH is - `NULL', then search all of the standard locations that `lt_dlopen' - would examine. This function will continue to make calls to FUNC - for each file that it discovers in SEARCH_PATH until one of these - calls returns non-zero, or until the files are exhausted. - `lt_dlforeachfile' returns the value returned by the last call - made to FUNC. - - For example you could define FUNC to build an ordered "argv"-like - vector of files using DATA to hold the address of the start of the - vector. - - -- Function: int lt_dlmakeresident (lt_dlhandle HANDLE) - Mark a module so that it cannot be `lt_dlclose'd. This can be - useful if a module implements some core functionality in your - project that would cause your code to crash if removed. Return 0 - on success. - - If you use `lt_dlopen (NULL)' to get a HANDLE for the running - binary, that handle will always be marked as resident, and - consequently cannot be successfully `lt_dlclose'd. - - -- Function: int lt_dlisresident (lt_dlhandle HANDLE) - Check whether a particular module has been marked as resident, - returning 1 if it has or 0 otherwise. If there is an error while - executing this function, return -1 and set an error message for - retrieval with `lt_dlerror'. - - ---------- Footnotes ---------- - - (1) Some platforms, notably Mac OS X, differentiate between a -runtime library that cannot be opened by `lt_dlopen' and a dynamic -module that can. For maximum portability you should try to ensure that -you only pass `lt_dlopen' objects that have been compiled with libtool's -`-module' flag. - - -File: libtool.info, Node: Modules for libltdl, Next: Thread Safety in libltdl, Prev: Libltdl interface, Up: Using libltdl - -11.2 Creating modules that can be `dlopen'ed -============================================ - -Libtool modules are created like normal libtool libraries with a few -exceptions: - - You have to link the module with libtool's `-module' switch, and you -should link any program that is intended to dlopen the module with -`-dlopen MODULENAME.LA' where possible, so that libtool can dlpreopen -the module on platforms that do not support dlopening. If the module -depends on any other libraries, make sure you specify them either when -you link the module or when you link programs that dlopen it. If you -want to disable versioning (*note Versioning::) for a specific module -you should link it with the `-avoid-version' switch. Note that libtool -modules don't need to have a "lib" prefix. However, Automake 1.4 or -higher is required to build such modules. - - Usually a set of modules provide the same interface, i.e. exports -the same symbols, so that a program can dlopen them without having to -know more about their internals: In order to avoid symbol conflicts all -exported symbols must be prefixed with "modulename_LTX_" (MODULENAME is -the name of the module). Internal symbols must be named in such a way -that they won't conflict with other modules, for example, by prefixing -them with "_modulename_". Although some platforms support having the -same symbols defined more than once it is generally not portable and it -makes it impossible to dlpreopen such modules. - - libltdl will automatically cut the prefix off to get the real name of -the symbol. Additionally, it supports modules that do not use a prefix -so that you can also dlopen non-libtool modules. - - `foo1.c' gives an example of a portable libtool module. Exported -symbols are prefixed with "foo1_LTX_", internal symbols with "_foo1_". -Aliases are defined at the beginning so that the code is more readable. - - /* aliases for the exported symbols */ - #define foo foo1_LTX_foo - #define bar foo1_LTX_bar - - /* a global variable definition */ - int bar = 1; - - /* a private function */ - int _foo1_helper() { - return bar; - } - - /* an exported function */ - int foo() { - return _foo1_helper(); - } - -The `Makefile.am' contains the necessary rules to build the module -`foo1.la': - - ... - lib_LTLIBRARIES = foo1.la - - foo1_la_SOURCES = foo1.c - foo1_la_LDFLAGS = -module - ... - - -File: libtool.info, Node: Thread Safety in libltdl, Next: User defined module data, Prev: Modules for libltdl, Up: Using libltdl - -11.3 Using libltdl in a multi threaded environment -================================================== - -Libltdl provides a wrapper around whatever dynamic run-time object -loading mechanisms are provided by the host system, many of which are -themselves not thread safe. Consequently libltdl cannot itself be -consistently thread safe. - - If you wish to use libltdl in a multithreaded environment, then you -must mutex lock around libltdl calls, since they may in turn be calling -non-thread-safe system calls on some target hosts. - - Some old releases of libtool provided a mutex locking API that was -unusable with POSIX threads, so callers were forced to lock around all -libltdl API calls anyway. That mutex locking API was next to useless, -and is not present in current releases. - - Some future release of libtool may provide a new POSIX thread -compliant mutex locking API. - - -File: libtool.info, Node: User defined module data, Next: Module loaders for libltdl, Prev: Thread Safety in libltdl, Up: Using libltdl - -11.4 Data associated with loaded modules -======================================== - -Some of the internal information about each loaded module that is -maintained by libltdl is available to the user, in the form of this -structure: - - -- Type: struct lt_dlinfo { char *FILENAME; char *NAME; int REF_COUNT; - int IS_RESIDENT; int IS_SYMGLOBAL; int IS_SYMLOCAL;} - `lt_dlinfo' is used to store information about a module. The - FILENAME attribute is a null-terminated character string of the - real module file name. If the module is a libtool module then - NAME is its module name (e.g. `"libfoo"' for `"dir/libfoo.la"'), - otherwise it is set to `NULL'. The REF_COUNT attribute is a - reference counter that describes how often the same module is - currently loaded. The remaining fields can be compared to any - hints that were passed to `lt_dlopenadvise' to determine whether - the underlying loader was able to follow them. - - The following function will return a pointer to libltdl's internal -copy of this structure for the given HANDLE: - - -- Function: const lt_dlinfo * lt_dlgetinfo (lt_dlhandle HANDLE) - Return a pointer to a struct that contains some information about - the module HANDLE. The contents of the struct must not be - modified. Return `NULL' on failure. - - Furthermore, in order to save you from having to keep a list of the -handles of all the modules you have loaded, these functions allow you to -iterate over libltdl's list of loaded modules: - - -- Type: lt_dlinterface_id - The opaque type used to hold the module interface details for each - registered libltdl client. - - -- Type: int lt_dlhandle_interface (lt_dlhandle HANDLE, - const char *ID_STRING) - Functions of this type are called to check that a handle conforms - to a library's expected module interface when iterating over the - global handle list. You should be careful to write a callback - function of this type that can correctly identify modules that - belong to this client, both to prevent other clients from - accidentally finding your loaded modules with the iterator - functions below, and vice versa. The best way to do this is to - check that module HANDLE conforms to the interface specification - of your loader using `lt_dlsym'. - - The callback may be given *every* module loaded by all the libltdl - module clients in the current address space, including any modules - loaded by other libraries such as libltdl itself, and should - return non-zero if that module does not fulfill the interface - requirements of your loader. - - int - my_interface_cb (lt_dlhandle handle, const char *id_string) - { - char *(*module_id) (void) = NULL; - - /* A valid my_module must provide all of these symbols. */ - if (!((module_id = (char*(*)(void)) lt_dlsym ("module_version")) - && lt_dlsym ("my_module_entrypoint"))) - return 1; - - if (strcmp (id_string, module_id()) != 0) - return 1; - - return 0; - } - - -- Function: lt_dlinterface_id lt_dlinterface_register - (const char *ID_STRING, lt_dlhandle_interface *IFACE) - Use this function to register your interface validator with - libltdl, and in return obtain a unique key to store and retrieve - per-module data. You supply an ID_STRING and IFACE so that the - resulting `lt_dlinterface_id' can be used to filter the module - handles returned by the iteration functions below. If IFACE is - `NULL', all modules will be matched. - - -- Function: void lt_dlinterface_free (lt_dlinterface_id IFACE) - Release the data associated with IFACE. - - -- Function: int lt_dlhandle_map (lt_dlinterface_id IFACE, - int (*FUNC) (lt_dlhandle HANDLE, void * DATA), void * DATA) - For each module that matches IFACE, call the function FUNC. When - writing the FUNC callback function, the argument HANDLE is the - handle of a loaded module, and DATA is the last argument passed to - `lt_dlhandle_map'. As soon as FUNC returns a non-zero value for - one of the handles, `lt_dlhandle_map' will stop calling FUNC and - immediately return that non-zero value. Otherwise 0 is eventually - returned when FUNC has been successfully called for all matching - modules. - - -- Function: lt_dlhandle lt_dlhandle_iterate - (lt_dlinterface_id IFACE, lt_dlhandle PLACE) - Iterate over the module handles loaded by IFACE, returning the - first matching handle in the list if PLACE is `NULL', and the next - one on subsequent calls. If PLACE is the last element in the list - of eligible modules, this function returns `NULL'. - - lt_dlhandle handle = 0; - lt_dlinterface_id iface = my_interface_id; - - while ((handle = lt_dlhandle_iterate (iface, handle))) - { - ... - } - - -- Function: lt_dlhandle lt_dlhandle_fetch (lt_dlinterface_id IFACE, - const char *MODULE_NAME) - Search through the module handles loaded by IFACE for a module - named MODULE_NAME, returning its handle if found or else `NULL' if - no such named module has been loaded by IFACE. - - However, you might still need to maintain your own list of loaded -module handles (in parallel with the list maintained inside libltdl) if -there were any other data that your application wanted to associate -with each open module. Instead, you can use the following API calls to -do that for you. You must first obtain a unique interface id from -libltdl as described above, and subsequently always use it to retrieve -the data you stored earlier. This allows different libraries to each -store their own data against loaded modules, without interfering with -one another. - - -- Function: void * lt_dlcaller_set_data (lt_dlinterface_id KEY, - lt_dlhandle HANDLE, void * DATA) - Set DATA as the set of data uniquely associated with KEY and - HANDLE for later retrieval. This function returns the DATA - previously associated with KEY and HANDLE if any. A result of 0, - may indicate that a diagnostic for the last error (if any) is - available from `lt_dlerror()'. - - For example, to correctly remove some associated data: - - void *stale = lt_dlcaller_set_data (key, handle, 0); - if (stale != NULL) - { - free (stale); - } - else - { - char *error_msg = lt_dlerror (); - - if (error_msg != NULL) - { - my_error_handler (error_msg); - return STATUS_FAILED; - } - } - - -- Function: void * lt_dlcaller_get_data (lt_dlinterface_id KEY, - lt_dlhandle HANDLE) - Return the address of the data associated with KEY and HANDLE, or - else `NULL' if there is none. - - Old versions of libltdl also provided a simpler, but similar, API -based around `lt_dlcaller_id'. Unfortunately, it had no provision for -detecting whether a module belonged to a particular interface as -libltdl didn't support multiple loaders in the same address space at -that time. Those APIs are no longer supported as there would be no way -to stop clients of the old APIs from seeing (and accidentally altering) -modules loaded by other libraries. - - -File: libtool.info, Node: Module loaders for libltdl, Next: Distributing libltdl, Prev: User defined module data, Up: Using libltdl - -11.5 How to create and register new module loaders -================================================== - -Sometimes libltdl's many ways of gaining access to modules are not -sufficient for the purposes of a project. You can write your own -loader, and register it with libltdl so that `lt_dlopen' will be able -to use it. - - Writing a loader involves writing at least three functions that can -be called by `lt_dlopen', `lt_dlsym' and `lt_dlclose'. Optionally, you -can provide a finalisation function to perform any cleanup operations -when `lt_dlexit' executes, and a symbol prefix string that will be -prepended to any symbols passed to `lt_dlsym'. These functions must -match the function pointer types below, after which they can be -allocated to an instance of `lt_user_dlloader' and registered. - - Registering the loader requires that you choose a name for it, so -that it can be recognised by `lt_dlloader_find' and removed with -`lt_dlloader_remove'. The name you choose must be unique, and not -already in use by libltdl's builtin loaders: - -"dlopen" - The system dynamic library loader, if one exists. - -"dld" - The GNU dld loader, if `libdld' was installed when libltdl was - built. - -"dlpreload" - The loader for `lt_dlopen'ing of preloaded static modules. - - The prefix "dl" is reserved for loaders supplied with future -versions of libltdl, so you should not use that for your own loader -names. - -The following types are defined in `ltdl.h': - - -- Type: lt_module - `lt_module' is a dlloader dependent module. The dynamic module - loader extensions communicate using these low level types. - - -- Type: lt_dlloader - `lt_dlloader' is a handle for module loader types. - - -- Type: lt_user_data - `lt_user_data' is used for specifying loader instance data. - - -- Type: struct lt_user_dlloader {const char *SYM_PREFIX; - lt_module_open *MODULE_OPEN; lt_module_close *MODULE_CLOSE; - lt_find_sym *FIND_SYM; lt_dlloader_exit *DLLOADER_EXIT; } - If you want to define a new way to open dynamic modules, and have - the `lt_dlopen' API use it, you need to instantiate one of these - structures and pass it to `lt_dlloader_add'. You can pass whatever - you like in the DLLOADER_DATA field, and it will be passed back as - the value of the first parameter to each of the functions - specified in the function pointer fields. - - -- Type: lt_module lt_module_open (const char *FILENAME) - The type of the loader function for an `lt_dlloader' module - loader. The value set in the dlloader_data field of the `struct - lt_user_dlloader' structure will be passed into this function in - the LOADER_DATA parameter. Implementation of such a function - should attempt to load the named module, and return an `lt_module' - suitable for passing in to the associated `lt_module_close' and - `lt_sym_find' function pointers. If the function fails it should - return `NULL', and set the error message with `lt_dlseterror'. - - -- Type: int lt_module_close (lt_user_data LOADER_DATA, - lt_module MODULE) - The type of the unloader function for a user defined module loader. - Implementation of such a function should attempt to release any - resources tied up by the MODULE module, and then unload it from - memory. If the function fails for some reason, set the error - message with `lt_dlseterror' and return non-zero. - - -- Type: void * lt_find_sym (lt_module MODULE, const char *SYMBOL) - The type of the symbol lookup function for a user defined module - loader. Implementation of such a function should return the - address of the named SYMBOL in the module MODULE, or else set the - error message with `lt_dlseterror' and return `NULL' if lookup - fails. - - -- Type: int lt_dlloader_exit (lt_user_data LOADER_DATA) - The type of the finalisation function for a user defined module - loader. Implementation of such a function should free any - resources associated with the loader, including any user specified - data in the `dlloader_data' field of the `lt_user_dlloader'. If - non-`NULL', the function will be called by `lt_dlexit', and - `lt_dlloader_remove'. - - For example: - - int - register_myloader (void) - { - lt_user_dlloader dlloader; - - /* User modules are responsible for their own initialisation. */ - if (myloader_init () != 0) - return MYLOADER_INIT_ERROR; - - dlloader.sym_prefix = NULL; - dlloader.module_open = myloader_open; - dlloader.module_close = myloader_close; - dlloader.find_sym = myloader_find_sym; - dlloader.dlloader_exit = myloader_exit; - dlloader.dlloader_data = (lt_user_data)myloader_function; - - /* Add my loader as the default module loader. */ - if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader, - "myloader") != 0) - return ERROR; - - return OK; - } - - Note that if there is any initialisation required for the loader, it -must be performed manually before the loader is registered - libltdl -doesn't handle user loader initialisation. - - Finalisation _is_ handled by libltdl however, and it is important to -ensure the `dlloader_exit' callback releases any resources claimed -during the initialisation phase. - -libltdl provides the following functions for writing your own module -loaders: - - -- Function: int lt_dlloader_add (lt_dlloader *PLACE, - lt_user_dlloader *DLLOADER, const char *LOADER_NAME) - Add a new module loader to the list of all loaders, either as the - last loader (if PLACE is `NULL'), else immediately before the - loader passed as PLACE. LOADER_NAME will be returned by - `lt_dlloader_name' if it is subsequently passed a newly registered - loader. These LOADER_NAMEs must be unique, or - `lt_dlloader_remove' and `lt_dlloader_find' cannot work. Returns - 0 for success. - - /* Make myloader be the last one. */ - if (lt_dlloader_add (NULL, myloader) != 0) - perror (lt_dlerror ()); - - -- Function: int lt_dlloader_remove (const char *LOADER_NAME) - Remove the loader identified by the unique name, LOADER_NAME. - Before this can succeed, all modules opened by the named loader - must have been closed. Returns 0 for success, otherwise an error - message can be obtained from `lt_dlerror'. - - /* Remove myloader. */ - if (lt_dlloader_remove ("myloader") != 0) - perror (lt_dlerror ()); - - -- Function: lt_dlloader * lt_dlloader_next (lt_dlloader *PLACE) - Iterate over the module loaders, returning the first loader if - PLACE is `NULL', and the next one on subsequent calls. The handle - is for use with `lt_dlloader_add'. - - /* Make myloader be the first one. */ - if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0) - return ERROR; - - -- Function: lt_dlloader * lt_dlloader_find (const char *LOADER_NAME) - Return the first loader with a matching LOADER_NAME identifier, or - else `NULL', if the identifier is not found. - - The identifiers that may be used by libltdl itself, if the host - architecture supports them are "dlopen"(1), "dld" and "dlpreload". - - /* Add a user loader as the next module loader to be tried if - the standard dlopen loader were to fail when lt_dlopening. */ - if (lt_dlloader_add (lt_dlloader_find ("dlopen"), myloader) != 0) - return ERROR; - - -- Function: const char * lt_dlloader_name (lt_dlloader *PLACE) - Return the identifying name of PLACE, as obtained from - `lt_dlloader_next' or `lt_dlloader_find'. If this function fails, - it will return `NULL' and set an error for retrieval with - `lt_dlerror'. - - -- Function: lt_user_data * lt_dlloader_data (lt_dlloader *PLACE) - Return the address of the `dlloader_data' of PLACE, as obtained - from `lt_dlloader_next' or `lt_dlloader_find'. If this function - fails, it will return `NULL' and set an error for retrieval with - `lt_dlerror'. - -11.5.1 Error handling within user module loaders ------------------------------------------------- - - -- Function: int lt_dladderror (const char *DIAGNOSTIC) - This function allows you to integrate your own error messages into - `lt_dlerror'. Pass in a suitable diagnostic message for return by - `lt_dlerror', and an error identifier for use with `lt_dlseterror' - is returned. - - If the allocation of an identifier fails, this function returns -1. - - int myerror = lt_dladderror ("Doh!"); - if (myerror < 0) - perror (lt_dlerror ()); - - -- Function: int lt_dlseterror (int ERRORCODE) - When writing your own module loaders, you should use this function - to raise errors so that they are propagated through the - `lt_dlerror' interface. All of the standard errors used by - libltdl are declared in `ltdl.h', or you can add more of your own - with `lt_dladderror'. This function returns 0 on success. - - if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0) - perror (lt_dlerror ()); - ----------- Footnotes ---------- - - (1) This is used for the host dependent module loading API - -`shl_load' and `LoadLibrary' for example - - -File: libtool.info, Node: Distributing libltdl, Prev: Module loaders for libltdl, Up: Using libltdl - -11.6 How to distribute libltdl with your package -================================================ - -Even though libltdl is installed together with libtool, you may wish to -include libltdl in the distribution of your package, for the -convenience of users of your package that don't have libtool or libltdl -installed, or if you are using features of a very new version of -libltdl that you don't expect your users to have yet. In such cases, -you must decide which flavor of libltdl you want to use: a convenience -library or an installable libtool library. - - The most simplistic way to add `libltdl' to your package is to copy -all the `libltdl' source files to a subdirectory within your package -and to build and link them along with the rest of your sources. To -help you do this, the m4 macros for Autoconf are available in -`ltdl.m4'. You must ensure that they are available in `aclocal.m4' -before you run Autoconf(1). Having made the macros available, you must -add a call to the `LTDL_INIT' macro (after the call to `LT_INIT') to -your package's `configure.ac' to perform the configure time checks -required to build the library correctly. Unfortunately, this method -has problems if you then try to link the package binaries with an -installed libltdl, or a library that depends on libltdl, because of the -duplicate symbol definitions. For example, ultimately linking against -two different versions of libltdl, or against both a local convenience -library and an installed libltdl is bad. Ensuring that only one copy -of the libltdl sources are linked into any program is left as an -exercise for the reader. - - -- Macro: LT_CONFIG_LTDL_DIR (DIRECTORY) - Declare DIRECTORY to be the location of the `libltdl' source - files, for `libtoolize --ltdl' to place them. *Note Invoking - libtoolize::, for more details. Provided that you add an - appropriate `LT_CONFIG_LTDL_DIR' call in your `configure.ac' - before calling `libtoolize', the appropriate `libltdl' files will - be installed automatically. - - -- Macro: LTDL_INIT (OPTIONS) - -- Macro: LT_WITH_LTDL - -- Macro: AC_WITH_LTDL - `AC_WITH_LTDL' and `LT_WITH_LTDL' are deprecated names for older - versions of this macro; `autoupdate' will update your - `configure.ac' file. - - This macro adds the following options to the `configure' script: - - `--with-ltdl-include INSTALLED-LTDL-HEADER-DIR' - The `LTDL_INIT' macro will look in the standard header file - locations to find the installed `libltdl' headers. If - `LTDL_INIT' can't find them by itself, the person who builds - your package can use this option to tell `configure' where - the installed `libltdl' headers are. - - `--with-ltdl-lib INSTALLED-LTDL-LIBRARY-DIR' - Similarly, the person building your package can use this - option to help `configure' find the installed `libltdl.la'. - - `--with-included-ltdl' - If there is no installed `libltdl', or in any case if the - person building your package would rather use the `libltdl' - sources shipped with the package in the subdirectory named by - `LT_CONFIG_LTDL_DIR', they should pass this option to - `configure'. - - If the `--with-included-ltdl' is not passed at configure time, and - an installed `libltdl' is not found(2), then `configure' will exit - immediately with an error that asks the user to either specify the - location of an installed `libltdl' using the `--with-ltdl-include' - and `--with-ltdl-lib' options, or to build with the `libltdl' - sources shipped with the package by passing `--with-included-ltdl'. - - If an installed `libltdl' is found, then `LIBLTDL' is set to the - link flags needed to use it, and `LTDLINCL' to the preprocessor - flags needed to find the installed headers, and `LTDLDEPS' will be - empty. Note, however, that no version checking is performed. You - should manually check for the `libltdl' features you need in - `configure.ac': - - LT_INIT([dlopen]) - LTDL_INIT - - # The lt_dladvise_init symbol was added with libtool-2.2 - if test "x$with_included_ltdl" != "xyes"; then - save_CFLAGS="$CFLAGS" - save_LDFLAGS="$LDFLAGS" - CFLAGS="$CFLAGS $LTDLINCL" - LDFLAGS="$LDFLAGS $LIBLTDL" - AC_CHECK_LIB([ltdl], [lt_dladvise_init], - [], - [AC_MSG_ERROR([installed libltdl is too old])]) - LDFLAGS="$save_LDFLAGS" - CFLAGS="$save_CFLAGS" - fi - - OPTIONS may include no more than one of the following build modes - depending on how you want your project to build `libltdl': - `nonrecursive', `recursive', or `subproject'. In order for - `libtoolize' to detect this option correctly, if you supply one of - these arguments, they must be given literally (i.e., macros or - shell variables that expand to the correct ltdl mode will not - work). - - `nonrecursive' - This is how the Libtool project distribution builds the - `libltdl' we ship and install. If you wish to use Automake - to build `libltdl' without invoking a recursive make to - descend into the `libltdl' subdirectory, then use this - option. You will need to set your configuration up carefully - to make this work properly, and you will need releases of - Autoconf and Automake that support `subdir-objects' and - `LIBOBJDIR' properly. In your `configure.ac', add: - - AM_INIT_AUTOMAKE([subdir-objects]) - AC_CONFIG_HEADERS([config.h]) - LT_CONFIG_LTDL_DIR([libltdl]) - LT_INIT([dlopen]) - LTDL_INIT([nonrecursive]) - - You _have to_ use a config header, but it may have a name - different than `config.h'. - - Also, add the following near the top of your `Makefile.am': - - AM_CPPFLAGS = - AM_LDFLAGS = - - BUILT_SOURCES = - EXTRA_DIST = - CLEANFILES = - MOSTLYCLEANFILES = - - include_HEADERS = - noinst_LTLIBRARIES = - lib_LTLIBRARIES = - EXTRA_LTLIBRARIES = - - include libltdl/Makefile.inc - - Unless you build no other libraries from this `Makefile.am', - you will also need to change `lib_LTLIBRARIES' to assign with - `+=' so that the `libltdl' targets declared in `Makefile.inc' - are not overwritten. - - `recursive' - This build mode still requires that you use Automake, but (in - contrast with `nonrecursive') uses the more usual device of - starting another `make' process in the `libltdl' - subdirectory. To use this mode, you should add to your - `configure.ac': - - AM_INIT_AUTOMAKE - AC_CONFIG_HEADERS([config.h]) - LT_CONFIG_LTDL_DIR([libltdl]) - LT_INIT([dlopen]) - LTDL_INIT([recursive]) - AC_CONFIG_FILES([libltdl/Makefile]) - - Again, you _have to_ use a config header, but it may have a - name different than `config.h' if you like. - - Also, add this to your `Makefile.am': - - SUBDIRS = libltdl - - `subproject' - This mode is the default unless you explicitly add - `recursive' or `nonrecursive' to your `LTDL_INIT' options; - `subproject' is the only mode supported by previous releases - of libltdl. Even if you do not use Autoconf in the parent - project, then, in `subproject' mode, still `libltdl' contains - all the necessary files to configure and build itself - you - just need to arrange for your build system to call - `libltdl/configure' with appropriate options, and then run - `make' in the `libltdl' subdirectory. - - If you _are_ using Autoconf and Automake, then you will need - to add the following to your `configure.ac': - - LT_CONFIG_LTDL_DIR([libltdl]) - LTDL_INIT - - and to `Makefile.am': - - SUBDIRS = libltdl - - Aside from setting the libltdl build mode, there are other keywords - that you can pass to `LTDL_INIT' to modify its behavior when - `--with-included-ltdl' has been given: - - `convenience' - This is the default unless you explicitly add `installable' to - your `LTDL_INIT' options. - - This keyword will cause options to be passed to the - `configure' script in the subdirectory named by - `LT_CONFIG_LTDL_DIR' in order to cause it to be built as a - convenience library. If you're not using automake, you will - need to define `top_build_prefix', `top_builddir', and - `top_srcdir' in your makefile so that `LIBLTDL', `LTDLDEPS', - and `LTDLINCL' expand correctly. - - One advantage of the convenience library is that it is not - installed, so the fact that you use `libltdl' will not be - apparent to the user, and it won't overwrite a pre-installed - version of `libltdl' the system might already have in the - installation directory. On the other hand, if you want to - upgrade `libltdl' for any reason (e.g. a bugfix) you'll have - to recompile your package instead of just replacing the - shared installed version of `libltdl'. However, if your - programs or libraries are linked with other libraries that - use such a pre-installed version of `libltdl', you may get - linker errors or run-time crashes. Another problem is that - you cannot link the convenience library into more than one - libtool library, then link a single program with those - libraries, because you may get duplicate symbols. In general - you can safely use the convenience library in programs that - don't depend on other libraries that might use `libltdl' too. - - `installable' - This keyword will pass options to the `configure' script in - the subdirectory named by `LT_CONFIG_LTDL_DIR' in order to - cause it to be built as an installable library. If you're not - using automake, you will need to define `top_build_prefix', - `top_builddir' and `top_srcdir' in your makefile so that - `LIBLTDL', `LTDLDEPS', and `LTDLINCL' are expanded properly. - - Be aware that you could overwrite another `libltdl' already - installed to the same directory if you use this option. - - Whatever method you use, `LTDL_INIT' will define the shell variable -`LIBLTDL' to the link flag that you should use to link with `libltdl', -the shell variable `LTDLDEPS' to the files that can be used as a -dependency in `Makefile' rules, and the shell variable `LTDLINCL' to -the preprocessor flag that you should use to compile programs that -include `ltdl.h'. So, when you want to link a program with libltdl, be -it a convenience, installed or installable library, just use -`$(LTDLINCL)' for preprocessing and compilation, and `$(LIBLTDL)' for -linking. - - * If your package is built using an installed version of `libltdl', - `LIBLTDL' will be set to the compiler flags needed to link against - the installed library, `LTDLDEPS' will be empty, and `LTDLINCL' - will be set to the compiler flags needed to find the `libltdl' - header files. - - * If your package is built using the convenience libltdl, `LIBLTDL' - and `LTDLDEPS' will be the pathname for the convenience version of - libltdl (starting with `${top_builddir}/' or - `${top_build_prefix}') and `LTDLINCL' will be `-I' followed by the - directory that contains `ltdl.h' (starting with `${top_srcdir}/'). - - * If an installable version of the included `libltdl' is being - built, its pathname starting with `${top_builddir}/' or - `${top_build_prefix}', will be stored in `LIBLTDL' and `LTDLDEPS', - and `LTDLINCL' will be set just like in the case of convenience - library. - - You should probably also use the `dlopen' option to `LT_INIT' in -your `configure.ac', otherwise libtool will assume no dlopening -mechanism is supported, and revert to dlpreopening, which is probably -not what you want. Avoid using the `-static', `-static-libtool-libs', -or `-all-static' switches when linking programs with libltdl. This -will not work on all platforms, because the dlopening functions may not -be available for static linking. - - The following example shows you how to embed an installable libltdl -in your package. In order to use the convenience variant, just replace -the `LTDL_INIT' option `installable' with `convenience'. We assume -that libltdl was embedded using `libtoolize --ltdl'. - - configure.ac: - ... - # Name the subdirectory that contains libltdl sources - LT_CONFIG_LTDL_DIR([libltdl]) - - # Configure libtool with dlopen support if possible - LT_INIT([dlopen]) - - # Enable building of the installable libltdl library - LTDL_INIT([installable]) - ... - - Makefile.am: - ... - SUBDIRS = libltdl - - AM_CPPFLAGS = $(LTDLINCL) - - myprog_LDFLAGS = -export-dynamic - myprog_LDADD = $(LIBLTDL) -dlopen self -dlopen foo1.la - myprog_DEPENDENCIES = $(LTDLDEPS) foo1.la - ... - - -- Macro: LTDL_INSTALLABLE - -- Macro: AC_LIBLTDL_INSTALLABLE - These macros are deprecated, the `installable' option to - `LTDL_INIT' should be used instead. - - -- Macro: LTDL_CONVENIENCE - -- Macro: AC_LIBLTDL_CONVENIENCE - These macros are deprecated, the `convenience' option to - `LTDL_INIT' should be used instead. - - ---------- Footnotes ---------- - - (1) We used to recommend adding the contents of `ltdl.m4' to -`acinclude.m4', but with `aclocal' from a modern Automake (1.8 or -newer) and this release of libltdl that is not only unnecessary but -makes it easy to forget to upgrade `acinclude.m4' if you move to a -different release of libltdl. - - (2) Even if libltdl is installed, `LTDL_INIT' may fail to detect it -if libltdl depends on symbols provided by libraries other than the C -library. - - -File: libtool.info, Node: Trace interface, Next: FAQ, Prev: Using libltdl, Up: Top - -12 Libtool's trace interface -**************************** - -This section describes macros whose sole purpose is to be traced using -Autoconf's `--trace' option (*note The Autoconf Manual: -(autoconf)autoconf Invocation.) to query the Libtool configuration of a -project. These macros are called by Libtool internals and should never -be called by user code; they should only be traced. - - -- Macro: LT_SUPPORTED_TAG (TAG) - This macro is called once for each language enabled in the - package. Its only argument, TAG, is the tag-name corresponding to - the language (*note Tags::). - - You can therefore retrieve the list of all tags enabled in a - project using the following command: - autoconf --trace 'LT_SUPPORTED_TAG:$1' - - -File: libtool.info, Node: FAQ, Next: Troubleshooting, Prev: Trace interface, Up: Top - -13 Frequently Asked Questions about libtool -******************************************* - -This chapter covers some questions that often come up on the mailing -lists. - -* Menu: - -* Stripped link flags:: Dropped flags when creating a library - - -File: libtool.info, Node: Stripped link flags, Up: FAQ - -13.1 Why does libtool strip link flags when creating a library? -=============================================================== - -When creating a shared library, but not when compiling or creating a -program, `libtool' drops some flags from the command line provided by -the user. This is done because flags unknown to `libtool' may -interfere with library creation or require additional support from -`libtool', and because omitting flags is usually the conservative -choice for a successful build. - - If you encounter flags that you think are useful to pass, as a -work-around you can prepend flags with `-Wc,' or `-Xcompiler ' to allow -them to be passed through to the compiler driver (*note Link mode::). -Another possibility is to add flags already to the compiler command at -`configure' run time: - - ./configure CC='gcc -m64' - - If you think `libtool' should let some flag through by default, -here's how you can test such an inclusion: grab the Libtool development -tree, edit the `ltmain.m4sh' file in the `libltdl/config' subdirectory -to pass through the flag (search for `Flags to be passed through'), -re-bootstrap and build with the flags in question added to `LDFLAGS', -`CFLAGS', `CXXFLAGS', etc. on the `configure' command line as -appropriate. Run the testsuite as described in the `README' file and -report results to the Libtool bug reporting address -<bug-libtool@gnu.org>. - - -File: libtool.info, Node: Troubleshooting, Next: Maintaining, Prev: FAQ, Up: Top - -14 Troubleshooting -****************** - -Libtool is under constant development, changing to remain up-to-date -with modern operating systems. If libtool doesn't work the way you -think it should on your platform, you should read this chapter to help -determine what the problem is, and how to resolve it. - -* Menu: - -* Libtool test suite:: Libtool's self-tests. -* Reporting bugs:: How to report problems with libtool. - - -File: libtool.info, Node: Libtool test suite, Next: Reporting bugs, Up: Troubleshooting - -14.1 The libtool test suite -=========================== - -Libtool comes with two integrated sets of tests to check that your build -is sane, that test its capabilities, and report obvious bugs in the -libtool program. These tests, too, are constantly evolving, based on -past problems with libtool, and known deficiencies in other operating -systems. - - As described in the `README' file, you may run `make -k check' after -you have built libtool (possibly before you install it) in order to -make sure that it meets basic functional requirements. - -* Menu: - -* Test descriptions:: The contents of the old test suite. -* When tests fail:: What to do when a test fails. - - -File: libtool.info, Node: Test descriptions, Next: When tests fail, Up: Libtool test suite - -14.1.1 Description of test suite --------------------------------- - -Here is a list of the current programs in the old test suite, and what -they test for: - -`cdemo-conf.test' -`cdemo-make.test' -`cdemo-exec.test' -`cdemo-static.test' -`cdemo-static-make.test' -`cdemo-static-exec.test' -`cdemo-shared.test' -`cdemo-shared-make.test' -`cdemo-shared-exec.test' -`cdemo-undef.test' -`cdemo-undef-make.test' -`cdemo-undef-exec.test' - These programs check to see that the `tests/cdemo' subdirectory of - the libtool distribution can be configured and built correctly. - - The `tests/cdemo' subdirectory contains a demonstration of libtool - convenience libraries, a mechanism that allows build-time static - libraries to be created, in a way that their components can be - later linked into programs or other libraries, even shared ones. - - The tests matching `cdemo-*make.test' and `cdemo-*exec.test' are - executed three times, under three different libtool configurations: - `cdemo-conf.test' configures `cdemo/libtool' to build both static - and shared libraries (the default for platforms that support - both), `cdemo-static.test' builds only static libraries - (`--disable-shared'), and `cdemo-shared.test' builds only shared - libraries (`--disable-static'). - - The test `cdemo-undef.test' tests the generation of shared - libraries with undefined symbols on systems that allow this. - -`demo-conf.test' -`demo-make.test' -`demo-exec.test' -`demo-inst.test' -`demo-unst.test' -`demo-static.test' -`demo-static-make.test' -`demo-static-exec.test' -`demo-static-inst.test' -`demo-static-unst.test' -`demo-shared.test' -`demo-shared-make.test' -`demo-shared-exec.test' -`demo-shared-inst.test' -`demo-shared-unst.test' -`demo-nofast.test' -`demo-nofast-make.test' -`demo-nofast-exec.test' -`demo-nofast-inst.test' -`demo-nofast-unst.test' -`demo-pic.test' -`demo-pic-make.test' -`demo-pic-exec.test' -`demo-nopic.test' -`demo-nopic-make.test' -`demo-nopic-exec.test' - These programs check to see that the `tests/demo' subdirectory of - the libtool distribution can be configured, built, installed, and - uninstalled correctly. - - The `tests/demo' subdirectory contains a demonstration of a trivial - package that uses libtool. The tests matching `demo-*make.test', - `demo-*exec.test', `demo-*inst.test' and `demo-*unst.test' are - executed four times, under four different libtool configurations: - `demo-conf.test' configures `demo/libtool' to build both static - and shared libraries, `demo-static.test' builds only static - libraries (`--disable-shared'), and `demo-shared.test' builds only - shared libraries (`--disable-static'). `demo-nofast.test' - configures `demo/libtool' to disable the fast-install mode - (`--enable-fast-install=no'). `demo-pic.test' configures - `demo/libtool' to prefer building PIC code (`--with-pic'), - `demo-nopic.test' to prefer non-PIC code (`--without-pic'). - -`demo-deplibs.test' - Many systems cannot link static libraries into shared libraries. - libtool uses a `deplibs_check_method' to prevent such cases. This - tests checks whether libtool's `deplibs_check_method' works - properly. - -`demo-hardcode.test' - On all systems with shared libraries, the location of the library - can be encoded in executables that are linked against it *note - Linking executables::. This test checks the conditions under - which your system linker hardcodes the library location, and - guarantees that they correspond to libtool's own notion of how - your linker behaves. - -`demo-relink.test' -`depdemo-relink.test' - These tests check whether variable `shlibpath_overrides_runpath' is - properly set. If the test fails, it will indicate what the - variable should have been set to. - -`demo-noinst-link.test' - Checks whether libtool will not try to link with a previously - installed version of a library when it should be linking with a - just-built one. - -`depdemo-conf.test' -`depdemo-make.test' -`depdemo-exec.test' -`depdemo-inst.test' -`depdemo-unst.test' -`depdemo-static.test' -`depdemo-static-make.test' -`depdemo-static-exec.test' -`depdemo-static-inst.test' -`depdemo-static-unst.test' -`depdemo-shared.test' -`depdemo-shared-make.test' -`depdemo-shared-exec.test' -`depdemo-shared-inst.test' -`depdemo-shared-unst.test' -`depdemo-nofast.test' -`depdemo-nofast-make.test' -`depdemo-nofast-exec.test' -`depdemo-nofast-inst.test' -`depdemo-nofast-unst.test' - These programs check to see that the `tests/depdemo' subdirectory - of the libtool distribution can be configured, built, installed, - and uninstalled correctly. - - The `tests/depdemo' subdirectory contains a demonstration of - inter-library dependencies with libtool. The test programs link - some interdependent libraries. - - The tests matching `depdemo-*make.test', `depdemo-*exec.test', - `depdemo-*inst.test' and `depdemo-*unst.test' are executed four - times, under four different libtool configurations: - `depdemo-conf.test' configures `depdemo/libtool' to build both - static and shared libraries, `depdemo-static.test' builds only - static libraries (`--disable-shared'), and `depdemo-shared.test' - builds only shared libraries (`--disable-static'). - `depdemo-nofast.test' configures `depdemo/libtool' to disable the - fast-install mode (`--enable-fast-install=no'). - -`mdemo-conf.test' -`mdemo-make.test' -`mdemo-exec.test' -`mdemo-inst.test' -`mdemo-unst.test' -`mdemo-static.test' -`mdemo-static-make.test' -`mdemo-static-exec.test' -`mdemo-static-inst.test' -`mdemo-static-unst.test' -`mdemo-shared.test' -`mdemo-shared-make.test' -`mdemo-shared-exec.test' -`mdemo-shared-inst.test' -`mdemo-shared-unst.test' - These programs check to see that the `tests/mdemo' subdirectory of - the libtool distribution can be configured, built, installed, and - uninstalled correctly. - - The `tests/mdemo' subdirectory contains a demonstration of a - package that uses libtool and the system independent dlopen wrapper - `libltdl' to load modules. The library `libltdl' provides a - dlopen wrapper for various platforms (POSIX) including support for - dlpreopened modules (*note Dlpreopening::). - - The tests matching `mdemo-*make.test', `mdemo-*exec.test', - `mdemo-*inst.test' and `mdemo-*unst.test' are executed three - times, under three different libtool configurations: - `mdemo-conf.test' configures `mdemo/libtool' to build both static - and shared libraries, `mdemo-static.test' builds only static - libraries (`--disable-shared'), and `mdemo-shared.test' builds - only shared libraries (`--disable-static'). - -`mdemo-dryrun.test' - This test checks whether libtool's `--dry-run' mode works properly. - -`mdemo2-conf.test' -`mdemo2-exec.test' -`mdemo2-make.test' - These programs check to see that the `tests/mdemo2' subdirectory of - the libtool distribution can be configured, built, and executed - correctly. - - The `tests/mdemo2' directory contains a demonstration of a package - that attempts to link with a library (from the `tests/mdemo' - directory) that itself does dlopening of libtool modules. - -`link.test' - This test guarantees that linking directly against a non-libtool - static library works properly. - -`link-2.test' - This test makes sure that files ending in `.lo' are never linked - directly into a program file. - -`nomode.test' - Check whether we can actually get help for libtool. - -`objectlist.test' - Check that a nonexistent objectlist file is properly detected. - -`pdemo-conf.test' -`pdemo-make.test' -`pdemo-exec.test' -`pdemo-inst.test' - These programs check to see that the `tests/pdemo' subdirectory of - the libtool distribution can be configured, built, and executed - correctly. - - The `pdemo-conf.test' lowers the `max_cmd_len' variable in the - generated libtool script to test the measures to evade command line - length limitations. - -`quote.test' - This program checks libtool's metacharacter quoting. - -`sh.test' - Checks for some nonportable or dubious or undesired shell - constructs in shell scripts. - -`suffix.test' - When other programming languages are used with libtool (*note - Other languages::), the source files may end in suffixes other - than `.c'. This test validates that libtool can handle suffixes - for all the file types that it supports, and that it fails when - the suffix is invalid. - -`tagdemo-conf.test' -`tagdemo-make.test' -`tagdemo-exec.test' -`tagdemo-static.test' -`tagdemo-static-make.test' -`tagdemo-static-exec.test' -`tagdemo-shared.test' -`tagdemo-shared-make.test' -`tagdemo-shared-exec.test' -`tagdemo-undef.test' -`tagdemo-undef-make.test' -`tagdemo-undef-exec.test' - These programs check to see that the `tests/tagdemo' subdirectory - of the libtool distribution can be configured, built, and executed - correctly. - - The `tests/tagdemo' directory contains a demonstration of a package - that uses libtool's multi-language support through configuration - tags. It generates a library from C++ sources, which is then - linked to a C++ program. - -`f77demo-conf.test' -`f77demo-make.test' -`f77demo-exec.test' -`f77demo-static.test' -`f77demo-static-make.test' -`f77demo-static-exec.test' -`f77demo-shared.test' -`f77demo-shared-make.test' -`f77demo-shared-exec.test' - These programs check to see that the `tests/f77demo' subdirectory - of the libtool distribution can be configured, built, and executed - correctly. - - The `tests/f77demo' tests test Fortran 77 support in libtool by - creating libraries from Fortran 77 sources, and mixed Fortran and C - sources, and a Fortran 77 program to use the former library, and a - C program to use the latter library. - -`fcdemo-conf.test' -`fcdemo-make.test' -`fcdemo-exec.test' -`fcdemo-static.test' -`fcdemo-static-make.test' -`fcdemo-static-exec.test' -`fcdemo-shared.test' -`fcdemo-shared-make.test' -`fcdemo-shared-exec.test' - These programs check to see that the `tests/fcdemo' subdirectory - of the libtool distribution can be configured, built, and executed - correctly. - - The `tests/fcdemo' is similar to the `tests/f77demo' directory, - except that Fortran 90 is used in combination with the `FC' - interface provided by Autoconf and Automake. - - - The new, Autotest-based test suite uses keywords to classify certain -test groups: - -`CXX' -`F77' -`FC' -`GCJ' - The test group exercises one of these `libtool' language tags. - -`autoconf' -`automake' - These keywords denote that the respective external program is - needed by the test group. The tests are typically skipped if the - program is not installed. The `automake' keyword may also denote - use of the `aclocal' program. - -`interactive' - This test group may require user interaction on some systems. - Typically, this means closing a popup window about a DLL load - error on Windows. - -`libltdl' - Denote that the `libltdl' library is exercised by the test group. - -`libtool' -`libtoolize' - Denote that the `libtool' or `libtoolize' scripts are exercised by - the test group, respectively. - -`recursive' - Denote that this test group may recursively re-invoke the test - suite itself, with changed settings and maybe a changed `libtool' - script. You may use the `INNER_TESTSUITEFLAGS' variable to pass - additional settings to this recursive invocation. Typically, - recursive invocations delimit the set of tests with another - keyword, for example by passing `-k libtool' right before the - expansion of the `INNER_TESTSUITEFLAGS' variable (without an - intervening space, so you get the chance for further delimitation). - - Test groups with the keyword `recursive' should not be denoted with - keywords, in order to avoid infinite recursion. As a consequence, - recursive test groups themselves should never require user - interaction, while the test groups they invoke may do so. - - There is a convenience target `check-noninteractive' that runs all -tests from both test suites that do not cause user interaction on -Windows. Conversely, the target `check-interactive' runs the -complement of tests and might require closing popup windows about DLL -load errors on Windows. - - -File: libtool.info, Node: When tests fail, Prev: Test descriptions, Up: Libtool test suite - -14.1.2 When tests fail ----------------------- - -When the tests in the old test suite are run via `make check', output -is caught in per-test `tests/TEST-NAME.log' files and summarized in the -`test-suite.log' file. The exit status of each program tells the -`Makefile' whether or not the test succeeded. - - If a test fails, it means that there is either a programming error in -libtool, or in the test program itself. - - To investigate a particular test, you may run it directly, as you -would a normal program. When the test is invoked in this way, it -produces output that may be useful in determining what the problem is. - - The new, Autotest-based test suite produces as output a file -`tests/testsuite.log' which contains information about failed tests. - - You can pass options to the test suite through the `make' variable -`TESTSUITEFLAGS' (*note The Autoconf Manual: (autoconf)testsuite -Invocation.). - - -File: libtool.info, Node: Reporting bugs, Prev: Libtool test suite, Up: Troubleshooting - -14.2 Reporting bugs -=================== - -If you think you have discovered a bug in libtool, you should think -twice: the libtool maintainer is notorious for passing the buck (or -maybe that should be "passing the bug"). Libtool was invented to fix -known deficiencies in shared library implementations, so, in a way, most -of the bugs in libtool are actually bugs in other operating systems. -However, the libtool maintainer would definitely be happy to add support -for somebody else's buggy operating system. [I wish there was a good -way to do winking smiley-faces in Texinfo.] - - Genuine bugs in libtool include problems with shell script -portability, documentation errors, and failures in the test suite -(*note Libtool test suite::). - - First, check the documentation and help screens to make sure that the -behaviour you think is a problem is not already mentioned as a feature. - - Then, you should read the Emacs guide to reporting bugs (*note -Reporting Bugs: (emacs)Bugs.). Some of the details listed there are -specific to Emacs, but the principle behind them is a general one. - - Finally, send a bug report to the Libtool bug reporting address -<bug-libtool@gnu.org> with any appropriate _facts_, such as test suite -output (*note When tests fail::), all the details needed to reproduce -the bug, and a brief description of why you think the behaviour is a -bug. Be sure to include the word "libtool" in the subject line, as -well as the version number you are using (which can be found by typing -`libtool --version'). - - -File: libtool.info, Node: Maintaining, Next: GNU Free Documentation License, Prev: Troubleshooting, Up: Top - -15 Maintenance notes for libtool -******************************** - -This chapter contains information that the libtool maintainer finds -important. It will be of no use to you unless you are considering -porting libtool to new systems, or writing your own libtool. - -* Menu: - -* New ports:: How to port libtool to new systems. -* Tested platforms:: When libtool was last tested. -* Platform quirks:: Information about different library systems. -* libtool script contents:: Configuration information that libtool uses. -* Cheap tricks:: Making libtool maintainership easier. - - -File: libtool.info, Node: New ports, Next: Tested platforms, Up: Maintaining - -15.1 Porting libtool to new systems -=================================== - -Before you embark on porting libtool to an unsupported system, it is -worthwhile to send e-mail to the Libtool mailing list -<libtool@gnu.org>, to make sure that you are not duplicating existing -work. - - If you find that any porting documentation is missing, please -complain! Complaints with patches and improvements to the -documentation, or to libtool itself, are more than welcome. - -* Menu: - -* Information sources:: Where to find relevant documentation -* Porting inter-library dependencies:: Implementation details explained - - -File: libtool.info, Node: Information sources, Next: Porting inter-library dependencies, Up: New ports - -15.1.1 Information sources --------------------------- - -Once it is clear that a new port is necessary, you'll generally need the -following information: - -canonical system name - You need the output of `config.guess' for this system, so that you - can make changes to the libtool configuration process without - affecting other systems. - -man pages for `ld' and `cc' - These generally describe what flags are used to generate PIC, to - create shared libraries, and to link against only static - libraries. You may need to follow some cross references to find - the information that is required. - -man pages for `ld.so', `rtld', or equivalent - These are a valuable resource for understanding how shared - libraries are loaded on the system. - -man page for `ldconfig', or equivalent - This page usually describes how to install shared libraries. - -output from `ls -l /lib /usr/lib' - This shows the naming convention for shared libraries on the - system, including which names should be symbolic links. - -any additional documentation - Some systems have special documentation on how to build and install - shared libraries. - - If you know how to program the Bourne shell, then you can complete -the port yourself; otherwise, you'll have to find somebody with the -relevant skills who will do the work. People on the libtool mailing -list are usually willing to volunteer to help you with new ports, so -you can send the information to them. - - To do the port yourself, you'll definitely need to modify the -`libtool.m4' macros in order to make platform-specific changes to the -configuration process. You should search that file for the `PORTME' -keyword, which will give you some hints on what you'll need to change. -In general, all that is involved is modifying the appropriate -configuration variables (*note libtool script contents::). - - Your best bet is to find an already-supported system that is similar -to yours, and make your changes based on that. In some cases, however, -your system will differ significantly from every other supported system, -and it may be necessary to add new configuration variables, and modify -the `ltmain.in' script accordingly. Be sure to write to the mailing -list before you make changes to `ltmain.in', since they may have advice -on the most effective way of accomplishing what you want. - - -File: libtool.info, Node: Porting inter-library dependencies, Prev: Information sources, Up: New ports - -15.1.2 Porting inter-library dependencies support -------------------------------------------------- - -Since version 1.2c, libtool has re-introduced the ability to do -inter-library dependency on some platforms, thanks to a patch by Toshio -Kuratomi <badger@prtr-13.ucsc.edu>. Here's a shortened version of the -message that contained his patch: - - The basic architecture is this: in `libtool.m4', the person who -writes libtool makes sure `$deplibs' is included in `$archive_cmds' -somewhere and also sets the variable `$deplibs_check_method', and maybe -`$file_magic_cmd' when `deplibs_check_method' is file_magic. - - `deplibs_check_method' can be one of five things: -`file_magic [REGEX]' - looks in the library link path for libraries that have the right - libname. Then it runs `$file_magic_cmd' on the library and checks - for a match against the extended regular expression REGEX. When - `file_magic_test_file' is set by `libtool.m4', it is used as an - argument to `$file_magic_cmd' in order to verify whether the - regular expression matches its output, and warn the user otherwise. - -`test_compile' - just checks whether it is possible to link a program out of a list - of libraries, and checks which of those are listed in the output of - `ldd'. It is currently unused, and will probably be dropped in the - future. - -`pass_all' - will pass everything without any checking. This may work on - platforms in which code is position-independent by default and - inter-library dependencies are properly supported by the dynamic - linker, for example, on DEC OSF/1 3 and 4. - -`none' - It causes deplibs to be reassigned `deplibs=""'. That way - `archive_cmds' can contain deplibs on all platforms, but not have - deplibs used unless needed. - -`unknown' - is the default for all systems unless overridden in `libtool.m4'. - It is the same as `none', but it documents that we really don't - know what the correct value should be, and we welcome patches that - improve it. - - Then in `ltmain.in' we have the real workhorse: a little -initialization and postprocessing (to setup/release variables for use -with eval echo libname_spec etc.) and a case statement that decides the -method that is being used. This is the real code... I wish I could -condense it a little more, but I don't think I can without function -calls. I've mostly optimized it (moved things out of loops, etc.) but -there is probably some fat left. I thought I should stop while I was -ahead, work on whatever bugs you discover, etc. before thinking about -more than obvious optimizations. - - -File: libtool.info, Node: Tested platforms, Next: Platform quirks, Prev: New ports, Up: Maintaining - -15.2 Tested platforms -===================== - -This table describes when libtool was last known to be tested on -platforms where it claims to support shared libraries: - - ------------------------------------------------------- - canonical host name compiler libtool results - (tools versions) release - ------------------------------------------------------- - alpha-dec-osf5.1 cc 1.3e ok (1.910) - alpha-dec-osf4.0f gcc 1.3e ok (1.910) - alpha-dec-osf4.0f cc 1.3e ok (1.910) - alpha-dec-osf3.2 gcc 0.8 ok - alpha-dec-osf3.2 cc 0.8 ok - alpha-dec-osf2.1 gcc 1.2f NS - alpha*-unknown-linux-gnu gcc 1.3b ok - (egcs-1.1.2, GNU ld 2.9.1.0.23) - hppa2.0w-hp-hpux11.00 cc 1.2f ok - hppa2.0-hp-hpux10.20 cc 1.3.2 ok - hppa1.1-hp-hpux10.20 gcc 1.2f ok - hppa1.1-hp-hpux10.20 cc 1.3c ok (1.821) - hppa1.1-hp-hpux10.10 gcc 1.2f ok - hppa1.1-hp-hpux10.10 cc 1.2f ok - hppa1.1-hp-hpux9.07 gcc 1.2f ok - hppa1.1-hp-hpux9.07 cc 1.2f ok - hppa1.1-hp-hpux9.05 gcc 1.2f ok - hppa1.1-hp-hpux9.05 cc 1.2f ok - hppa1.1-hp-hpux9.01 gcc 1.2f ok - hppa1.1-hp-hpux9.01 cc 1.2f ok - i*86-*-beos gcc 1.2f ok - i*86-*-bsdi4.0.1 gcc 1.3c ok - (gcc-2.7.2.1) - i*86-*-bsdi4.0 gcc 1.2f ok - i*86-*-bsdi3.1 gcc 1.2e NS - i*86-*-bsdi3.0 gcc 1.2e NS - i*86-*-bsdi2.1 gcc 1.2e NS - i*86-pc-cygwin gcc 1.3b NS - (egcs-1.1 stock b20.1 compiler) - i*86-*-dguxR4.20MU01 gcc 1.2 ok - i*86-*-freebsd4.3 gcc 1.3e ok (1.912) - i*86-*-freebsdelf4.0 gcc 1.3c ok - (egcs-1.1.2) - i*86-*-freebsdelf3.2 gcc 1.3c ok - (gcc-2.7.2.1) - i*86-*-freebsdelf3.1 gcc 1.3c ok - (gcc-2.7.2.1) - i*86-*-freebsdelf3.0 gcc 1.3c ok - i*86-*-freebsd3.0 gcc 1.2e ok - i*86-*-freebsd2.2.8 gcc 1.3c ok - (gcc-2.7.2.1) - i*86-*-freebsd2.2.6 gcc 1.3b ok - (egcs-1.1 & gcc-2.7.2.1, native ld) - i*86-*-freebsd2.1.5 gcc 0.5 ok - i*86-*-netbsd1.5 gcc 1.3e ok (1.901) - (egcs-1.1.2) - i*86-*-netbsd1.4 gcc 1.3c ok - (egcs-1.1.1) - i*86-*-netbsd1.4.3A gcc 1.3e ok (1.901) - i*86-*-netbsd1.3.3 gcc 1.3c ok - (gcc-2.7.2.2+myc2) - i*86-*-netbsd1.3.2 gcc 1.2e ok - i*86-*-netbsd1.3I gcc 1.2e ok - (egcs 1.1?) - i*86-*-netbsd1.2 gcc 0.9g ok - i*86-*-linux-gnu gcc 1.3e ok (1.901) - (Red Hat 7.0, gcc "2.96") - i*86-*-linux-gnu gcc 1.3e ok (1.911) - (SuSE 7.0, gcc 2.95.2) - i*86-*-linux-gnulibc1 gcc 1.2f ok - i*86-*-openbsd2.5 gcc 1.3c ok - (gcc-2.8.1) - i*86-*-openbsd2.4 gcc 1.3c ok - (gcc-2.8.1) - i*86-*-solaris2.7 gcc 1.3b ok - (egcs-1.1.2, native ld) - i*86-*-solaris2.6 gcc 1.2f ok - i*86-*-solaris2.5.1 gcc 1.2f ok - i*86-ncr-sysv4.3.03 gcc 1.2f ok - i*86-ncr-sysv4.3.03 cc 1.2e ok - (cc -Hnocopyr) - i*86-pc-sco3.2v5.0.5 cc 1.3c ok - i*86-pc-sco3.2v5.0.5 gcc 1.3c ok - (gcc 95q4c) - i*86-pc-sco3.2v5.0.5 gcc 1.3c ok - (egcs-1.1.2) - i*86-sco-sysv5uw7.1.1 gcc 1.3e ok (1.901) - (gcc-2.95.2, SCO linker) - i*86-UnixWare7.1.0-sysv5 cc 1.3c ok - i*86-UnixWare7.1.0-sysv5 gcc 1.3c ok - (egcs-1.1.1) - m68k-next-nextstep3 gcc 1.2f NS - m68k-sun-sunos4.1.1 gcc 1.2f NS - (gcc-2.5.7) - m88k-dg-dguxR4.12TMU01 gcc 1.2 ok - m88k-motorola-sysv4 gcc 1.3 ok - (egcs-1.1.2) - mips-sgi-irix6.5 gcc 1.2f ok - (gcc-2.8.1) - mips-sgi-irix6.4 gcc 1.2f ok - mips-sgi-irix6.3 gcc 1.3b ok - (egcs-1.1.2, native ld) - mips-sgi-irix6.3 cc 1.3b ok - (cc 7.0) - mips-sgi-irix6.2 gcc 1.2f ok - mips-sgi-irix6.2 cc 0.9 ok - mips-sgi-irix5.3 gcc 1.2f ok - (egcs-1.1.1) - mips-sgi-irix5.3 gcc 1.2f NS - (gcc-2.6.3) - mips-sgi-irix5.3 cc 0.8 ok - mips-sgi-irix5.2 gcc 1.3b ok - (egcs-1.1.2, native ld) - mips-sgi-irix5.2 cc 1.3b ok - (cc 3.18) - mips-sni-sysv4 cc 1.3.5 ok - (Siemens C-compiler) - mips-sni-sysv4 gcc 1.3.5 ok - (gcc-2.7.2.3, GNU assembler 2.8.1, native ld) - mipsel-unknown-openbsd2.1 gcc 1.0 ok - powerpc-apple-darwin6.4 gcc 1.5 ok - (apple dev tools released 12/2002) - powerpc-ibm-aix4.3.1.0 gcc 1.2f ok - (egcs-1.1.1) - powerpc-ibm-aix4.2.1.0 gcc 1.2f ok - (egcs-1.1.1) - powerpc-ibm-aix4.1.5.0 gcc 1.2f ok - (egcs-1.1.1) - powerpc-ibm-aix4.1.5.0 gcc 1.2f NS - (gcc-2.8.1) - powerpc-ibm-aix4.1.4.0 gcc 1.0 ok - powerpc-ibm-aix4.1.4.0 xlc 1.0i ok - rs6000-ibm-aix4.1.5.0 gcc 1.2f ok - (gcc-2.7.2) - rs6000-ibm-aix4.1.4.0 gcc 1.2f ok - (gcc-2.7.2) - rs6000-ibm-aix3.2.5 gcc 1.0i ok - rs6000-ibm-aix3.2.5 xlc 1.0i ok - sparc-sun-solaris2.8 gcc 1.3e ok (1.913) - (gcc-2.95.3 & native ld) - sparc-sun-solaris2.7 gcc 1.3e ok (1.913) - (gcc-2.95.3 & native ld) - sparc-sun-solaris2.6 gcc 1.3e ok (1.913) - (gcc-2.95.3 & native ld) - sparc-sun-solaris2.5.1 gcc 1.3e ok (1.911) - sparc-sun-solaris2.5 gcc 1.3b ok - (egcs-1.1.2, GNU ld 2.9.1 & native ld) - sparc-sun-solaris2.5 cc 1.3b ok - (SC 3.0.1) - sparc-sun-solaris2.4 gcc 1.0a ok - sparc-sun-solaris2.4 cc 1.0a ok - sparc-sun-solaris2.3 gcc 1.2f ok - sparc-sun-sunos4.1.4 gcc 1.2f ok - sparc-sun-sunos4.1.4 cc 1.0f ok - sparc-sun-sunos4.1.3_U1 gcc 1.2f ok - sparc-sun-sunos4.1.3C gcc 1.2f ok - sparc-sun-sunos4.1.3 gcc 1.3b ok - (egcs-1.1.2, GNU ld 2.9.1 & native ld) - sparc-sun-sunos4.1.3 cc 1.3b ok - sparc-unknown-bsdi4.0 gcc 1.2c ok - sparc-unknown-linux-gnulibc1 gcc 1.2f ok - sparc-unknown-linux-gnu gcc 1.3b ok - (egcs-1.1.2, GNU ld 2.9.1.0.23) - sparc64-unknown-linux-gnu gcc 1.2f ok - - Notes: - - "ok" means "all tests passed". - - "NS" means "Not Shared", but OK for static libraries - - Note: The vendor-distributed HP-UX `sed'(1) programs are horribly -broken, and cannot handle libtool's requirements, so users may report -unusual problems. There is no workaround except to install a working -`sed' (such as GNU `sed') on these systems. - - Note: The vendor-distributed NCR MP-RAS `cc' programs emits -copyright on standard error that confuse tests on size of -`conftest.err'. The workaround is to specify `CC' when run `configure' -with `CC='cc -Hnocopyr''. - - -File: libtool.info, Node: Platform quirks, Next: libtool script contents, Prev: Tested platforms, Up: Maintaining - -15.3 Platform quirks -==================== - -This section is dedicated to the sanity of the libtool maintainers. It -describes the programs that libtool uses, how they vary from system to -system, and how to test for them. - - Because libtool is a shell script, it can be difficult to understand -just by reading it from top to bottom. This section helps show why -libtool does things a certain way. Combined with the scripts -themselves, you should have a better sense of how to improve libtool, or -write your own. - -* Menu: - -* References:: Finding more information. -* Compilers:: Creating object files from source files. -* Reloadable objects:: Binding object files together. -* Multiple dependencies:: Removing duplicate dependent libraries. -* Archivers:: Programs that create static archives. -* Cross compiling:: Issues that arise when cross compiling. -* File name conversion:: Converting file names between platforms. -* Windows DLLs:: Windows header defines. - - -File: libtool.info, Node: References, Next: Compilers, Up: Platform quirks - -15.3.1 References ------------------ - -The following is a list of valuable documentation references: - - * SGI's IRIX Manual Pages can be found at - `http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man'. - - * Sun's free service area - (`http://www.sun.com/service/online/free.html') and documentation - server (`http://docs.sun.com/'). - - * Compaq's Tru64 UNIX online documentation is at - (`http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html') - with C++ documentation at - (`http://tru64unix.compaq.com/cplus/docs/index.htm'). - - * Hewlett-Packard has online documentation at - (`http://docs.hp.com/index.html'). - - * IBM has online documentation at - (`http://www.rs6000.ibm.com/resource/aix_resource/Pubs/'). - - -File: libtool.info, Node: Compilers, Next: Reloadable objects, Prev: References, Up: Platform quirks - -15.3.2 Compilers ----------------- - -The only compiler characteristics that affect libtool are the flags -needed (if any) to generate PIC objects. In general, if a C compiler -supports certain PIC flags, then any derivative compilers support the -same flags. Until there are some noteworthy exceptions to this rule, -this section will document only C compilers. - - The following C compilers have standard command line options, -regardless of the platform: - -`gcc' - This is the GNU C compiler, which is also the system compiler for - many free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, - NetBSD, and OpenBSD, to name a few). - - The `-fpic' or `-fPIC' flags can be used to generate - position-independent code. `-fPIC' is guaranteed to generate - working code, but the code is slower on m68k, m88k, and Sparc - chips. However, using `-fpic' on those chips imposes arbitrary - size limits on the shared libraries. - - The rest of this subsection lists compilers by the operating system -that they are bundled with: - -`aix3*' -`aix4*' - Most AIX compilers have no PIC flags, since AIX (with the - exception of AIX for IA-64) runs on PowerPC and RS/6000 chips. (1) - -`hpux10*' - Use `+Z' to generate PIC. - -`osf3*' - Digital/UNIX 3.x does not have PIC flags, at least not on the - PowerPC platform. - -`solaris2*' - Use `-KPIC' to generate PIC. - -`sunos4*' - Use `-PIC' to generate PIC. - - ---------- Footnotes ---------- - - (1) All code compiled for the PowerPC and RS/6000 chips -(`powerpc-*-*', `powerpcle-*-*', and `rs6000-*-*') is -position-independent, regardless of the operating system or compiler -suite. So, "regular objects" can be used to build shared libraries on -these systems and no special PIC compiler flags are required. - - -File: libtool.info, Node: Reloadable objects, Next: Multiple dependencies, Prev: Compilers, Up: Platform quirks - -15.3.3 Reloadable objects -------------------------- - -On all known systems, a reloadable object can be created by running `ld --r -o OUTPUT.o INPUT1.o INPUT2.o'. This reloadable object may be -treated as exactly equivalent to other objects. - - -File: libtool.info, Node: Multiple dependencies, Next: Archivers, Prev: Reloadable objects, Up: Platform quirks - -15.3.4 Multiple dependencies ----------------------------- - -On most modern platforms the order in which dependent libraries are -listed has no effect on object generation. In theory, there are -platforms that require libraries that provide missing symbols to other -libraries to be listed after those libraries whose symbols they provide. - - Particularly, if a pair of static archives each resolve some of the -other's symbols, it might be necessary to list one of those archives -both before and after the other one. Libtool does not currently cope -with this situation well, since duplicate libraries are removed from -the link line by default. Libtool provides the command line option -`--preserve-dup-deps' to preserve all duplicate dependencies in cases -where it is necessary. - - -File: libtool.info, Node: Archivers, Next: Cross compiling, Prev: Multiple dependencies, Up: Platform quirks - -15.3.5 Archivers ----------------- - -On all known systems, building a static library can be accomplished by -running `ar cru libNAME.a OBJ1.o OBJ2.o ...', where the `.a' file is -the output library, and each `.o' file is an object file. - - On all known systems, if there is a program named `ranlib', then it -must be used to "bless" the created library before linking against it, -with the `ranlib libNAME.a' command. Some systems, like Irix, use the -`ar ts' command, instead. - - -File: libtool.info, Node: Cross compiling, Next: File name conversion, Prev: Archivers, Up: Platform quirks - -15.3.6 Cross compiling ----------------------- - -Most build systems support the ability to compile libraries and -applications on one platform for use on a different platform, provided -a compiler capable of generating the appropriate output is available. -In such cross compiling scenarios, the platform on which the libraries -or applications are compiled is called the "build platform", while the -platform on which the libraries or applications are intended to be used -or executed is called the "host platform". *note The GNU Build System: -(automake)GNU Build System, of which libtool is a part, supports cross -compiling via arguments passed to the configure script: `--build=...' -and `--host=...'. However, when the build platform and host platform -are very different, libtool is required to make certain accommodations -to support these scenarios. - - In most cases, because the build platform and host platform differ, -the cross-compiled libraries and executables can't be executed or -tested on the build platform where they were compiled. The testsuites -of most build systems will often skip any tests that involve executing -such foreign executables when cross-compiling. However, if the build -platform and host platform are sufficiently similar, it is often -possible to run cross-compiled applications. Libtool's own testsuite -often attempts to execute cross-compiled tests, but will mark any -failures as _skipped_ since the failure might simply be due to the -differences between the two platforms. - - In addition to cases where the host platform and build platform are -extremely similar (e.g. `i586-pc-linux-gnu' and `i686-pc-linux-gnu'), -there is another case in which cross-compiled host applications may be -executed on the build platform. This is possible when the build -platform supports an emulation or API-enhanced environment for the host -platform. One example of this situation would be if the build platform -were MinGW, and the host platform were Cygwin (or vice versa). Both of -these platforms can actually operate within a single Windows instance, -so Cygwin applications can be launched from a MinGW context, and vice -versa--provided certain care is taken. Another example would be if the -build platform were GNU/Linux on an x86 32bit processor, and the host -platform were MinGW. In this situation, the Wine -(http://www.winehq.org/) environment can be used to launch Windows -applications from the GNU/Linux operating system; again, provided -certain care is taken. - - One particular issue occurs when a Windows platform such as MinGW, -Cygwin, or MSYS is the host or build platform, while the other platform -is a Unix-style system. In these cases, there are often conflicts -between the format of the file names and paths expected within host -platform libraries and executables, and those employed on the build -platform. - - This situation is best described using a concrete example: suppose -the build platform is GNU/Linux with canonical triplet -`i686-pc-linux-gnu'. Suppose further that the host platform is MinGW -with canonical triplet `i586-pc-mingw32'. On the GNU/Linux platform -there is a cross compiler following the usual naming conventions of -such compilers, where the compiler name is prefixed by the host -canonical triplet (or suitable alias). (For more information -concerning canonical triplets and platform aliases, see *note -Specifying Target Triplets: (autoconf)Specifying Target Triplets. and -*note Canonicalizing: (autoconf)Canonicalizing.) In this case, the C -compiler is named `i586-pc-mingw32-gcc'. - - As described in *note Wrapper executables::, for the MinGW host -platform libtool uses a wrapper executable to set various environment -variables before launching the actual program executable. Like the -program executable, the wrapper executable is cross-compiled for the -host platform (that is, for MinGW). As described above, ordinarily a -host platform executable cannot be executed on the build platform, but -in this case the Wine environment could be used to launch the MinGW -application from GNU/Linux. However, the wrapper executable, as a host -platform (MinGW) application, must set the `PATH' variable so that the -true application's dependent libraries can be located--but the contents -of the `PATH' variable must be structured for MinGW. Libtool must use -the Wine file name mapping facilities to determine the correct value so -that the wrapper executable can set the `PATH' variable to point to the -correct location. - - For example, suppose we are compiling an application in `/var/tmp' on -GNU/Linux, using separate source code and build directories: - - `/var/tmp/foo-1.2.3/app/' (application source code) - `/var/tmp/foo-1.2.3/lib/' (library source code) - `/var/tmp/BUILD/app/' (application build objects here) - `/var/tmp/BUILD/lib/' (library build objects here) - - Since the library will be built in `/var/tmp/BUILD/lib', the wrapper -executable (which will be in `/var/tmp/BUILD/app') must add that -directory to `PATH' (actually, it must add the directory named OBJDIR -under `/var/tmp/BUILD/lib', but we'll ignore that detail for now). -However, Windows does not have a concept of Unix-style file or -directory names such as `/var/tmp/BUILD/lib'. Therefore, Wine provides -a mapping from Windows file names such as `C:\Program Files' to specific -Unix-style file names. Wine also provides a utility that can be used -to map Unix-style file names to Windows file names. - - In this case, the wrapper executable should actually add the value - - Z:\var\tmp\BUILD\lib - -to the `PATH'. libtool contains support for path conversions of this -type, for a certain limited set of build and host platform -combinations. In this case, libtool will invoke Wine's `winepath' -utility to ensure that the correct `PATH' value is used. For more -information, see *note File name conversion::. - - -File: libtool.info, Node: File name conversion, Next: Windows DLLs, Prev: Cross compiling, Up: Platform quirks - -15.3.7 File name conversion ---------------------------- - -In certain situations, libtool must convert file names and paths between -formats appropriate to different platforms. Usually this occurs when -cross-compiling, and affects only the ability to launch host platform -executables on the build platform using an emulation or API-enhancement -environment such as Wine. Failure to convert paths (*note File Name -Conversion Failure::) will cause a warning to be issued, but rarely -causes the build to fail--and should have no affect on the compiled -products, once installed properly on the host platform. For more -information, *note Cross compiling::. - - However, file name conversion may also occur in another scenario: -when using a Unix emulation system on Windows (such as Cygwin or MSYS), -combined with a native Windows compiler such as MinGW or MSVC. Only a -limited set of such scenarios are currently supported; in other cases -file name conversion is skipped. The lack of file name conversion -usually means that uninstalled executables can't be launched, but only -rarely causes the build to fail (*note File Name Conversion Failure::). - - libtool supports file name conversion in the following scenarios: - -build platform host platform Notes ---------------------------------------------------------------------------- -MinGW (MSYS) MinGW (Windows) *note Native MinGW File Name - Conversion:: -Cygwin MinGW (Windows) *note Cygwin/Windows File Name - Conversion:: -Unix + Wine MinGW (Windows) Requires Wine. *note Unix/Windows - File Name Conversion:: -MinGW (MSYS) Cygwin Requires `LT_CYGPATH'. *note - LT_CYGPATH::. Provided for testing - purposes only. -Unix + Wine Cygwin Requires both Wine and - `LT_CYGPATH', but does not yet work - with Cygwin 1.7.7 and Wine-1.2. - See *note Unix/Windows File Name - Conversion:: and *note LT_CYGPATH::. - -* Menu: - -* File Name Conversion Failure:: What happens when file name conversion fails -* Native MinGW File Name Conversion:: MSYS file name conversion idiosyncrasies -* Cygwin/Windows File Name Conversion:: Using `cygpath' to convert Cygwin file names -* Unix/Windows File Name Conversion:: Using Wine to convert Unix paths -* LT_CYGPATH:: Invoking `cygpath' from other environments -* Cygwin to MinGW Cross:: Other notes concerning MinGW cross - - -File: libtool.info, Node: File Name Conversion Failure, Next: Native MinGW File Name Conversion, Up: File name conversion - -15.3.7.1 File Name Conversion Failure -..................................... - -In most cases, file name conversion is not needed or attempted. -However, when libtool detects that a specific combination of build and -host platform does require file name conversion, it is possible that -the conversion may fail. In these cases, you may see a warning such as -the following: - - Could not determine the host file name corresponding to - `... a file name ...' - Continuing, but uninstalled executables may not work. - -or - - Could not determine the host path corresponding to - `... a path ...' - Continuing, but uninstalled executables may not work. - -This should not cause the build to fail. At worst, it means that the -wrapper executable will specify file names or paths appropriate for the -build platform. Since those are not appropriate for the host platform, -the uninstalled executables would not operate correctly, even when the -wrapper executable is launched via the appropriate emulation or -API-enhancement (e.g. Wine). Simply install the executables on the -host platform, and execute them there. - - -File: libtool.info, Node: Native MinGW File Name Conversion, Next: Cygwin/Windows File Name Conversion, Prev: File Name Conversion Failure, Up: File name conversion - -15.3.7.2 Native MinGW File Name Conversion -.......................................... - -MSYS is a Unix emulation environment for Windows, and is specifically -designed such that in normal usage it _pretends_ to be MinGW or native -Windows, but understands Unix-style file names and paths, and supports -standard Unix tools and shells. Thus, "native" MinGW builds are -actually an odd sort of cross-compile, from an MSYS Unix emulation -environment "pretending" to be MinGW, to actual native Windows. - - When an MSYS shell launches a native Windows executable (as opposed -to other _MSYS_ executables), it uses a system of heuristics to detect -any command-line arguments that contain file names or paths. It -automatically converts these file names from the MSYS (Unix-like) -format, to the corresponding Windows file name, before launching the -executable. However, this auto-conversion facility is only available -when using the MSYS runtime library. The wrapper executable itself is -a MinGW application (that is, it does not use the MSYS runtime -library). The wrapper executable must set `PATH' to, and call -`_spawnv' with, values that have already been converted from MSYS -format to Windows. Thus, when libtool writes the source code for the -wrapper executable, it must manually convert MSYS paths to Windows -format, so that the Windows values can be hard-coded into the wrapper -executable. - - -File: libtool.info, Node: Cygwin/Windows File Name Conversion, Next: Unix/Windows File Name Conversion, Prev: Native MinGW File Name Conversion, Up: File name conversion - -15.3.7.3 Cygwin/Windows File Name Conversion -............................................ - -Cygwin provides a Unix emulation environment for Windows. As part of -that emulation, it provides a file system mapping that presents the -Windows file system in a Unix-compatible manner. Cygwin also provides -a utility `cygpath' that can be used to convert file names and paths -between the two representations. In a correctly configured Cygwin -installation, `cygpath' is always present, and is in the `PATH'. - - Libtool uses `cygpath' to convert from Cygwin (Unix-style) file names -and paths to Windows format when the build platform is Cygwin and the -host platform is MinGW. - - When the host platform is Cygwin, but the build platform is MSYS or -some Unix system, libtool also uses `cygpath' to convert from Windows -to Cygwin format (after first converting from the build platform format -to Windows format; see *note Native MinGW File Name Conversion:: and -*note Unix/Windows File Name Conversion::). Because the build platform -is not Cygwin, `cygpath' is not (and should not be) in the `PATH'. -Therefore, in this configuration the environment variable `LT_CYGPATH' -is required. *Note LT_CYGPATH::. - - -File: libtool.info, Node: Unix/Windows File Name Conversion, Next: LT_CYGPATH, Prev: Cygwin/Windows File Name Conversion, Up: File name conversion - -15.3.7.4 Unix/Windows File Name Conversion -.......................................... - -Wine (http://www.winehq.org/) provides an interpretation environment for -some Unix platforms in which Windows applications can be executed. It -provides a mapping between the Unix file system and a virtual Windows -file system used by the Windows programs. For the file name conversion -to work, Wine must be installed and properly configured on the build -platform, and the `winepath' application must be in the build -platform's `PATH'. In addition, on 32bit GNU/Linux it is usually -helpful if the binfmt extension is enabled. - - -File: libtool.info, Node: LT_CYGPATH, Next: Cygwin to MinGW Cross, Prev: Unix/Windows File Name Conversion, Up: File name conversion - -15.3.7.5 LT_CYGPATH -................... - -For some cross-compile configurations (where the host platform is -Cygwin), the `cygpath' program is used to convert file names from the -build platform notation to the Cygwin form (technically, this -conversion is from Windows notation to Cygwin notation; the conversion -from the build platform format to Windows notation is performed via -other means). However, because the `cygpath' program is not (and -should not be) in the `PATH' on the build platform, `LT_CYGPATH' must -specify the full build platform file name (that is, the full Unix or -MSYS file name) of the `cygpath' program. - - The reason `cygpath' should not be in the build platform `PATH' is -twofold: first, `cygpath' is usually installed in the same directory as -many other Cygwin executables, such as `sed', `cp', etc. If the build -platform environment had this directory in its `PATH', then these -Cygwin versions of common Unix utilities might be used in preference to -the ones provided by the build platform itself, with deleterious -effects. Second, especially when Cygwin-1.7 or later is used, multiple -Cygwin installations can coexist within the same Windows instance. -Each installation will have separate "mount tables" specified in -`CYGROOT-N/etc/fstab'. These "mount tables" control how that instance -of Cygwin will map Windows file names and paths to Cygwin form. Each -installation's `cygpath' utility automatically deduces the appropriate -`/etc/fstab' file. Since each `CYGROOT-N/etc/fstab' mount table may -specify different mappings, it matters which `cygpath' is used. - - Note that `cygpath' is a Cygwin application; to execute this tool -from Unix requires a working and properly configured Wine installation, -as well as enabling the GNU/Linux `binfmt' extension. Furthermore, the -Cygwin `setup.exe' tool should have been used, via Wine, to properly -install Cygwin into the Wine file system (and registry). - - Unfortunately, Wine support for Cygwin is intermittent. Recent -releases of Cygwin (1.7 and above) appear to require more Windows API -support than Wine provides (as of Wine version 1.2); most Cygwin -applications fail to execute. This includes `cygpath' itself. Hence, -it is best _not_ to use the LT_CYGPATH machinery in libtool when -performing Unix to Cygwin cross-compiles. Similarly, it is best _not_ -to enable the GNU/Linux binfmt support in this configuration, because -while Wine will fail to execute the compiled Cygwin applications, it -will still exit with status zero. This tends to confuse build systems -and test suites (including libtool's own testsuite, resulting in -spurious reported failures). Wine support for the older Cygwin-1.5 -series appears satisfactory, but the Cygwin team no longer supports -Cygwin-1.5. It is hoped that Wine will eventually be improved such that -Cygwin-1.7 will again operate correctly under Wine. Until then, -libtool will report warnings as described in *note File Name Conversion -Failure:: in these scenarios. - - However, `LT_CYGPATH' is also used for the MSYS to Cygwin cross -compile scenario, and operates as expected. - - -File: libtool.info, Node: Cygwin to MinGW Cross, Prev: LT_CYGPATH, Up: File name conversion - -15.3.7.6 Cygwin to MinGW Cross -.............................. - -There are actually three different scenarios that could all -legitimately be called a "Cygwin to MinGW" cross compile. The current -(and standard) definition is when there is a compiler that produces -native Windows libraries and applications, but which itself is a Cygwin -application, just as would be expected in any other cross compile setup. - - However, historically there were two other definitions, which we -will refer to as the _fake_ one, and the _lying_ one. - - In the _fake_ Cygwin to MinGW cross compile case, you actually use a -native MinGW compiler, but you do so from within a Cygwin environment: - - export PATH="/c/MinGW/bin:${PATH}" - configure --build=i686-pc-cygwin \ - --host=mingw32 \ - NM=/c/MinGW/bin/nm.exe - - In this way, the build system "knows" that you are cross compiling, -and the file name conversion logic will be used. However, because the -tools (`mingw32-gcc', `nm', `ar') used are actually native Windows -applications, they will not understand any Cygwin (that is, Unix-like) -absolute file names passed as command line arguments (and, unlike MSYS, -Cygwin does not automatically convert such arguments). However, so -long as only relative file names are used in the build system, and -non-Windows-supported Unix idioms such as symlinks and mount points are -avoided, this scenario should work. - - If you must use absolute file names, you will have to force Libtool -to convert file names for the toolchain in this case, by doing the -following before you run configure: - - export lt_cv_to_tool_file_cmd=func_convert_file_cygwin_to_w32 - - In the _lying_ Cygwin to MinGW cross compile case, you lie to the -build system: - - export PATH="/c/MinGW/bin:${PATH}" - configure --build=i686-pc-mingw32 \ - --host=i686-pc-mingw32 \ - --disable-dependency-tracking - -and claim that the build platform is MinGW, even though you are actually -running under _Cygwin_ and not MinGW. In this case, libtool does _not_ -know that you are performing a cross compile, and thinks instead that -you are performing a native MinGW build. However, as described in -(*note Native MinGW File Name Conversion::), that scenario triggers an -"MSYS to Windows" file name conversion. This, of course, is the wrong -conversion since we are actually running under Cygwin. Also, the -toolchain is expecting Windows file names (not Cygwin) but unless told -so Libtool will feed Cygwin file names to the toolchain in this case. -To force the correct file name conversions in this situation, you -should do the following _before_ running configure: - - export lt_cv_to_host_file_cmd=func_convert_file_cygwin_to_w32 - export lt_cv_to_tool_file_cmd=func_convert_file_cygwin_to_w32 - - Note that this relies on internal implementation details of libtool, -and is subject to change. Also, `--disable-dependency-tracking' is -required, because otherwise the MinGW GCC will generate dependency -files that contain Windows file names. This, in turn, will confuse the -Cygwin `make' program, which does not accept Windows file names: - - Makefile:1: *** target pattern contains no `%'. Stop. - - There have also always been a number of other details required for -the _lying_ case to operate correctly, such as the use of so-called -"identity mounts": - - # CYGWIN-ROOT/etc/fstab - D:/foo /foo some_fs binary 0 0 - D:/bar /bar some_fs binary 0 0 - E:/grill /grill some_fs binary 0 0 - - In this way, top-level directories of each drive are available using -identical names within Cygwin. - - Note that you also need to ensure that the standard Unix directories -(like `/bin', `/lib', `/usr', `/etc') appear in the root of a drive. -This means that you must install Cygwin itself into the `C:/' root -directory (or `D:/', or `E:/', etc)--instead of the recommended -installation into `C:/cygwin/'. In addition, all file names used in -the build system must be relative, symlinks should not be used within -the source or build directory trees, and all `-M*' options to `gcc' -except `-MMD' must be avoided. - - This is quite a fragile setup, but it has been in historical use, -and so is documented here. - - -File: libtool.info, Node: Windows DLLs, Prev: File name conversion, Up: Platform quirks - -15.3.8 Windows DLLs -------------------- - -This topic describes a couple of ways to portably create Windows Dynamic -Link Libraries (DLLs). Libtool knows how to create DLLs using GNU tools -and using Microsoft tools. - - A typical library has a "hidden" implementation with an interface -described in a header file. On just about every system, the interface -could be something like this: - - Example `foo.h': - - #ifndef FOO_H - #define FOO_H - - int one (void); - int two (void); - extern int three; - - #endif /* FOO_H */ - -And the implementation could be something like this: - - Example `foo.c': - - #include "foo.h" - - int one (void) - { - return 1; - } - - int two (void) - { - return three - one (); - } - - int three = 3; - - When using contemporary GNU tools to create the Windows DLL, the -above code will work there too, thanks to its auto-import/auto-export -features. But that is not the case when using older GNU tools or -perhaps more interestingly when using proprietary tools. In those -cases the code will need additional decorations on the interface -symbols with `__declspec(dllimport)' and `__declspec(dllexport)' -depending on whether the library is built or it's consumed and how it's -built and consumed. However, it should be noted that it would have -worked also with Microsoft tools, if only the variable `three' hadn't -been there, due to the fact the Microsoft tools will automatically -import functions (but sadly not variables) and Libtool will -automatically export non-static symbols as described next. - - With Microsoft tools, Libtool digs through the object files that -make up the library, looking for non-static symbols to automatically -export. I.e., Libtool with Microsoft tools tries to mimic the -auto-export feature of contemporary GNU tools. It should be noted that -the GNU auto-export feature is turned off when an explicit -`__declspec(dllexport)' is seen. The GNU tools do this to not make -more symbols visible for projects that have already taken the trouble -to decorate symbols. There is no similar way to limit which symbols -are visible in the code when Libtool is using Microsoft tools. In -order to limit symbol visibility in that case you need to use one of -the options `-export-symbols' or `-export-symbols-regex'. - - No matching help with auto-import is provided by Libtool, which is -why variables must be decorated to import them from a DLL for -everything but contemporary GNU tools. As stated above, functions are -automatically imported by both contemporary GNU tools and Microsoft -tools, but for other proprietary tools the auto-import status of -functions is unknown. - - When the objects that form the library are built, there are generally -two copies built for each object. One copy is used when linking the DLL -and one copy is used for the static library. On Windows systems, a pair -of defines are commonly used to discriminate how the interface symbols -should be decorated. The first define is `-DDLL_EXPORT' which is -automatically provided by Libtool when `libtool' builds the copy of the -object that is destined for the DLL. The second define is -`-DLIBFOO_BUILD' (or similar) which is often added by the package -providing the library and is used when building the library, but not -when consuming the library. - - However, the matching double compile is not performed when consuming -libraries. It is therefore not possible to reliably distinguish if the -consumer is importing from a DLL or if it is going to use a static -library. - - With contemporary GNU tools, auto-import often saves the day, but see -the GNU ld documentation and its `--enable-auto-import' option for some -corner cases when it does not (*note `--enable-auto-import': -(ld)Options.). - - With Microsoft tools you typically get away with always compiling the -code such that variables are expected to be imported from a DLL and -functions are expected to be found in a static library. The tools will -then automatically import the function from a DLL if that is where they -are found. If the variables are not imported from a DLL as expected, -but are found in a static library that is otherwise pulled in by some -function, the linker will issue a warning (LNK4217) that a locally -defined symbol is imported, but it still works. In other words, this -scheme will not work to only consume variables from a library. There is -also a price connected to this liberal use of imports in that an extra -indirection is introduced when you are consuming the static version of -the library. That extra indirection is unavoidable when the DLL is -consumed, but it is not needed when consuming the static library. - - For older GNU tools and other proprietary tools there is no generic -way to make it possible to consume either of the DLL or the static -library without user intervention, the tools need to be told what is -intended. One common assumption is that if a DLL is being built -(`DLL_EXPORT' is defined) then that DLL is going to consume any -dependent libraries as DLLs. If that assumption is made everywhere, it -is possible to select how an end-user application is consuming -libraries by adding a single flag `-DDLL_EXPORT' when a DLL build is -required. This is of course an all or nothing deal, either everything -as DLLs or everything as static libraries. - - To sum up the above, the header file of the foo library needs to be -changed into something like this: - - Modified `foo.h': - - #ifndef FOO_H - #define FOO_H - - #if defined _WIN32 && !defined __GNUC__ - # ifdef LIBFOO_BUILD - # ifdef DLL_EXPORT - # define LIBFOO_SCOPE __declspec (dllexport) - # define LIBFOO_SCOPE_VAR extern __declspec (dllexport) - # endif - # elif defined _MSC_VER - # define LIBFOO_SCOPE - # define LIBFOO_SCOPE_VAR extern __declspec (dllimport) - # elif defined DLL_EXPORT - # define LIBFOO_SCOPE __declspec (dllimport) - # define LIBFOO_SCOPE_VAR extern __declspec (dllimport) - # endif - #endif - #ifndef LIBFOO_SCOPE - # define LIBFOO_SCOPE - # define LIBFOO_SCOPE_VAR extern - #endif - - LIBFOO_SCOPE int one (void); - LIBFOO_SCOPE int two (void); - LIBFOO_SCOPE_VAR int three; - - #endif /* FOO_H */ - - When the targets are limited to contemporary GNU tools and Microsoft -tools, the above can be simplified to the following: - - Simplified `foo.h': - - #ifndef FOO_H - #define FOO_H - - #if defined _WIN32 && !defined __GNUC__ && !defined LIBFOO_BUILD - # define LIBFOO_SCOPE_VAR extern __declspec (dllimport) - #else - # define LIBFOO_SCOPE_VAR extern - #endif - - int one (void); - int two (void); - LIBFOO_SCOPE_VAR int three; - - #endif /* FOO_H */ - - This last simplified version can of course only work when Libtool is -used to build the DLL, as no symbols would be exported otherwise (i.e., -when using Microsoft tools). - - It should be noted that there are various projects that attempt to -relax these requirements by various low level tricks, but they are not -discussed here. Examples are FlexDLL -(http://alain.frisch.fr/flexdll.html) and edll -(http://edll.sourceforge.net/). - - -File: libtool.info, Node: libtool script contents, Next: Cheap tricks, Prev: Platform quirks, Up: Maintaining - -15.4 `libtool' script contents -============================== - -Since version 1.4, the `libtool' script is generated by `configure' -(*note Configuring::). In earlier versions, `configure' achieved this -by calling a helper script called `ltconfig'. From libtool version 0.7 -to 1.0, this script simply set shell variables, then sourced the -libtool backend, `ltmain.sh'. `ltconfig' from libtool version 1.1 -through 1.3 inlined the contents of `ltmain.sh' into the generated -`libtool', which improved performance on many systems. The tests that -`ltconfig' used to perform are now kept in `libtool.m4' where they can -be written using Autoconf. This has the runtime performance benefits -of inlined `ltmain.sh', _and_ improves the build time a little while -considerably easing the amount of raw shell code that used to need -maintaining. - - The convention used for naming variables that hold shell commands for -delayed evaluation, is to use the suffix `_cmd' where a single line of -valid shell script is needed, and the suffix `_cmds' where multiple -lines of shell script *may* be delayed for later evaluation. By -convention, `_cmds' variables delimit the evaluation units with the `~' -character where necessary. - - Here is a listing of each of the configuration variables, and how -they are used within `ltmain.sh' (*note Configuring::): - - -- Variable: AR - The name of the system library archiver. - - -- Variable: CC - The name of the compiler used to configure libtool. This will - always contain the compiler for the current language (*note - Tags::). - - -- Variable: ECHO - An `echo' program that does not interpret backslashes as an escape - character. It may be given only one argument, so due quoting is - necessary. - - -- Variable: LD - The name of the linker that libtool should use internally for - reloadable linking and possibly shared libraries. - - -- Variable: LTCC - -- Variable: LTCFLAGS - The name of the C compiler and C compiler flags used to configure - libtool. - - -- Variable: NM - The name of a BSD- or MS-compatible program that produces listings - of global symbols. For BSD `nm', the symbols should be in one the - following formats: - - ADDRESS C GLOBAL-VARIABLE-NAME - ADDRESS D GLOBAL-VARIABLE-NAME - ADDRESS T GLOBAL-FUNCTION-NAME - - For MS `dumpbin', the symbols should be in one of the following - formats: - - COUNTER SIZE UNDEF notype External | GLOBAL-VAR - COUNTER ADDRESS SECTION notype External | GLOBAL-VAR - COUNTER ADDRESS SECTION notype () External | GLOBAL-FUNC - - The SIZE of the global variables are not zero and the SECTION of - the global functions are not "UNDEF". Symbols in "pick any" - sections ("pick any" appears in the section header) are not global - either. - - -- Variable: RANLIB - Set to the name of the `ranlib' program, if any. - - -- Variable: allow_undefined_flag - The flag that is used by `archive_cmds' in order to declare that - there will be unresolved symbols in the resulting shared library. - Empty, if no such flag is required. Set to `unsupported' if there - is no way to generate a shared library with references to symbols - that aren't defined in that library. - - -- Variable: always_export_symbols - Whether libtool should automatically generate a list of exported - symbols using `export_symbols_cmds' before linking an archive. - Set to `yes' or `no'. Default is `no'. - - -- Variable: archive_cmds - -- Variable: archive_expsym_cmds - -- Variable: old_archive_cmds - Commands used to create shared libraries, shared libraries with - `-export-symbols' and static libraries, respectively. - - -- Variable: archiver_list_spec - Specify filename containing input files for `AR'. - - -- Variable: old_archive_from_new_cmds - If the shared library depends on a static library, - `old_archive_from_new_cmds' contains the commands used to create - that static library. If this variable is not empty, - `old_archive_cmds' is not used. - - -- Variable: old_archive_from_expsyms_cmds - If a static library must be created from the export symbol list in - order to correctly link with a shared library, - `old_archive_from_expsyms_cmds' contains the commands needed to - create that static library. When these commands are executed, the - variable `soname' contains the name of the shared library in - question, and the `$objdir/$newlib' contains the path of the - static library these commands should build. After executing these - commands, libtool will proceed to link against `$objdir/$newlib' - instead of `soname'. - - -- Variable: lock_old_archive_extraction - Set to `yes' if the extraction of a static library requires locking - the library file. This is required on Darwin. - - -- Variable: build - -- Variable: build_alias - -- Variable: build_os - Set to the specified and canonical names of the system that - libtool was built on. - - -- Variable: build_libtool_libs - Whether libtool should build shared libraries on this system. Set - to `yes' or `no'. - - -- Variable: build_old_libs - Whether libtool should build static libraries on this system. Set - to `yes' or `no'. - - -- Variable: compiler_c_o - Whether the compiler supports the `-c' and `-o' options - simultaneously. Set to `yes' or `no'. - - -- Variable: compiler_needs_object - Whether the compiler has to see an object listed on the command - line in order to successfully invoke the linker. If `no', then a - set of convenience archives or a set of object file names can be - passed via linker-specific options or linker scripts. - - -- Variable: dlopen_support - Whether `dlopen' is supported on the platform. Set to `yes' or - `no'. - - -- Variable: dlopen_self - Whether it is possible to `dlopen' the executable itself. Set to - `yes' or `no'. - - -- Variable: dlopen_self_static - Whether it is possible to `dlopen' the executable itself, when it - is linked statically (`-all-static'). Set to `yes' or `no'. - - -- Variable: exclude_expsyms - List of symbols that should not be listed in the preloaded symbols. - - -- Variable: export_dynamic_flag_spec - Compiler link flag that allows a dlopened shared library to - reference symbols that are defined in the program. - - -- Variable: export_symbols_cmds - Commands to extract exported symbols from `libobjs' to the file - `export_symbols'. - - -- Variable: extract_expsyms_cmds - Commands to extract the exported symbols list from a shared - library. These commands are executed if there is no file - `$objdir/$soname-def', and should write the names of the exported - symbols to that file, for the use of - `old_archive_from_expsyms_cmds'. - - -- Variable: fast_install - Determines whether libtool will privilege the installer or the - developer. The assumption is that installers will seldom run - programs in the build tree, and the developer will seldom install. - This is only meaningful on platforms where - `shlibpath_overrides_runpath' is not `yes', so `fast_install' will - be set to `needless' in this case. If `fast_install' set to - `yes', libtool will create programs that search for installed - libraries, and, if a program is run in the build tree, a new copy - will be linked on-demand to use the yet-to-be-installed libraries. - If set to `no', libtool will create programs that use the - yet-to-be-installed libraries, and will link a new copy of the - program at install time. The default value is `yes' or - `needless', depending on platform and configuration flags, and it - can be turned from `yes' to `no' with the configure flag - `--disable-fast-install'. - - On some systems, the linker always hardcodes paths to dependent - libraries into the output. In this case, `fast_install' is never - set to `yes', and relinking at install time is triggered. This - also means that `DESTDIR' installation does not work as expected. - - -- Variable: file_magic_glob - How to find potential files when `deplibs_check_method' is - `file_magic'. `file_magic_glob' is a `sed' expression, and the - `sed' instance is fed potential file names that are transformed by - the `file_magic_glob' expression. Useful when the shell does not - support the shell option `nocaseglob', making `want_nocaseglob' - inappropriate. Normally disabled (i.e. `file_magic_glob' is - empty). - - -- Variable: finish_cmds - Commands to tell the dynamic linker how to find shared libraries - in a specific directory. - - -- Variable: finish_eval - Same as `finish_cmds', except the commands are not displayed. - - -- Variable: global_symbol_pipe - A pipeline that takes the output of `NM', and produces a listing of - raw symbols followed by their C names. For example: - - $ eval "$NM progname | $global_symbol_pipe" - D SYMBOL1 C-SYMBOL1 - T SYMBOL2 C-SYMBOL2 - C SYMBOL3 C-SYMBOL3 - ... - $ - - The first column contains the symbol type (used to tell data from - code) but its meaning is system dependent. - - -- Variable: global_symbol_to_cdecl - A pipeline that translates the output of `global_symbol_pipe' into - proper C declarations. Since some platforms, such as HP/UX, have - linkers that differentiate code from data, data symbols are - declared as data, and code symbols are declared as functions. - - -- Variable: hardcode_action - Either `immediate' or `relink', depending on whether shared - library paths can be hardcoded into executables before they are - installed, or if they need to be relinked. - - -- Variable: hardcode_direct - Set to `yes' or `no', depending on whether the linker hardcodes - directories if a library is directly specified on the command line - (such as `DIR/libNAME.a') when `hardcode_libdir_flag_spec' is - specified. - - -- Variable: hardcode_direct_absolute - Some architectures hardcode "absolute" library directories that - can not be overridden by `shlibpath_var' when `hardcode_direct' is - `yes'. In that case set `hardcode_direct_absolute' to `yes', or - otherwise `no'. - - -- Variable: hardcode_into_libs - Whether the platform supports hardcoding of run-paths into - libraries. If enabled, linking of programs will be much simpler - but libraries will need to be relinked during installation. Set - to `yes' or `no'. - - -- Variable: hardcode_libdir_flag_spec - Flag to hardcode a `libdir' variable into a binary, so that the - dynamic linker searches `libdir' for shared libraries at runtime. - If it is empty, libtool will try to use some other hardcoding - mechanism. - - -- Variable: hardcode_libdir_separator - If the compiler only accepts a single `hardcode_libdir_flag', then - this variable contains the string that should separate multiple - arguments to that flag. - - -- Variable: hardcode_minus_L - Set to `yes' or `no', depending on whether the linker hardcodes - directories specified by `-L' flags into the resulting executable - when `hardcode_libdir_flag_spec' is specified. - - -- Variable: hardcode_shlibpath_var - Set to `yes' or `no', depending on whether the linker hardcodes - directories by writing the contents of `$shlibpath_var' into the - resulting executable when `hardcode_libdir_flag_spec' is - specified. Set to `unsupported' if directories specified by - `$shlibpath_var' are searched at run time, but not at link time. - - -- Variable: host - -- Variable: host_alias - -- Variable: host_os - Set to the specified and canonical names of the system that - libtool was configured for. - - -- Variable: include_expsyms - List of symbols that must always be exported when using - `export_symbols'. - - -- Variable: inherit_rpath - Whether the linker adds runtime paths of dependency libraries to - the runtime path list, requiring libtool to relink the output when - installing. Set to `yes' or `no'. Default is `no'. - - -- Variable: install_override_mode - Permission mode override for installation of shared libraries. If - the runtime linker fails to load libraries with wrong permissions, - then it may fail to execute programs that are needed during - installation, because these need the library that has just been - installed. In this case, it is necessary to pass the mode to - `install' with `-m INSTALL_OVERRIDE_MODE'. - - -- Variable: libext - The standard old archive suffix (normally `a'). - - -- Variable: libname_spec - The format of a library name prefix. On all Unix systems, static - libraries are called `libNAME.a', but on some systems (such as - OS/2 or MS-DOS), the library is just called `NAME.a'. - - -- Variable: library_names_spec - A list of shared library names. The first is the name of the file, - the rest are symbolic links to the file. The name in the list is - the file name that the linker finds when given `-lNAME'. - - -- Variable: link_all_deplibs - Whether libtool must link a program against all its dependency - libraries. Set to `yes' or `no'. Default is `unknown', which is - a synonym for `yes'. - - -- Variable: link_static_flag - Linker flag (passed through the C compiler) used to prevent dynamic - linking. - - -- Variable: macro_version - -- Variable: macro_revision - The release and revision from which the libtool.m4 macros were - taken. This is used to ensure that macros and `ltmain.sh' - correspond to the same Libtool version. - - -- Variable: max_cmd_len - The approximate longest command line that can be passed to `$SHELL' - without being truncated, as computed by `LT_CMD_MAX_LEN'. - - -- Variable: need_lib_prefix - Whether we can `dlopen' modules without a `lib' prefix. Set to - `yes' or `no'. By default, it is `unknown', which means the same - as `yes', but documents that we are not really sure about it. - `no' means that it is possible to `dlopen' a module without the - `lib' prefix. - - -- Variable: need_version - Whether versioning is required for libraries, i.e. whether the - dynamic linker requires a version suffix for all libraries. Set - to `yes' or `no'. By default, it is `unknown', which means the - same as `yes', but documents that we are not really sure about it. - - -- Variable: need_locks - Whether files must be locked to prevent conflicts when compiling - simultaneously. Set to `yes' or `no'. - - -- Variable: nm_file_list_spec - Specify filename containing input files for `NM'. - - -- Variable: no_builtin_flag - Compiler flag to disable builtin functions that conflict with - declaring external global symbols as `char'. - - -- Variable: no_undefined_flag - The flag that is used by `archive_cmds' in order to declare that - there will be no unresolved symbols in the resulting shared - library. Empty, if no such flag is required. - - -- Variable: objdir - The name of the directory that contains temporary libtool files. - - -- Variable: objext - The standard object file suffix (normally `o'). - - -- Variable: pic_flag - Any additional compiler flags for building library object files. - - -- Variable: postinstall_cmds - -- Variable: old_postinstall_cmds - Commands run after installing a shared or static library, - respectively. - - -- Variable: postuninstall_cmds - -- Variable: old_postuninstall_cmds - Commands run after uninstalling a shared or static library, - respectively. - - -- Variable: postlink_cmds - Commands necessary for finishing linking programs. `postlink_cmds' - are executed immediately after the program is linked. Any - occurrence of the string `@OUTPUT@' in `postlink_cmds' is replaced - by the name of the created executable (i.e. not the wrapper, if a - wrapper is generated) prior to execution. Similarly, - `@TOOL_OUTPUT@' is replaced by the toolchain format of `@OUTPUT@'. - Normally disabled (i.e. `postlink_cmds' empty). - - -- Variable: reload_cmds - -- Variable: reload_flag - Commands to create a reloadable object. Set `reload_cmds' to - `false' on systems that cannot create reloadable objects. - - -- Variable: runpath_var - The environment variable that tells the linker which directories to - hardcode in the resulting executable. - - -- Variable: shlibpath_overrides_runpath - Indicates whether it is possible to override the hard-coded library - search path of a program with an environment variable. If this is - set to no, libtool may have to create two copies of a program in - the build tree, one to be installed and one to be run in the build - tree only. When each of these copies is created depends on the - value of `fast_install'. The default value is `unknown', which is - equivalent to `no'. - - -- Variable: shlibpath_var - The environment variable that tells the dynamic linker where to - find shared libraries. - - -- Variable: soname_spec - The name coded into shared libraries, if different from the real - name of the file. - - -- Variable: striplib - -- Variable: old_striplib - Command to strip a shared (`striplib') or static (`old_striplib') - library, respectively. If these variables are empty, the strip - flag in the install mode will be ignored for libraries (*note - Install mode::). - - -- Variable: sys_lib_dlsearch_path_spec - Expression to get the run-time system library search path. - Directories that appear in this list are never hard-coded into - executables. - - -- Variable: sys_lib_search_path_spec - Expression to get the compile-time system library search path. - This variable is used by libtool when it has to test whether a - certain library is shared or static. The directories listed in - `shlibpath_var' are automatically appended to this list, every time - libtool runs (i.e., not at configuration time), because some - linkers use this variable to extend the library search path. - Linker switches such as `-L' also augment the search path. - - -- Variable: thread_safe_flag_spec - Linker flag (passed through the C compiler) used to generate - thread-safe libraries. - - -- Variable: to_host_file_cmd - If the toolchain is not native to the build platform (e.g. if you - are using MSYS to drive the scripting, but are using the MinGW - native Windows compiler) this variable describes how to convert - file names from the format used by the build platform to the - format used by host platform. Normally set to - `func_convert_file_noop', libtool will autodetect most cases in - which other values should be used. On rare occasions, it may be - necessary to override the autodetected value (*note Cygwin to - MinGW Cross::). - - -- Variable: to_tool_file_cmd - If the toolchain is not native to the build platform (e.g. if you - are using some Unix to drive the scripting together with a Windows - toolchain running in Wine) this variable describes how to convert - file names from the format used by the build platform to the - format used by the toolchain. Normally set to - `func_convert_file_noop'. - - -- Variable: version_type - The library version numbering type. One of `libtool', - `freebsd-aout', `freebsd-elf', `irix', `linux', `osf', `sunos', - `windows', or `none'. - - -- Variable: want_nocaseglob - Find potential files using the shell option `nocaseglob', when - `deplibs_check_method' is `file_magic'. Normally set to `no'. Set - to `yes' to enable the `nocaseglob' shell option when looking for - potential file names in a case-insensitive manner. - - -- Variable: whole_archive_flag_spec - Compiler flag to generate shared objects from convenience archives. - - -- Variable: wl - The C compiler flag that allows libtool to pass a flag directly to - the linker. Used as: `${wl}SOME-FLAG'. - - Variables ending in `_cmds' or `_eval' contain a `~'-separated list -of commands that are `eval'ed one after another. If any of the -commands return a nonzero exit status, libtool generally exits with an -error message. - - Variables ending in `_spec' are `eval'ed before being used by -libtool. - - -File: libtool.info, Node: Cheap tricks, Prev: libtool script contents, Up: Maintaining - -15.5 Cheap tricks -================= - -Here are a few tricks that you can use in order to make maintainership -easier: - - * When people report bugs, ask them to use the `--config', - `--debug', or `--features' flags, if you think they will help you. - These flags are there to help you get information directly, rather - than having to trust second-hand observation. - - * Rather than reconfiguring libtool every time I make a change to - `ltmain.in', I keep a permanent `libtool' script in my `PATH', - which sources `ltmain.in' directly. - - The following steps describe how to create such a script, where - `/home/src/libtool' is the directory containing the libtool source - tree, `/home/src/libtool/libtool' is a libtool script that has been - configured for your platform, and `~/bin' is a directory in your - `PATH': - - trick$ cd ~/bin - trick$ sed 's%^\(macro_version=\).*$%\1@VERSION@%; - s%^\(macro_revision=\).*$%\1@package_revision@%; - /^# ltmain\.sh/q' /home/src/libtool/libtool > libtool - trick$ echo '. /home/src/libtool/ltmain.in' >> libtool - trick$ chmod +x libtool - trick$ libtool --version - ltmain.sh (GNU @PACKAGE@@TIMESTAMP@) @VERSION@ - - Copyright (C) 2011 Free Software Foundation, Inc. - This is free software; see the source for copying conditions. There is NO - warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - trick$ - - The output of the final `libtool --version' command shows that the -`ltmain.in' script is being used directly. Now, modify `~/bin/libtool' -or `/home/src/libtool/ltmain.in' directly in order to test new changes -without having to rerun `configure'. - diff --git a/gtk+-mingw/share/info/libtool.info-2 b/gtk+-mingw/share/info/libtool.info-2 deleted file mode 100644 index 607fef5..0000000 --- a/gtk+-mingw/share/info/libtool.info-2 +++ /dev/null @@ -1,1227 +0,0 @@ -This is doc/libtool.info, produced by makeinfo version 4.13 from -./doc/libtool.texi. - -INFO-DIR-SECTION GNU programming tools -START-INFO-DIR-ENTRY -* Libtool: (libtool). Generic shared library support script. -END-INFO-DIR-ENTRY - -INFO-DIR-SECTION Individual utilities -START-INFO-DIR-ENTRY -* libtool-invocation: (libtool)Invoking libtool. - Running the `libtool' script. -* libtoolize: (libtool)Invoking libtoolize. Adding libtool support. -END-INFO-DIR-ENTRY - - This file documents GNU Libtool 2.4.2 - - Copyright (C) 1996-2011 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled "GNU -Free Documentation License". - - -File: libtool.info, Node: GNU Free Documentation License, Next: Combined Index, Prev: Maintaining, Up: Top - -Appendix A GNU Free Documentation License -***************************************** - - Version 1.3, 3 November 2008 - - Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. - `http://fsf.org/' - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. - We recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it - can be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You - accept the license if you copy, modify or distribute the work in a - way requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in - the notice that says that the Document is released under this - License. If a section does not fit the above definition of - Secondary then it is not allowed to be designated as Invariant. - The Document may contain zero Invariant Sections. If the Document - does not identify any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup, or absence of - markup, has been arranged to thwart or discourage subsequent - modification by readers is not Transparent. An image format is - not Transparent if used for any substantial amount of text. A - copy that is not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and - standard-conforming simple HTML, PostScript or PDF designed for - human modification. Examples of transparent image formats include - PNG, XCF and JPG. Opaque formats include proprietary formats that - can be read and edited only by proprietary word processors, SGML or - XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML, PostScript or PDF - produced by some word processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - The "publisher" means any person or entity that distributes copies - of the Document to the public. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow - the conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the - title equally prominent and visible. You may add other material - on the covers in addition. Copying with changes limited to the - covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in - other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a computer-network location from - which the general network-using public has access to download - using public-standard network protocols a complete Transparent - copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of - copies, to give them a chance to provide you with an updated - version of the Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with - the Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version to - whoever possesses a copy of it. In addition, you must do these - things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of - previous versions (which should, if there were any, be listed - in the History section of the Document). You may use the - same title as a previous version if the original publisher of - that version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on - the Title Page. If there is no section Entitled "History" in - the Document, create one stating the title, year, authors, - and publisher of the Document as given on its Title Page, - then add an item describing the Modified Version as stated in - the previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in - the "History" section. You may omit a network location for a - work that was published at least four years before the - Document itself, or if the original publisher of the version - it refers to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the - section all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section - titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end - of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow - this License in all other respects regarding verbatim copying of - that document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included in an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warranty Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided under this License. Any attempt - otherwise to copy, modify, sublicense, or distribute it is void, - and will automatically terminate your rights under this License. - - However, if you cease all violation of this License, then your - license from a particular copyright holder is reinstated (a) - provisionally, unless and until the copyright holder explicitly - and finally terminates your license, and (b) permanently, if the - copyright holder fails to notify you of the violation by some - reasonable means prior to 60 days after the cessation. - - Moreover, your license from a particular copyright holder is - reinstated permanently if the copyright holder notifies you of the - violation by some reasonable means, this is the first time you have - received notice of violation of this License (for any work) from - that copyright holder, and you cure the violation prior to 30 days - after your receipt of the notice. - - Termination of your rights under this section does not terminate - the licenses of parties who have received copies or rights from - you under this License. If your rights have been terminated and - not permanently reinstated, receipt of a copy of some or all of - the same material does not give you any rights to use it. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - `http://www.gnu.org/copyleft/'. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. If the Document specifies that a proxy - can decide which future versions of this License can be used, that - proxy's public statement of acceptance of a version permanently - authorizes you to choose that version for the Document. - - 11. RELICENSING - - "Massive Multiauthor Collaboration Site" (or "MMC Site") means any - World Wide Web server that publishes copyrightable works and also - provides prominent facilities for anybody to edit those works. A - public wiki that anybody can edit is an example of such a server. - A "Massive Multiauthor Collaboration" (or "MMC") contained in the - site means any set of copyrightable works thus published on the MMC - site. - - "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 - license published by Creative Commons Corporation, a not-for-profit - corporation with a principal place of business in San Francisco, - California, as well as future copyleft versions of that license - published by that same organization. - - "Incorporate" means to publish or republish a Document, in whole or - in part, as part of another Document. - - An MMC is "eligible for relicensing" if it is licensed under this - License, and if all works that were first published under this - License somewhere other than this MMC, and subsequently - incorporated in whole or in part into the MMC, (1) had no cover - texts or invariant sections, and (2) were thus incorporated prior - to November 1, 2008. - - The operator of an MMC Site may republish an MMC contained in the - site under CC-BY-SA on the same site at any time before August 1, - 2009, provided the MMC is eligible for relicensing. - - -ADDENDUM: How to use this License for your documents -==================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover -Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, to -permit their use in free software. - - -File: libtool.info, Node: Combined Index, Prev: GNU Free Documentation License, Up: Top - -Combined Index -************** - - -* Menu: - -* -no-suppress, libtool compile mode option: Creating object files. - (line 92) -* -weak option: Linking with dlopened modules. - (line 94) -* .la files: Linking libraries. (line 24) -* .libs subdirectory: Linking libraries. (line 77) -* .lo files: Creating object files. - (line 28) -* AC_CONFIG_AUX_DIR: Invoking libtoolize. (line 157) -* AC_CONFIG_MACRO_DIR: Invoking libtoolize. (line 136) -* AC_DISABLE_FAST_INSTALL: LT_INIT. (line 185) -* AC_DISABLE_SHARED: LT_INIT. (line 189) -* AC_DISABLE_STATIC: LT_INIT. (line 206) -* AC_ENABLE_SHARED: LT_INIT. (line 197) -* AC_ENABLE_STATIC: LT_INIT. (line 214) -* AC_LIBLTDL_CONVENIENCE: Distributing libltdl. - (line 302) -* AC_LIBLTDL_INSTALLABLE: Distributing libltdl. - (line 297) -* AC_LIBTOOL_DLOPEN: LT_INIT. (line 177) -* AC_LIBTOOL_WIN32_DLL: LT_INIT. (line 181) -* AC_PROG_LIBTOOL: LT_INIT. (line 22) -* AC_WITH_LTDL: Distributing libltdl. - (line 42) -* aclocal: LT_INIT. (line 322) -* allow_undefined_flag: libtool script contents. - (line 76) -* always_export_symbols: libtool script contents. - (line 83) -* AM_DISABLE_SHARED: LT_INIT. (line 190) -* AM_DISABLE_STATIC: LT_INIT. (line 207) -* AM_ENABLE_SHARED: LT_INIT. (line 198) -* AM_ENABLE_STATIC: LT_INIT. (line 215) -* AM_PROG_LIBTOOL: LT_INIT. (line 23) -* application-level dynamic linking <1>: Dlopened modules. (line 6) -* application-level dynamic linking: Using libltdl. (line 6) -* ar: Linking libraries. (line 6) -* AR: libtool script contents. - (line 30) -* archive_cmds: libtool script contents. - (line 88) -* archive_expsym_cmds: libtool script contents. - (line 89) -* archiver_list_spec: libtool script contents. - (line 94) -* AS: LT_INIT. (line 278) -* autoconf traces: Trace interface. (line 6) -* avoiding shared libraries: Static-only libraries. - (line 6) -* bug reports: Reporting bugs. (line 6) -* buggy system linkers: Linking executables. (line 11) -* bugs, subtle ones caused by buggy linkers: Linking executables. - (line 16) -* build: libtool script contents. - (line 118) -* build_alias: libtool script contents. - (line 119) -* build_libtool_libs: libtool script contents. - (line 124) -* build_old_libs: libtool script contents. - (line 128) -* build_os: libtool script contents. - (line 120) -* C header files, portable: C header files. (line 6) -* C++, pitfalls: C++ libraries. (line 6) -* C++, using: Other languages. (line 6) -* C, not using: Other languages. (line 6) -* CC <1>: LT_INIT. (line 228) -* CC: libtool script contents. - (line 33) -* cdemo-conf.test: Test descriptions. (line 21) -* cdemo-exec.test: Test descriptions. (line 21) -* cdemo-make.test: Test descriptions. (line 21) -* cdemo-shared-exec.test: Test descriptions. (line 21) -* cdemo-shared-make.test: Test descriptions. (line 21) -* cdemo-shared.test: Test descriptions. (line 21) -* cdemo-static-exec.test: Test descriptions. (line 21) -* cdemo-static-make.test: Test descriptions. (line 21) -* cdemo-static.test: Test descriptions. (line 21) -* cdemo-undef-exec.test: Test descriptions. (line 21) -* cdemo-undef-make.test: Test descriptions. (line 21) -* cdemo-undef.test: Test descriptions. (line 21) -* CFLAGS: LT_INIT. (line 232) -* check-interactive: Test descriptions. (line 334) -* check-noninteractive: Test descriptions. (line 334) -* clean mode: Clean mode. (line 6) -* command options, libtool: Invoking libtool. (line 6) -* command options, libtoolize: Invoking libtoolize. (line 6) -* compile mode: Compile mode. (line 6) -* compiler_c_o: libtool script contents. - (line 132) -* compiler_needs_object: libtool script contents. - (line 136) -* compiling object files: Creating object files. - (line 6) -* complexity of library systems: Postmortem. (line 11) -* config.guess: Distributing. (line 10) -* config.sub: Distributing. (line 13) -* configuring libtool: Configuring. (line 6) -* convenience libraries: Static libraries. (line 6) -* CPPFLAGS: LT_INIT. (line 237) -* cross compile: Cross compiling. (line 6) -* Cygwin to MinGW Cross: Cygwin to MinGW Cross. - (line 6) -* debugging libraries: Static-only libraries. - (line 6) -* definition of libraries: Libtool paradigm. (line 11) -* demo-conf.test: Test descriptions. (line 66) -* demo-deplibs.test: Test descriptions. (line 84) -* demo-exec.test: Test descriptions. (line 66) -* demo-hardcode.test: Test descriptions. (line 90) -* demo-inst.test: Test descriptions. (line 66) -* demo-make.test: Test descriptions. (line 66) -* demo-nofast-exec.test: Test descriptions. (line 66) -* demo-nofast-inst.test: Test descriptions. (line 66) -* demo-nofast-make.test: Test descriptions. (line 66) -* demo-nofast-unst.test: Test descriptions. (line 66) -* demo-nofast.test: Test descriptions. (line 66) -* demo-noinst-link.test: Test descriptions. (line 104) -* demo-nopic-exec.test: Test descriptions. (line 66) -* demo-nopic-make.test: Test descriptions. (line 66) -* demo-nopic.test: Test descriptions. (line 66) -* demo-pic-exec.test: Test descriptions. (line 66) -* demo-pic-make.test: Test descriptions. (line 66) -* demo-pic.test: Test descriptions. (line 66) -* demo-relink.test: Test descriptions. (line 99) -* demo-shared-exec.test: Test descriptions. (line 66) -* demo-shared-inst.test: Test descriptions. (line 66) -* demo-shared-make.test: Test descriptions. (line 66) -* demo-shared-unst.test: Test descriptions. (line 66) -* demo-shared.test: Test descriptions. (line 66) -* demo-static-exec.test: Test descriptions. (line 66) -* demo-static-inst.test: Test descriptions. (line 66) -* demo-static-make.test: Test descriptions. (line 66) -* demo-static-unst.test: Test descriptions. (line 66) -* demo-static.test: Test descriptions. (line 66) -* demo-unst.test: Test descriptions. (line 66) -* depdemo-conf.test: Test descriptions. (line 128) -* depdemo-exec.test: Test descriptions. (line 128) -* depdemo-inst.test: Test descriptions. (line 128) -* depdemo-make.test: Test descriptions. (line 128) -* depdemo-nofast-exec.test: Test descriptions. (line 128) -* depdemo-nofast-inst.test: Test descriptions. (line 128) -* depdemo-nofast-make.test: Test descriptions. (line 128) -* depdemo-nofast-unst.test: Test descriptions. (line 128) -* depdemo-nofast.test: Test descriptions. (line 128) -* depdemo-relink.test: Test descriptions. (line 99) -* depdemo-shared-exec.test: Test descriptions. (line 128) -* depdemo-shared-inst.test: Test descriptions. (line 128) -* depdemo-shared-make.test: Test descriptions. (line 128) -* depdemo-shared-unst.test: Test descriptions. (line 128) -* depdemo-shared.test: Test descriptions. (line 128) -* depdemo-static-exec.test: Test descriptions. (line 128) -* depdemo-static-inst.test: Test descriptions. (line 128) -* depdemo-static-make.test: Test descriptions. (line 128) -* depdemo-static-unst.test: Test descriptions. (line 128) -* depdemo-static.test: Test descriptions. (line 128) -* depdemo-unst.test: Test descriptions. (line 128) -* dependencies between libraries: Inter-library dependencies. - (line 6) -* dependency versioning: Versioning. (line 6) -* deplibs_check_method: Porting inter-library dependencies. - (line 6) -* design issues: Issues. (line 6) -* design of library interfaces: Library tips. (line 6) -* design philosophy: Motivation. (line 6) -* developing libraries: Static-only libraries. - (line 6) -* dlclose <1>: Dlopened modules. (line 6) -* dlclose: Using libltdl. (line 6) -* dlerror: Using libltdl. (line 6) -* DLLTOOL: LT_INIT. (line 270) -* dlopen <1>: Dlopened modules. (line 6) -* dlopen: Using libltdl. (line 6) -* dlopen_self: libtool script contents. - (line 146) -* dlopen_self_static: libtool script contents. - (line 150) -* dlopen_support: libtool script contents. - (line 142) -* dlopening modules <1>: Dlopened modules. (line 6) -* dlopening modules: Using libltdl. (line 6) -* dlopening, pitfalls: Dlopen issues. (line 6) -* dlsym <1>: Dlopened modules. (line 6) -* dlsym: Using libltdl. (line 6) -* double-compilation, avoiding: Static-only libraries. - (line 6) -* dynamic dependencies: Versioning. (line 6) -* dynamic linking, applications <1>: Using libltdl. (line 6) -* dynamic linking, applications: Dlopened modules. (line 6) -* dynamic modules, names: Finding the dlname. (line 6) -* ECHO: libtool script contents. - (line 38) -* eliding shared libraries: Static-only libraries. - (line 6) -* examples of using libtool: Using libtool. (line 6) -* exclude_expsyms: libtool script contents. - (line 154) -* execute mode: Execute mode. (line 6) -* export_dynamic_flag_spec: libtool script contents. - (line 157) -* export_symbols_cmds: libtool script contents. - (line 161) -* extract_expsyms_cmds: libtool script contents. - (line 165) -* f77demo-conf.test: Test descriptions. (line 263) -* f77demo-exec.test: Test descriptions. (line 263) -* f77demo-make.test: Test descriptions. (line 263) -* f77demo-shared-exec.test: Test descriptions. (line 263) -* f77demo-shared-make.test: Test descriptions. (line 263) -* f77demo-shared.test: Test descriptions. (line 263) -* f77demo-static-exec.test: Test descriptions. (line 263) -* f77demo-static-make.test: Test descriptions. (line 263) -* f77demo-static.test: Test descriptions. (line 263) -* failed tests: When tests fail. (line 6) -* fast_install: libtool script contents. - (line 172) -* fcdemo-conf.test: Test descriptions. (line 281) -* fcdemo-exec.test: Test descriptions. (line 281) -* fcdemo-make.test: Test descriptions. (line 281) -* fcdemo-shared-exec.test: Test descriptions. (line 281) -* fcdemo-shared-make.test: Test descriptions. (line 281) -* fcdemo-shared.test: Test descriptions. (line 281) -* fcdemo-static-exec.test: Test descriptions. (line 281) -* fcdemo-static-make.test: Test descriptions. (line 281) -* fcdemo-static.test: Test descriptions. (line 281) -* FDL, GNU Free Documentation License: GNU Free Documentation License. - (line 6) -* file name conversion: File name conversion. - (line 6) -* File Name Conversion - Cygwin to Windows: Cygwin/Windows File Name Conversion. - (line 6) -* File Name Conversion - Failure: File Name Conversion Failure. - (line 6) -* File Name Conversion - MinGW: Native MinGW File Name Conversion. - (line 6) -* File Name Conversion - Unix to Windows: Unix/Windows File Name Conversion. - (line 6) -* file_magic: Porting inter-library dependencies. - (line 18) -* file_magic_cmd: Porting inter-library dependencies. - (line 18) -* file_magic_glob: libtool script contents. - (line 194) -* file_magic_test_file: Porting inter-library dependencies. - (line 18) -* finish mode: Finish mode. (line 6) -* finish_cmds: libtool script contents. - (line 203) -* finish_eval: libtool script contents. - (line 207) -* formal versioning: Libtool versioning. (line 6) -* func_convert_file_cygwin_to_w32: Cygwin to MinGW Cross. - (line 61) -* global functions: Library tips. (line 45) -* global_symbol_pipe: libtool script contents. - (line 210) -* global_symbol_to_cdecl: libtool script contents. - (line 224) -* hardcode_action: libtool script contents. - (line 230) -* hardcode_direct: libtool script contents. - (line 235) -* hardcode_direct_absolute: libtool script contents. - (line 241) -* hardcode_into_libs: libtool script contents. - (line 247) -* hardcode_libdir_flag_spec: libtool script contents. - (line 253) -* hardcode_libdir_separator: libtool script contents. - (line 259) -* hardcode_minus_L: libtool script contents. - (line 264) -* hardcode_shlibpath_var: libtool script contents. - (line 269) -* header files: Library tips. (line 39) -* host: libtool script contents. - (line 276) -* host_alias: libtool script contents. - (line 277) -* host_os: libtool script contents. - (line 278) -* implementation of libtool: libtool script contents. - (line 6) -* include files, portable: C header files. (line 6) -* include_expsyms: libtool script contents. - (line 282) -* inferring tags: Tags. (line 6) -* inherit_rpath: libtool script contents. - (line 286) -* install: Installing libraries. - (line 19) -* install mode: Install mode. (line 6) -* install-sh: Distributing. (line 16) -* install_override_mode: libtool script contents. - (line 291) -* installation, finishing: Installing libraries. - (line 54) -* inter-library dependencies: Inter-library dependencies. - (line 6) -* inter-library dependency: Porting inter-library dependencies. - (line 6) -* language names: Tags. (line 6) -* languages, non-C: Other languages. (line 6) -* LD <1>: LT_INIT. (line 242) -* LD: libtool script contents. - (line 43) -* LDFLAGS: LT_INIT. (line 247) -* libext: libtool script contents. - (line 299) -* libltdl: Using libltdl. (line 6) -* libname_spec: libtool script contents. - (line 302) -* libraries, definition of: Libtool paradigm. (line 11) -* libraries, finishing installation: Installing libraries. - (line 54) -* libraries, stripping: Installing libraries. - (line 44) -* library interfaces: Interfaces. (line 6) -* library interfaces, design: Library tips. (line 6) -* library object file: Creating object files. - (line 28) -* library_names_spec: libtool script contents. - (line 307) -* LIBS: LT_INIT. (line 253) -* libtool: Invoking libtool. (line 6) -* libtool command options: Invoking libtool. (line 6) -* libtool examples: Using libtool. (line 6) -* libtool implementation: libtool script contents. - (line 6) -* libtool libraries: Linking libraries. (line 24) -* libtool library versions: Libtool versioning. (line 6) -* libtool specifications: Motivation. (line 20) -* libtoolize: Invoking libtoolize. (line 6) -* libtoolize command options: Invoking libtoolize. (line 6) -* LIBTOOLIZE_OPTIONS: Invoking libtoolize. (line 120) -* link mode: Link mode. (line 6) -* link-2.test: Test descriptions. (line 198) -* link.test: Test descriptions. (line 194) -* link_all_deplibs: libtool script contents. - (line 312) -* link_static_flag: libtool script contents. - (line 317) -* linking against installed libraries: Linking executables. (line 6) -* linking against uninstalled libraries: Linking executables. (line 25) -* linking with installed libtool libraries: Linking executables. - (line 50) -* linking, dlopen: Linking with dlopened modules. - (line 6) -* linking, dlpreopen: Linking with dlopened modules. - (line 6) -* linking, partial: Link mode. (line 207) -* LN_S: LT_INIT. (line 265) -* lock_old_archive_extraction: libtool script contents. - (line 114) -* LT_CMD_MAX_LEN: Autoconf macros. (line 15) -* LT_CONFIG_LTDL_DIR: Distributing libltdl. - (line 32) -* lt_cv_to_host_file_cmd: Cygwin to MinGW Cross. - (line 61) -* lt_cv_to_tool_file_cmd: Cygwin to MinGW Cross. - (line 61) -* LT_CYGPATH: LT_CYGPATH. (line 6) -* LT_DIRSEP_CHAR: Libltdl interface. (line 40) -* lt_dladderror: Module loaders for libltdl. - (line 191) -* lt_dladdsearchdir: Libltdl interface. (line 244) -* lt_dladvise: Libltdl interface. (line 50) -* lt_dladvise_destroy: Libltdl interface. (line 147) -* lt_dladvise_ext: Libltdl interface. (line 154) -* lt_dladvise_global: Libltdl interface. (line 179) -* lt_dladvise_init: Libltdl interface. (line 137) -* lt_dladvise_local: Libltdl interface. (line 196) -* lt_dladvise_preload: Libltdl interface. (line 222) -* lt_dladvise_resident: Libltdl interface. (line 213) -* lt_dlcaller_get_data: User defined module data. - (line 154) -* lt_dlcaller_set_data: User defined module data. - (line 128) -* lt_dlclose: Libltdl interface. (line 228) -* lt_dlerror: Libltdl interface. (line 238) -* lt_dlexit: Libltdl interface. (line 66) -* lt_dlforeachfile: Libltdl interface. (line 264) -* lt_dlgetinfo: User defined module data. - (line 26) -* lt_dlgetsearchpath: Libltdl interface. (line 260) -* lt_dlhandle: Libltdl interface. (line 46) -* lt_dlhandle_fetch: User defined module data. - (line 112) -* lt_dlhandle_interface: User defined module data. - (line 40) -* lt_dlhandle_iterate: User defined module data. - (line 97) -* lt_dlhandle_map: User defined module data. - (line 86) -* lt_dlinfo: User defined module data. - (line 12) -* lt_dlinit: Libltdl interface. (line 61) -* lt_dlinsertsearchdir: Libltdl interface. (line 249) -* lt_dlinterface_free: User defined module data. - (line 82) -* lt_dlinterface_id: User defined module data. - (line 35) -* lt_dlinterface_register: User defined module data. - (line 74) -* lt_dlisresident: Libltdl interface. (line 292) -* lt_dlloader: Module loaders for libltdl. - (line 45) -* lt_dlloader_add: Module loaders for libltdl. - (line 132) -* lt_dlloader_data: Module loaders for libltdl. - (line 182) -* lt_dlloader_exit: Module loaders for libltdl. - (line 86) -* lt_dlloader_find: Module loaders for libltdl. - (line 164) -* lt_dlloader_name: Module loaders for libltdl. - (line 176) -* lt_dlloader_next: Module loaders for libltdl. - (line 155) -* lt_dlloader_remove: Module loaders for libltdl. - (line 145) -* lt_dlmakeresident: Libltdl interface. (line 282) -* lt_dlopen: Libltdl interface. (line 72) -* lt_dlopenadvise: Libltdl interface. (line 127) -* lt_dlopenext: Libltdl interface. (line 110) -* lt_dlpreload: Dlpreopening. (line 69) -* lt_dlpreload_callback_func: Dlpreopening. (line 97) -* lt_dlpreload_default: Dlpreopening. (line 75) -* lt_dlpreload_open: Dlpreopening. (line 103) -* lt_dlseterror: Module loaders for libltdl. - (line 203) -* lt_dlsetsearchpath: Libltdl interface. (line 255) -* lt_dlsym: Libltdl interface. (line 233) -* lt_dlsymlist <1>: Dlpreopening. (line 42) -* lt_dlsymlist: Libltdl interface. (line 55) -* lt_find_sym: Module loaders for libltdl. - (line 79) -* LT_FUNC_DLSYM_USCORE: Autoconf macros. (line 24) -* LT_INIT: LT_INIT. (line 21) -* LT_LANG: LT_INIT. (line 155) -* LT_LIB_DLLOAD: Autoconf macros. (line 35) -* LT_LIB_M: Autoconf macros. (line 31) -* lt_module: Module loaders for libltdl. - (line 41) -* lt_module_close: Module loaders for libltdl. - (line 72) -* lt_module_open: Module loaders for libltdl. - (line 61) -* LT_OUTPUT: LT_INIT. (line 309) -* LT_PATH_LD: Autoconf macros. (line 51) -* LT_PATH_NM: Autoconf macros. (line 57) -* LT_PATHSEP_CHAR: Libltdl interface. (line 36) -* lt_preloaded_symbols: Dlpreopening. (line 47) -* LT_PREREQ: LT_INIT. (line 13) -* LT_SUPPORTED_TAG: Trace interface. (line 13) -* LT_SYS_DLOPEN_DEPLIBS: Autoconf macros. (line 70) -* LT_SYS_DLOPEN_SELF: Autoconf macros. (line 64) -* LT_SYS_DLSEARCH_PATH: Autoconf macros. (line 75) -* LT_SYS_MODULE_EXT: Autoconf macros. (line 79) -* LT_SYS_MODULE_PATH: Autoconf macros. (line 85) -* LT_SYS_SYMBOL_USCORE: Autoconf macros. (line 90) -* lt_user_data: Module loaders for libltdl. - (line 48) -* lt_user_dlloader: Module loaders for libltdl. - (line 53) -* LT_WITH_LTDL: Distributing libltdl. - (line 41) -* LTCC: libtool script contents. - (line 47) -* LTCFLAGS: libtool script contents. - (line 48) -* LTDL_CONVENIENCE: Distributing libltdl. - (line 301) -* LTDL_INIT: Distributing libltdl. - (line 40) -* LTDL_INSTALLABLE: Distributing libltdl. - (line 296) -* LTDL_SET_PRELOADED_SYMBOLS: Dlpreopening. (line 85) -* LTLIBOBJS: Autoconf and LTLIBOBJS. - (line 8) -* LTLIBRARIES: Using Automake. (line 6) -* ltmain.sh: Distributing. (line 19) -* macro_revision: libtool script contents. - (line 322) -* macro_version: libtool script contents. - (line 321) -* Makefile: Makefile rules. (line 6) -* Makefile.am: Makefile rules. (line 6) -* Makefile.in: Makefile rules. (line 6) -* MANIFEST_TOOL: LT_INIT. (line 282) -* max_cmd_len: libtool script contents. - (line 327) -* mdemo-conf.test: Test descriptions. (line 161) -* mdemo-dryrun.test: Test descriptions. (line 180) -* mdemo-exec.test: Test descriptions. (line 161) -* mdemo-inst.test: Test descriptions. (line 161) -* mdemo-make.test: Test descriptions. (line 161) -* mdemo-shared-exec.test: Test descriptions. (line 161) -* mdemo-shared-inst.test: Test descriptions. (line 161) -* mdemo-shared-make.test: Test descriptions. (line 161) -* mdemo-shared-unst.test: Test descriptions. (line 161) -* mdemo-shared.test: Test descriptions. (line 161) -* mdemo-static-exec.test: Test descriptions. (line 161) -* mdemo-static-inst.test: Test descriptions. (line 161) -* mdemo-static-make.test: Test descriptions. (line 161) -* mdemo-static-unst.test: Test descriptions. (line 161) -* mdemo-static.test: Test descriptions. (line 161) -* mdemo-unst.test: Test descriptions. (line 161) -* mdemo2-conf.test: Test descriptions. (line 185) -* mdemo2-exec.test: Test descriptions. (line 185) -* mdemo2-make.test: Test descriptions. (line 185) -* mode, clean: Clean mode. (line 6) -* mode, compile: Compile mode. (line 6) -* mode, execute: Execute mode. (line 6) -* mode, finish: Finish mode. (line 6) -* mode, install: Install mode. (line 6) -* mode, link: Link mode. (line 6) -* mode, uninstall: Uninstall mode. (line 6) -* modules, dynamic <1>: Dlopened modules. (line 6) -* modules, dynamic: Using libltdl. (line 6) -* motivation for writing libtool: Motivation. (line 6) -* MSYS: Native MinGW File Name Conversion. - (line 6) -* names of dynamic modules: Finding the dlname. (line 6) -* need_lib_prefix: libtool script contents. - (line 331) -* need_locks: libtool script contents. - (line 344) -* need_version: libtool script contents. - (line 338) -* NM <1>: LT_INIT. (line 259) -* NM: libtool script contents. - (line 52) -* nm_file_list_spec: libtool script contents. - (line 348) -* no_builtin_flag: libtool script contents. - (line 351) -* no_undefined_flag: libtool script contents. - (line 355) -* nomode.test: Test descriptions. (line 202) -* none: Porting inter-library dependencies. - (line 38) -* objdir: libtool script contents. - (line 360) -* OBJDUMP: LT_INIT. (line 274) -* object files, compiling: Creating object files. - (line 6) -* object files, library: Creating object files. - (line 28) -* objectlist.test: Test descriptions. (line 205) -* objext: libtool script contents. - (line 363) -* old_archive_cmds: libtool script contents. - (line 90) -* old_archive_from_expsyms_cmds: libtool script contents. - (line 103) -* old_archive_from_new_cmds: libtool script contents. - (line 97) -* old_postinstall_cmds: libtool script contents. - (line 370) -* old_postuninstall_cmds: libtool script contents. - (line 375) -* old_striplib: libtool script contents. - (line 415) -* opaque data types: Library tips. (line 28) -* options, libtool command: Invoking libtool. (line 6) -* options, libtoolize command: Invoking libtoolize. (line 6) -* other implementations, flaws in: Postmortem. (line 6) -* partial linking: Link mode. (line 207) -* pass_all: Porting inter-library dependencies. - (line 32) -* path conversion: File name conversion. - (line 6) -* Path Conversion - Cygwin to Windows: Cygwin/Windows File Name Conversion. - (line 6) -* Path Conversion - Failure: File Name Conversion Failure. - (line 6) -* Path Conversion - MinGW: Native MinGW File Name Conversion. - (line 6) -* Path Conversion - Unix to Windows: Unix/Windows File Name Conversion. - (line 6) -* pdemo-conf.test: Test descriptions. (line 211) -* pdemo-exec.test: Test descriptions. (line 211) -* pdemo-inst.test: Test descriptions. (line 211) -* pdemo-make.test: Test descriptions. (line 211) -* PIC (position-independent code): Creating object files. - (line 23) -* pic_flag: libtool script contents. - (line 366) -* pitfalls using C++: C++ libraries. (line 6) -* pitfalls with dlopen: Dlopen issues. (line 6) -* portable C headers: C header files. (line 6) -* position-independent code: Creating object files. - (line 23) -* postinstall_cmds: libtool script contents. - (line 369) -* postinstallation: Installing libraries. - (line 54) -* postlink_cmds: libtool script contents. - (line 379) -* postuninstall_cmds: libtool script contents. - (line 374) -* problem reports: Reporting bugs. (line 6) -* problems, blaming somebody else for: Troubleshooting. (line 6) -* problems, solving: Troubleshooting. (line 6) -* program wrapper executables: Wrapper executables. (line 6) -* program wrapper scripts: Linking executables. (line 71) -* quote.test: Test descriptions. (line 220) -* ranlib: Linking libraries. (line 12) -* RANLIB <1>: LT_INIT. (line 262) -* RANLIB: libtool script contents. - (line 73) -* reload_cmds: libtool script contents. - (line 388) -* reload_flag: libtool script contents. - (line 389) -* renaming interface functions: Library tips. (line 21) -* reporting bugs: Reporting bugs. (line 6) -* reusability of library systems: Postmortem. (line 6) -* runpath_var: libtool script contents. - (line 393) -* saving time: Static-only libraries. - (line 6) -* security problems with buggy linkers: Linking executables. (line 16) -* sh.test: Test descriptions. (line 223) -* shared libraries, not using: Static-only libraries. - (line 6) -* shared library versions: Versioning. (line 6) -* shl_load <1>: Dlopened modules. (line 6) -* shl_load: Using libltdl. (line 6) -* shlibpath_overrides_runpath: libtool script contents. - (line 397) -* shlibpath_var: libtool script contents. - (line 406) -* solving problems: Troubleshooting. (line 6) -* soname_spec: libtool script contents. - (line 410) -* specifications for libtool: Motivation. (line 20) -* standalone binaries: Static libraries. (line 64) -* static linking: Static libraries. (line 6) -* strip: Installing libraries. - (line 6) -* striplib: libtool script contents. - (line 414) -* stripping libraries: Installing libraries. - (line 44) -* su: Installing libraries. - (line 9) -* suffix.test: Test descriptions. (line 227) -* sys_lib_dlsearch_path_spec: libtool script contents. - (line 421) -* sys_lib_search_path_spec: libtool script contents. - (line 426) -* tag names: Tags. (line 6) -* tagdemo-conf.test: Test descriptions. (line 245) -* tagdemo-exec.test: Test descriptions. (line 245) -* tagdemo-make.test: Test descriptions. (line 245) -* tagdemo-shared-exec.test: Test descriptions. (line 245) -* tagdemo-shared-make.test: Test descriptions. (line 245) -* tagdemo-shared.test: Test descriptions. (line 245) -* tagdemo-static-exec.test: Test descriptions. (line 245) -* tagdemo-static-make.test: Test descriptions. (line 245) -* tagdemo-static.test: Test descriptions. (line 245) -* tagdemo-undef-exec.test: Test descriptions. (line 245) -* tagdemo-undef-make.test: Test descriptions. (line 245) -* tagdemo-undef.test: Test descriptions. (line 245) -* test suite: Libtool test suite. (line 6) -* test_compile: Porting inter-library dependencies. - (line 26) -* tests, failed: When tests fail. (line 6) -* thread_safe_flag_spec: libtool script contents. - (line 435) -* time, saving: Static-only libraries. - (line 6) -* to_host_file_cmd: libtool script contents. - (line 439) -* to_tool_file_cmd: libtool script contents. - (line 450) -* trace interface: Trace interface. (line 6) -* tricky design issues: Issues. (line 6) -* trouble with C++: C++ libraries. (line 6) -* trouble with dlopen: Dlopen issues. (line 6) -* troubleshooting: Troubleshooting. (line 6) -* undefined symbols, allowing: Link mode. (line 14) -* uninstall mode: Uninstall mode. (line 6) -* unknown: Porting inter-library dependencies. - (line 43) -* unresolved symbols, allowing: Link mode. (line 14) -* using shared libraries, not: Static-only libraries. - (line 6) -* version_type: libtool script contents. - (line 458) -* versioning, formal: Libtool versioning. (line 6) -* want_nocaseglob: libtool script contents. - (line 463) -* whole_archive_flag_spec: libtool script contents. - (line 469) -* Windows DLLs: Windows DLLs. (line 6) -* wl: libtool script contents. - (line 472) -* wrapper executables for uninstalled programs: Wrapper executables. - (line 6) -* wrapper scripts for programs: Linking executables. (line 71) - - |