diff options
| author | Bruno Haible <bruno@clisp.org> | 2003-02-14 17:04:54 +0000 |
|---|---|---|
| committer | Bruno Haible <bruno@clisp.org> | 2009-06-23 12:10:02 +0200 |
| commit | da7cbb13cbc776e498167f34ce1dbb6504b442e3 (patch) | |
| tree | ef082e1e6c37fadf09d10d994df07bcb7ac15933 /doc/gettext_2.html | |
| parent | 859de64dc4f5defce5980f9b5904d1692eb70ad0 (diff) | |
| download | external_gettext-da7cbb13cbc776e498167f34ce1dbb6504b442e3.zip external_gettext-da7cbb13cbc776e498167f34ce1dbb6504b442e3.tar.gz external_gettext-da7cbb13cbc776e498167f34ce1dbb6504b442e3.tar.bz2 | |
Obsolete.
Diffstat (limited to 'doc/gettext_2.html')
| -rw-r--r-- | doc/gettext_2.html | 788 |
1 files changed, 0 insertions, 788 deletions
diff --git a/doc/gettext_2.html b/doc/gettext_2.html deleted file mode 100644 index bb19ddf..0000000 --- a/doc/gettext_2.html +++ /dev/null @@ -1,788 +0,0 @@ -<HTML> -<HEAD> -<!-- This HTML file has been created by texi2html 1.52a - from gettext.texi on 5 November 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_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. -<P><HR><P> - - -<H1><A NAME="SEC7" HREF="gettext_toc.html#TOC7">2 PO Files and PO Mode Basics</A></H1> - -<P> -The GNU <CODE>gettext</CODE> toolset helps programmers and translators -at producing, updating and using translation files, mainly those -PO files which are textual, editable files. This chapter stresses -the format of PO files, and contains a PO mode starter. PO mode -description is spread throughout this manual instead of being concentrated -in one place. Here we present only the basics of PO mode. - -</P> - - - -<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 -<CODE>msgmerge</CODE>, 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. - -</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: - -</P> - -<PRE> -(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) -</PRE> - -<P> -Later, whenever you edit some <TT>`.po´</TT> -file, or any file having the string <SAMP>`.po.´</SAMP> within its name, -Emacs loads <TT>`po-mode.elc´</TT> (or <TT>`po-mode.el´</TT>) as needed, and -automatically activates PO mode commands for the associated buffer. -The string <EM>PO</EM> 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. - -</P> -<P> -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: - -</P> - -<PRE> -(modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\." - 'po-find-file-coding-system) -(autoload 'po-find-file-coding-system "po-mode") -</PRE> - -<P> -to your <TT>`.emacs´</TT> file. If, with this, you still see boxes instead -of international characters, try a different font set (via Shift Mouse -button 1). - -</P> - - -<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 -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 <EM>entry</EM> has the following schematic -structure: - -</P> - -<PRE> -<VAR>white-space</VAR> -# <VAR>translator-comments</VAR> -#. <VAR>automatic-comments</VAR> -#: <VAR>reference</VAR>... -#, <VAR>flag</VAR>... -msgid <VAR>untranslated-string</VAR> -msgstr <VAR>translated-string</VAR> -</PRE> - -<P> -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. - -</P> -<P> -A simple entry can look like this: - -</P> - -<PRE> -#: lib/error.c:116 -msgid "Unknown system error" -msgstr "Error desconegut del sistema" -</PRE> - -<P> -Entries begin with some optional white space. Usually, when generated -through GNU <CODE>gettext</CODE> tools, there is exactly one blank line -between entries. Then comments follow, on lines all starting with the -character <KBD>#</KBD>. There are two kinds of comments: those which have -some white space immediately following the <KBD>#</KBD>, which comments are -created and maintained exclusively by the translator, and those which -have some non-white character just after the <KBD>#</KBD>, which comments -are created and maintained automatically by GNU <CODE>gettext</CODE> tools. -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 -string is introduced by the keyword <CODE>msgid</CODE>, and the translation, -by <CODE>msgstr</CODE>. The two strings, untranslated and translated, -are quoted in various ways in the PO file, using <KBD>"</KBD> -delimiters and <KBD>\</KBD> 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. - -</P> -<P> -The <CODE>msgid</CODE> strings, as well as automatic comments, are produced -and managed by other GNU <CODE>gettext</CODE> 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 <CODE>msgstr</CODE> string, as well as translator -comments, are really meant for the translator, and PO mode gives her -the full control she needs. - -</P> -<P> -The comment lines beginning with <KBD>#,</KBD> are special because they are -not completely ignored by the programs as comments generally are. The -comma separated list of <VAR>flag</VAR>s is used by the <CODE>msgfmt</CODE> -program to give the user some better diagnostic messages. Currently -there are two forms of flags defined: - -</P> -<DL COMPACT> - -<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 -can judge if the translation requires further modification, or is -acceptable as is. Once satisfied with the translation, she then removes -this <KBD>fuzzy</KBD> attribute. The <CODE>msgmerge</CODE> program inserts this -when it combined the <CODE>msgid</CODE> and <CODE>msgstr</CODE> entries after fuzzy -search only. See section <A HREF="gettext_6.html#SEC47">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 -soon as the <CODE>xgettext</CODE> program generates a new template file. - -In case the <KBD>c-format</KBD> flag is given for a string the <CODE>msgfmt</CODE> -does some more tests to check to validity of the translation. -See section <A HREF="gettext_8.html#SEC120">8.1 Invoking the <CODE>msgfmt</CODE> Program</A>. - -</DL> - -<P> -<A NAME="IDX50"></A> -<A NAME="IDX51"></A> -A different kind of entries is used for translations which involve -plural forms. - -</P> - -<PRE> -<VAR>white-space</VAR> -# <VAR>translator-comments</VAR> -#. <VAR>automatic-comments</VAR> -#: <VAR>reference</VAR>... -#, <VAR>flag</VAR>... -msgid <VAR>untranslated-string-singular</VAR> -msgid_plural <VAR>untranslated-string-plural</VAR> -msgstr[0] <VAR>translated-string-case-0</VAR> -... -msgstr[N] <VAR>translated-string-case-n</VAR> -</PRE> - -<P> -Such an entry can look like this: - -</P> - -<PRE> -#: 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" -</PRE> - -<P> -<A NAME="IDX52"></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 -PO mode function <KBD>M-x po-normalize</KBD>, the translator may get -rid of those spurious lines. See section <A HREF="gettext_2.html#SEC12">2.5 Normalizing Strings in Entries</A>. - -</P> -<P> -The remainder of this section may be safely skipped by those using -PO mode, 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 -not having Emacs handy should carefully continue reading on. - -</P> -<P> -Each of <VAR>untranslated-string</VAR> and <VAR>translated-string</VAR> 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: - -</P> - -<PRE> -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" -</PRE> - -<P> -In this example, the empty string is used on the first line, to -allow better alignment of the <KBD>H</KBD> from the word <SAMP>`Here´</SAMP> -over the <KBD>f</KBD> from the word <SAMP>`for´</SAMP>. In this example, the -<CODE>msgid</CODE> 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 <CODE>msgid</CODE> 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 <SAMP>`Here´</SAMP> was -promoted on the first line, right after <CODE>msgid</CODE>.<A NAME="DOCF2" HREF="gettext_foot.html#FOOT2">(2)</A> It was not really necessary -either to switch between the two last quoted strings immediately after -the newline <SAMP>`\n´</SAMP>, the switch could have occurred after <EM>any</EM> -other character, we just did it this way because it is neater. - -</P> -<P> -<A NAME="IDX53"></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, -which have no incidence on the represented string. - -</P> -<P> -<A NAME="IDX54"></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 -should have the initial <SAMP>`#´</SAMP> immediately followed by some white -space. If the <SAMP>`#´</SAMP> 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 <CODE>msgmerge</CODE>. - -</P> - - -<H2><A NAME="SEC10" HREF="gettext_toc.html#TOC10">2.3 Main PO mode Commands</A></H2> - -<P> -<A NAME="IDX55"></A> -<A NAME="IDX56"></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 -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 <CODE>po-mode-hook</CODE>, -if any, will be executed. - -</P> -<P> -When PO mode is active in a window, the letters <SAMP>`PO´</SAMP> 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 <SAMP>`132t+3f+10u+2o´</SAMP> would tell the translator that the -PO mode contains 132 translated entries (see section <A HREF="gettext_6.html#SEC46">6.2 Translated Entries</A>, -3 fuzzy entries (see section <A HREF="gettext_6.html#SEC47">6.3 Fuzzy Entries</A>), 10 untranslated entries -(see section <A HREF="gettext_6.html#SEC48">6.4 Untranslated Entries</A>) and 2 obsolete entries (see section <A HREF="gettext_6.html#SEC49">6.5 Obsolete Entries</A>). 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 -<SAMP>`145t´</SAMP> for the counters. - -</P> -<P> -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. - -</P> -<DL COMPACT> - -<DT><KBD>_</KBD> -<DD> -<A NAME="IDX57"></A> -Undo last modification to the PO file (<CODE>po-undo</CODE>). - -<DT><KBD>Q</KBD> -<DD> -<A NAME="IDX58"></A> -Quit processing and save the PO file (<CODE>po-quit</CODE>). - -<DT><KBD>q</KBD> -<DD> -<A NAME="IDX59"></A> -Quit processing, possibly after confirmation (<CODE>po-confirm-and-quit</CODE>). - -<DT><KBD>0</KBD> -<DD> -<A NAME="IDX60"></A> -Temporary leave the PO file window (<CODE>po-other-window</CODE>). - -<DT><KBD>?</KBD> -<DD> -<DT><KBD>h</KBD> -<DD> -<A NAME="IDX61"></A> -<A NAME="IDX62"></A> -Show help about PO mode (<CODE>po-help</CODE>). - -<DT><KBD>=</KBD> -<DD> -<A NAME="IDX63"></A> -Give some PO file statistics (<CODE>po-statistics</CODE>). - -<DT><KBD>V</KBD> -<DD> -<A NAME="IDX64"></A> -Batch validate the format of the whole PO file (<CODE>po-validate</CODE>). - -</DL> - -<P> -<A NAME="IDX65"></A> -<A NAME="IDX66"></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 -undoing, each PO mode command is atomic. This is especially true for -the <KBD><KBD>RET</KBD></KBD> 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. - -</P> -<P> -<A NAME="IDX67"></A> -<A NAME="IDX68"></A> -<A NAME="IDX69"></A> -<A NAME="IDX70"></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 -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 -<KBD>C-x k</KBD> (<CODE>kill-buffer</CODE>) is not the tidiest way to proceed. - -</P> -<P> -<A NAME="IDX71"></A> -<A NAME="IDX72"></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 -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 <EM>he</EM>) 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. - -</P> -<P> -<A NAME="IDX73"></A> -<A NAME="IDX74"></A> -<A NAME="IDX75"></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 -as <KBD>h</KBD>. - -</P> -<P> -<A NAME="IDX76"></A> -<A NAME="IDX77"></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, -and displays all these numbers. - -</P> -<P> -<A NAME="IDX78"></A> -<A NAME="IDX79"></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 -current PO file on disk. The <CODE>msgfmt</CODE> tool, from GNU <CODE>gettext</CODE>, -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. - -</P> -<P> -<A NAME="IDX80"></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, -displayed in another window. The regular Emacs command <KBD>C-x`</KBD> -(<CODE>next-error</CODE>), 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. - -</P> - - -<H2><A NAME="SEC11" HREF="gettext_toc.html#TOC11">2.4 Entry Positioning</A></H2> - -<P> -<A NAME="IDX81"></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 -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. - -</P> -<P> -<A NAME="IDX82"></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 -<KBD>C-h m</KBD>): - -</P> -<DL COMPACT> - -<DT><KBD>.</KBD> -<DD> -<A NAME="IDX83"></A> -Redisplay the current entry (<CODE>po-current-entry</CODE>). - -<DT><KBD>n</KBD> -<DD> -<A NAME="IDX84"></A> -Select the entry after the current one (<CODE>po-next-entry</CODE>). - -<DT><KBD>p</KBD> -<DD> -<A NAME="IDX85"></A> -Select the entry before the current one (<CODE>po-previous-entry</CODE>). - -<DT><KBD><</KBD> -<DD> -<A NAME="IDX86"></A> -Select the first entry in the PO file (<CODE>po-first-entry</CODE>). - -<DT><KBD>></KBD> -<DD> -<A NAME="IDX87"></A> -Select the last entry in the PO file (<CODE>po-last-entry</CODE>). - -<DT><KBD>m</KBD> -<DD> -<A NAME="IDX88"></A> -Record the location of the current entry for later use -(<CODE>po-push-location</CODE>). - -<DT><KBD>r</KBD> -<DD> -<A NAME="IDX89"></A> -Return to a previously saved entry location (<CODE>po-pop-location</CODE>). - -<DT><KBD>x</KBD> -<DD> -<A NAME="IDX90"></A> -Exchange the current entry location with the previously saved one -(<CODE>po-exchange-location</CODE>). - -</DL> - -<P> -<A NAME="IDX91"></A> -<A NAME="IDX92"></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 -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 <KBD>.</KBD> -(<CODE>po-current-entry</CODE>) 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. - -</P> -<P> -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 <EM>thinking</EM> about -how <EM>others</EM> should do translation. - -</P> -<P> -<A NAME="IDX93"></A> -<A NAME="IDX94"></A> -<A NAME="IDX95"></A> -<A NAME="IDX96"></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 -cursor is on the last entry of the PO file, or if <KBD>p</KBD> -is given while the cursor is on the first entry, no move is done. - -</P> -<P> -<A NAME="IDX97"></A> -<A NAME="IDX98"></A> -<A NAME="IDX99"></A> -<A NAME="IDX100"></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 -entry in a PO file, most PO mode commands will return an error saying -<SAMP>`After last entry´</SAMP>. Moreover, the commands <KBD><</KBD> and <KBD>></KBD> -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. See section <A HREF="gettext_3.html#SEC17">3.4 Marking Translatable Strings</A>. - -</P> -<P> -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. - -</P> -<P> -<A NAME="IDX101"></A> -<A NAME="IDX102"></A> -<A NAME="IDX103"></A> -<A NAME="IDX104"></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 -the already saved locations under the new one. The command -<KBD>r</KBD> (<CODE>po-pop-location</CODE>) 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 <KBD>r</KBD> will move the cursor -to the previously saved location, and so on until no locations remain -on the stack. - -</P> -<P> -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 <KBD>m</KBD> immediately after <KBD>r</KBD>. - -</P> -<P> -<A NAME="IDX105"></A> -<A NAME="IDX106"></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 -location of the current entry before the move. Consequently, repeating -the <KBD>x</KBD> command toggles alternatively between two entries. -For achieving this, the translator will position the cursor on the -first entry, use <KBD>m</KBD>, then position to the second entry, and -merely use <KBD>x</KBD> for making the switch. - -</P> - - -<H2><A NAME="SEC12" HREF="gettext_toc.html#TOC12">2.5 Normalizing Strings in Entries</A></H2> -<P> -<A NAME="IDX107"></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 -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 <CODE>msgid</CODE> 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. - -</P> -<P> -A conventional representation of strings in a PO file is currently -under discussion, and PO mode experiments with a canonical representation. -Having both <CODE>xgettext</CODE> 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 <CODE>xgettext</CODE> from GNU <CODE>gettext</CODE>. An explicit -PO mode normalization should then be only necessary for PO files -imported from elsewhere, or for when the convention itself evolves. - -</P> -<P> -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: - -</P> -<P> -<A NAME="IDX108"></A> -<DL COMPACT> - -<DT><KBD>M-x po-normalize</KBD> -<DD> -<A NAME="IDX109"></A> -Tidy the whole PO file by making entries more uniform. - -</DL> - -<P> -The special command <KBD>M-x po-normalize</KBD>, 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 <CODE>msgid</CODE> string lookup for some other PO mode commands. - -</P> -<P> -<KBD>M-x po-normalize</KBD> presently makes three passes over the entries. -The first implements heuristics for converting PO files for GNU -<CODE>gettext</CODE> 0.6 and earlier, in which <CODE>msgid</CODE> and <CODE>msgstr</CODE> -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 <CODE>msgid</CODE> and <CODE>msgstr</CODE> strings respectively. They also -clean out those trailing backslashes used by XView's <CODE>msgfmt</CODE> -for continued lines. - -</P> -<P> -<A NAME="IDX110"></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. -It is easy to make suggested adjustments at a later time, as the -normalizing command and eventually, other GNU <CODE>gettext</CODE> 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. - -</P> -<P> -<A NAME="IDX111"></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: - -</P> - -<PRE> -msgstr "\n\nHello, world!\n\n\n" -</PRE> - -<P> -but, replacing the space by a newline, this becomes: - -</P> - -<PRE> -msgstr "" -"\n" -"\n" -"Hello,\n" -"world!\n" -"\n" -"\n" -</PRE> - -<P> -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 <VAR>n</VAR> -> 1, the <VAR>n</VAR>-1'th last newlines would go together on a separate -string), so making the previous example appear: - -</P> - -<PRE> -msgstr "\n\n" -"Hello,\n" -"world!\n" -"\n\n" -</PRE> - -<P> -There are a few yet undecided little points about string normalization, -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_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. -</BODY> -</HTML> |