diff options
| author | Leo Tenenbaum <pommicket@gmail.com> | 2018-08-20 20:34:57 -0400 |
|---|---|---|
| committer | Leo Tenenbaum <pommicket@gmail.com> | 2018-08-20 20:34:57 -0400 |
| commit | a4460f6d9453bbd7e584937686449cef3e19f052 (patch) | |
| tree | 037c208f1e20302ed048c0952ef8e3418add9c86 /gtk+-mingw/share/info | |
Initial commit0.0.0
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, 27213 insertions, 0 deletions
diff --git a/gtk+-mingw/share/info/autosprintf.info b/gtk+-mingw/share/info/autosprintf.info new file mode 100644 index 0000000..37af0bd --- /dev/null +++ b/gtk+-mingw/share/info/autosprintf.info @@ -0,0 +1,134 @@ +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 new file mode 100644 index 0000000..e240bf0 --- /dev/null +++ b/gtk+-mingw/share/info/dir @@ -0,0 +1,23 @@ +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 new file mode 100644 index 0000000..abd1869 --- /dev/null +++ b/gtk+-mingw/share/info/gettext.info @@ -0,0 +1,18374 @@ +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 new file mode 100644 index 0000000..402f760 --- /dev/null +++ b/gtk+-mingw/share/info/libffi.info @@ -0,0 +1,617 @@ +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 new file mode 100644 index 0000000..9a1263a --- /dev/null +++ b/gtk+-mingw/share/info/libtool.info @@ -0,0 +1,140 @@ +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 new file mode 100644 index 0000000..6d16648 --- /dev/null +++ b/gtk+-mingw/share/info/libtool.info-1 @@ -0,0 +1,6698 @@ +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 new file mode 100644 index 0000000..607fef5 --- /dev/null +++ b/gtk+-mingw/share/info/libtool.info-2 @@ -0,0 +1,1227 @@ +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) + + |