gettext: C Sources Context

1 
1 8.3.12 C Sources Context
1 ------------------------
1 
1    PO mode is particularly powerful when used with PO files created
1 through GNU ‘gettext’ utilities, as those utilities insert special
1 comments in the PO files they generate.  Some of these special comments
1 relate the PO file entry to exactly where the untranslated string
1 appears in the program sources.
1 
1    When the translator gets to an untranslated entry, she is fairly
1 often faced with an original string which is not as informative as it
1 normally should be, being succinct, cryptic, or otherwise ambiguous.
1 Before choosing how to translate the string, she needs to understand
1 better what the string really means and how tight the translation has to
1 be.  Most of the time, when problems arise, the only way left to make
1 her judgment is looking at the true program sources from where this
1 string originated, searching for surrounding comments the programmer
1 might have put in there, and looking around for helping clues of _any_
1 kind.
1 
1    Surely, when looking at program sources, the translator will receive
1 more help if she is a fluent programmer.  However, even if she is not
1 versed in programming and feels a little lost in C code, the translator
1 should not be shy at taking a look, once in a while.  It is most
1 probable that she will still be able to find some of the hints she
1 needs.  She will learn quickly to not feel uncomfortable in program
1 code, paying more attention to programmer’s comments, variable and
1 function names (if he dared choosing them well), and overall
1 organization, than to the program code itself.
1 
1    The following commands are meant to help the translator at getting
1 program source context for a PO file entry.
1 
1 ‘s’
1      Resume the display of a program source context, or cycle through
1      them (‘po-cycle-source-reference’).
1 
1 ‘M-s’
1      Display of a program source context selected by menu
1      (‘po-select-source-reference’).
1 
1 ‘S’
1      Add a directory to the search path for source files
1      (‘po-consider-source-path’).
1 
1 ‘M-S’
1      Delete a directory from the search path for source files
1      (‘po-ignore-source-path’).
1 
1    The commands ‘s’ (‘po-cycle-source-reference’) and ‘M-s’
1 (‘po-select-source-reference’) both open another window displaying some
1 source program file, and already positioned in such a way that it shows
1 an actual use of the string to be translated.  By doing so, the command
1 gives source program context for the string.  But if the entry has no
1 source context references, or if all references are unresolved along the
1 search path for program sources, then the command diagnoses this as an
1 error.
1 
1    Even if ‘s’ (or ‘M-s’) opens a new window, the cursor stays in the PO
1 file window.  If the translator really wants to get into the program
1 source window, she ought to do it explicitly, maybe by using command
1 ‘O’.
1 
1    When ‘s’ is typed for the first time, or for a PO file entry which is
1 different of the last one used for getting source context, then the
1 command reacts by giving the first context available for this entry, if
1 any.  If some context has already been recently displayed for the
1 current PO file entry, and the translator wandered off to do other
1 things, typing ‘s’ again will merely resume, in another window, the
1 context last displayed.  In particular, if the translator moved the
1 cursor away from the context in the source file, the command will bring
1 the cursor back to the context.  By using ‘s’ many times in a row, with
1 no other commands intervening, PO mode will cycle to the next available
1 contexts for this particular entry, getting back to the first context
1 once the last has been shown.
1 
1    The command ‘M-s’ behaves differently.  Instead of cycling through
1 references, it lets the translator choose a particular reference among
1 many, and displays that reference.  It is best used with completion, if
1 the translator types ‘<TAB>’ immediately after ‘M-s’, in response to the
1 question, she will be offered a menu of all possible references, as a
1 reminder of which are the acceptable answers.  This command is useful
1 only where there are really many contexts available for a single string
1 to translate.
1 
1    Program source files are usually found relative to where the PO file
1 stands.  As a special provision, when this fails, the file is also
1 looked for, but relative to the directory immediately above it.  Those
1 two cases take proper care of most PO files.  However, it might happen
1 that a PO file has been moved, or is edited in a different place than
1 its normal location.  When this happens, the translator should tell PO
1 mode in which directory normally sits the genuine PO file.  Many such
1 directories may be specified, and all together, they constitute what is
1 called the "search path" for program sources.  The command ‘S’
1 (‘po-consider-source-path’) is used to interactively enter a new
1 directory at the front of the search path, and the command ‘M-S’
1 (‘po-ignore-source-path’) is used to select, with completion, one of the
1 directories she does not want anymore on the search path.
1