diff options
| author | Bruno Haible <bruno@clisp.org> | 2001-04-19 18:37:49 +0000 |
|---|---|---|
| committer | Bruno Haible <bruno@clisp.org> | 2001-04-19 18:37:49 +0000 |
| commit | 41ae7394123b8b0b13eb37ff1e9ed325374bbeba (patch) | |
| tree | 264af71280c09f69da43c6ad6ced7ba6633af09d /doc/gettext_2.html | |
| parent | 6ae7c1b1ba9f4f3aa1d78f121bc7ded6692d5f46 (diff) | |
| download | external_gettext-41ae7394123b8b0b13eb37ff1e9ed325374bbeba.zip external_gettext-41ae7394123b8b0b13eb37ff1e9ed325374bbeba.tar.gz external_gettext-41ae7394123b8b0b13eb37ff1e9ed325374bbeba.tar.bz2 | |
Automatically generated from gettext.texi.
Diffstat (limited to 'doc/gettext_2.html')
| -rw-r--r-- | doc/gettext_2.html | 685 |
1 files changed, 685 insertions, 0 deletions
diff --git a/doc/gettext_2.html b/doc/gettext_2.html new file mode 100644 index 0000000..fcf1a05 --- /dev/null +++ b/doc/gettext_2.html @@ -0,0 +1,685 @@ +<HTML> +<HEAD> +<!-- This HTML file has been created by texi2html 1.51 + from gettext.texi on 19 April 2001 --> + +<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_14.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> +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> +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[tx]?\\'\\|\\.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>, <TT>`.pot'</TT> or <TT>`.pox'</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[tx]?\\'\\|\\.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 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 <STRONG>entry</STRONG> 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> +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> +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> +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#SEC25">6.3 Fuzzy Entries</A>. + +<DT><KBD>c-format</KBD> +<DD> +<DT><KBD>no-c-format</KBD> +<DD> +These flags should not be added by a human. Instead only the +<CODE>xgettext</CODE> program adds them. In an automatized 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_7.html#SEC35">7.1 Invoking the <CODE>msgfmt</CODE> Program</A>. + +</DL> + +<P> +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> +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 imbedded 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> +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> +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> +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#SEC24">6.2 Translated Entries</A>, +3 fuzzy entries (see section <A HREF="gettext_6.html#SEC25">6.3 Fuzzy Entries</A>), 10 untranslated entries +(see section <A HREF="gettext_6.html#SEC26">6.4 Untranslated Entries</A>) and 2 obsolete entries (see section <A HREF="gettext_6.html#SEC27">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>U</KBD> +<DD> +Undo last modification to the PO file. + +<DT><KBD>Q</KBD> +<DD> +Quit processing and save the PO file. + +<DT><KBD>q</KBD> +<DD> +Quit processing, possibly after confirmation. + +<DT><KBD>O</KBD> +<DD> +Temporary leave the PO file window. + +<DT><KBD>?</KBD> +<DD> +<DT><KBD>h</KBD> +<DD> +Show help about PO mode. + +<DT><KBD>=</KBD> +<DD> +Give some PO file statistics. + +<DT><KBD>V</KBD> +<DD> +Batch validate the format of the whole PO file. + +</DL> + +<P> +The command <KBD>U</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> +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 some untranslated message remains in the +PO file and, if yes, 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> +The command <KBD>O</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> +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> +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> +The command <KBD>V</KBD> (<CODE>po-validate</CODE>) launches <CODE>msgfmt</CODE> in 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> +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> +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> +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. + +</P> +<DL COMPACT> + +<DT><KBD>.</KBD> +<DD> +Redisplay the current entry. + +<DT><KBD>n</KBD> +<DD> +<DT><KBD>n</KBD> +<DD> +Select the entry after the current one. + +<DT><KBD>p</KBD> +<DD> +<DT><KBD>p</KBD> +<DD> +Select the entry before the current one. + +<DT><KBD><</KBD> +<DD> +Select the first entry in the PO file. + +<DT><KBD>></KBD> +<DD> +Select the last entry in the PO file. + +<DT><KBD>m</KBD> +<DD> +Record the location of the current entry for later use. + +<DT><KBD>l</KBD> +<DD> +Return to a previously saved entry location. + +<DT><KBD>x</KBD> +<DD> +Exchange the current entry location with the previously saved one. + +</DL> + +<P> +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> +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> +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#SEC16">3.3 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> +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> +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> +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 backslahsed 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> +<DL COMPACT> + +<DT><KBD>M-x po-normalize</KBD> +<DD> +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> +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> +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_14.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. +</BODY> +</HTML> |