diff options
Diffstat (limited to 'doc/gettext_2.html')
| -rw-r--r-- | doc/gettext_2.html | 83 |
1 files changed, 80 insertions, 3 deletions
diff --git a/doc/gettext_2.html b/doc/gettext_2.html index 699dfc5..c419d89 100644 --- a/doc/gettext_2.html +++ b/doc/gettext_2.html @@ -1,12 +1,12 @@ <HTML> <HEAD> <!-- This HTML file has been created by texi2html 1.52a - from gettext.texi on 31 January 2002 --> + from gettext.texi on 7 March 2002 --> <TITLE>GNU gettext utilities - 2 PO Files and PO Mode Basics</TITLE> </HEAD> <BODY> -Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_1.html">previous</A>, <A HREF="gettext_3.html">next</A>, <A HREF="gettext_16.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. +Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_1.html">previous</A>, <A HREF="gettext_3.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. <P><HR><P> @@ -27,6 +27,8 @@ in one place. Here we present only the basics of PO mode. <H2><A NAME="SEC8" HREF="gettext_toc.html#TOC8">2.1 Completing GNU <CODE>gettext</CODE> Installation</A></H2> <P> +<A NAME="IDX39"></A> +<A NAME="IDX40"></A> Once you have received, unpacked, configured and compiled the GNU <CODE>gettext</CODE> distribution, the <SAMP>`make install´</SAMP> command puts in place the programs <CODE>xgettext</CODE>, <CODE>msgfmt</CODE>, <CODE>gettext</CODE>, and @@ -36,6 +38,8 @@ PO mode available to your Emacs users. </P> <P> +<A NAME="IDX41"></A> +<A NAME="IDX42"></A> During the installation of the PO mode, you might want to modify your file <TT>`.emacs´</TT>, once and for all, so it contains a few lines looking like: @@ -83,7 +87,11 @@ button 1). <H2><A NAME="SEC9" HREF="gettext_toc.html#TOC9">2.2 The Format of PO Files</A></H2> +<P> +<A NAME="IDX43"></A> +<A NAME="IDX44"></A> +</P> <P> A PO file is made up of many entries, each entry holding the relation between an original untranslated string and its corresponding @@ -123,6 +131,8 @@ All comments, of either kind, are optional. </P> <P> +<A NAME="IDX45"></A> +<A NAME="IDX46"></A> 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 @@ -156,6 +166,7 @@ there are two forms of flags defined: <DT><KBD>fuzzy</KBD> <DD> +<A NAME="IDX47"></A> This flag can be generated by the <CODE>msgmerge</CODE> program or it can be inserted by the translator herself. It shows that the <CODE>msgstr</CODE> string might not be a correct translation (anymore). Only the translator @@ -167,8 +178,10 @@ search only. See section <A HREF="gettext_6.html#SEC45">6.3 Fuzzy Entries</A>. <DT><KBD>c-format</KBD> <DD> +<A NAME="IDX48"></A> <DT><KBD>no-c-format</KBD> <DD> +<A NAME="IDX49"></A> These flags should not be added by a human. Instead only the <CODE>xgettext</CODE> program adds them. In an automated PO file processing system as proposed here the user changes would be thrown away again as @@ -181,6 +194,7 @@ See section <A HREF="gettext_8.html#SEC118">8.1 Invoking the <CODE>msgfmt</CODE </DL> <P> +<A NAME="IDX50"></A> A different kind of entries is used for translations which involve plural forms. @@ -200,6 +214,7 @@ msgstr[N] <VAR>translated-string-case-n</VAR> </PRE> <P> +<A NAME="IDX51"></A> 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 PO mode is unable to take action on those lines. By using the @@ -249,6 +264,7 @@ other character, we just did it this way because it is neater. </P> <P> +<A NAME="IDX52"></A> One should carefully distinguish between end of lines marked as <SAMP>`\n´</SAMP> <EM>inside</EM> quotes, which are part of the represented string, and end of lines in the PO file itself, outside string quotes, @@ -256,6 +272,7 @@ which have no incidence on the represented string. </P> <P> +<A NAME="IDX53"></A> Outside strings, white lines and comments may be used freely. Comments start at the beginning of a line with <SAMP>`#´</SAMP> and extend until the end of the PO file line. Comments written by translators @@ -271,6 +288,8 @@ file is given to <CODE>msgmerge</CODE>. <H2><A NAME="SEC10" HREF="gettext_toc.html#TOC10">2.3 Main PO mode Commands</A></H2> <P> +<A NAME="IDX54"></A> +<A NAME="IDX55"></A> After setting up Emacs with something similar to the lines in section <A HREF="gettext_2.html#SEC8">2.1 Completing GNU <CODE>gettext</CODE> Installation</A>, 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 @@ -302,37 +321,47 @@ in special ways. <DT><KBD>_</KBD> <DD> +<A NAME="IDX56"></A> Undo last modification to the PO file (<CODE>po-undo</CODE>). <DT><KBD>Q</KBD> <DD> +<A NAME="IDX57"></A> Quit processing and save the PO file (<CODE>po-quit</CODE>). <DT><KBD>q</KBD> <DD> +<A NAME="IDX58"></A> Quit processing, possibly after confirmation (<CODE>po-confirm-and-quit</CODE>). <DT><KBD>0</KBD> <DD> +<A NAME="IDX59"></A> Temporary leave the PO file window (<CODE>po-other-window</CODE>). <DT><KBD>?</KBD> <DD> <DT><KBD>h</KBD> <DD> +<A NAME="IDX60"></A> +<A NAME="IDX61"></A> Show help about PO mode (<CODE>po-help</CODE>). <DT><KBD>=</KBD> <DD> +<A NAME="IDX62"></A> Give some PO file statistics (<CODE>po-statistics</CODE>). <DT><KBD>V</KBD> <DD> +<A NAME="IDX63"></A> Batch validate the format of the whole PO file (<CODE>po-validate</CODE>). </DL> <P> +<A NAME="IDX64"></A> +<A NAME="IDX65"></A> The command <KBD>_</KBD> (<CODE>po-undo</CODE>) interfaces to the Emacs <EM>undo</EM> facility. See section `Undoing Changes' in <CITE>The Emacs Editor</CITE>. Each time <KBD>U</KBD> is typed, modifications which the translator did to the PO file are undone a little more. For the purpose of @@ -344,6 +373,10 @@ can undo the edition work quite parsimoniously. </P> <P> +<A NAME="IDX66"></A> +<A NAME="IDX67"></A> +<A NAME="IDX68"></A> +<A NAME="IDX69"></A> The commands <KBD>Q</KBD> (<CODE>po-quit</CODE>) and <KBD>q</KBD> (<CODE>po-confirm-and-quit</CODE>) are used when the translator is done with the PO file. The former is a bit less verbose than the latter. If the file @@ -356,6 +389,8 @@ of an Emacs PO file buffer. Merely killing it through the usual command </P> <P> +<A NAME="IDX70"></A> +<A NAME="IDX71"></A> The command <KBD>0</KBD> (<CODE>po-other-window</CODE>) 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 @@ -369,6 +404,9 @@ PO mode is then recovered. </P> <P> +<A NAME="IDX72"></A> +<A NAME="IDX73"></A> +<A NAME="IDX74"></A> The command <KBD>h</KBD> (<CODE>po-help</CODE>) displays a summary of all available PO mode commands. The translator should then type any character to resume normal PO mode operations. The command <KBD>?</KBD> has the same effect @@ -376,6 +414,8 @@ as <KBD>h</KBD>. </P> <P> +<A NAME="IDX75"></A> +<A NAME="IDX76"></A> The command <KBD>=</KBD> (<CODE>po-statistics</CODE>) 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, @@ -383,6 +423,8 @@ and displays all these numbers. </P> <P> +<A NAME="IDX77"></A> +<A NAME="IDX78"></A> The command <KBD>V</KBD> (<CODE>po-validate</CODE>) launches <CODE>msgfmt</CODE> in checking and verbose mode over the current PO file. This command first offers to save the @@ -393,6 +435,7 @@ as well as all individual entries. </P> <P> +<A NAME="IDX79"></A> The program <CODE>msgfmt</CODE> runs asynchronously with Emacs, so the translator regains control immediately while her PO file is being studied. Error output is collected in the Emacs <SAMP>`*compilation*´</SAMP> buffer, @@ -408,6 +451,7 @@ any PO mode action which would help correcting the error. <H2><A NAME="SEC11" HREF="gettext_toc.html#TOC11">2.4 Entry Positioning</A></H2> <P> +<A NAME="IDX80"></A> 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 @@ -418,6 +462,7 @@ the PO file, this also selects on which entry commands operate. </P> <P> +<A NAME="IDX81"></A> 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 @@ -428,41 +473,51 @@ the others are described in following sections (for a complete list try <DT><KBD>.</KBD> <DD> +<A NAME="IDX82"></A> Redisplay the current entry (<CODE>po-current-entry</CODE>). <DT><KBD>n</KBD> <DD> +<A NAME="IDX83"></A> Select the entry after the current one (<CODE>po-next-entry</CODE>). <DT><KBD>p</KBD> <DD> +<A NAME="IDX84"></A> Select the entry before the current one (<CODE>po-previous-entry</CODE>). <DT><KBD><</KBD> <DD> +<A NAME="IDX85"></A> Select the first entry in the PO file (<CODE>po-first-entry</CODE>). <DT><KBD>></KBD> <DD> +<A NAME="IDX86"></A> Select the last entry in the PO file (<CODE>po-last-entry</CODE>). <DT><KBD>m</KBD> <DD> +<A NAME="IDX87"></A> Record the location of the current entry for later use (<CODE>po-push-location</CODE>). <DT><KBD>r</KBD> <DD> +<A NAME="IDX88"></A> Return to a previously saved entry location (<CODE>po-pop-location</CODE>). <DT><KBD>x</KBD> <DD> +<A NAME="IDX89"></A> Exchange the current entry location with the previously saved one (<CODE>po-exchange-location</CODE>). </DL> <P> +<A NAME="IDX90"></A> +<A NAME="IDX91"></A> 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 @@ -491,6 +546,10 @@ how <EM>others</EM> should do translation. </P> <P> +<A NAME="IDX92"></A> +<A NAME="IDX93"></A> +<A NAME="IDX94"></A> +<A NAME="IDX95"></A> The commands <KBD>n</KBD> (<CODE>po-next-entry</CODE>) and <KBD>p</KBD> (<CODE>po-previous-entry</CODE>) move the cursor the entry following, or preceding, the current one. If <KBD>n</KBD> is given while the @@ -499,6 +558,10 @@ is given while the cursor is on the first entry, no move is done. </P> <P> +<A NAME="IDX96"></A> +<A NAME="IDX97"></A> +<A NAME="IDX98"></A> +<A NAME="IDX99"></A> The commands <KBD><</KBD> (<CODE>po-first-entry</CODE>) and <KBD>></KBD> (<CODE>po-last-entry</CODE>) move the cursor to the first entry, or last entry, of the PO file. When the cursor is located past the last @@ -521,6 +584,10 @@ register for getting back, or else, use the location ring. </P> <P> +<A NAME="IDX100"></A> +<A NAME="IDX101"></A> +<A NAME="IDX102"></A> +<A NAME="IDX103"></A> PO mode offers another approach, by which cursor locations may be saved onto a special stack. The command <KBD>m</KBD> (<CODE>po-push-location</CODE>) merely adds the location of current entry to the stack, pushing @@ -540,6 +607,8 @@ ought to use <KBD>m</KBD> immediately after <KBD>r</KBD>. </P> <P> +<A NAME="IDX104"></A> +<A NAME="IDX105"></A> The command <KBD>x</KBD> (<CODE>po-exchange-location</CODE>) 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 @@ -553,7 +622,10 @@ merely use <KBD>x</KBD> for making the switch. <H2><A NAME="SEC12" HREF="gettext_toc.html#TOC12">2.5 Normalizing Strings in Entries</A></H2> +<P> +<A NAME="IDX106"></A> +</P> <P> 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 @@ -584,10 +656,13 @@ PO file needing a canonical representation, the following PO mode command is available: </P> +<P> +<A NAME="IDX107"></A> <DL COMPACT> <DT><KBD>M-x po-normalize</KBD> <DD> +<A NAME="IDX108"></A> Tidy the whole PO file by making entries more uniform. </DL> @@ -619,6 +694,7 @@ for continued lines. </P> <P> +<A NAME="IDX109"></A> 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. @@ -631,6 +707,7 @@ their PO files in nice ways. </P> <P> +<A NAME="IDX110"></A> Right now, in PO mode, strings are single line or multi-line. A string goes multi-line if and only if it has <EM>embedded</EM> newlines, that is, if it matches <SAMP>`[^\n]\n+[^\n]´</SAMP>. So, we would have: @@ -680,6 +757,6 @@ to be documented in this manual, once these questions settle. </P> <P><HR><P> -Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_1.html">previous</A>, <A HREF="gettext_3.html">next</A>, <A HREF="gettext_16.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. +Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_1.html">previous</A>, <A HREF="gettext_3.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. </BODY> </HTML> |