DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

(gettext.info.gz) C Sources Context

Info Catalog (gettext.info.gz) Subedit (gettext.info.gz) PO Mode (gettext.info.gz) Auxiliary
 
 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.
 
Info Catalog (gettext.info.gz) Subedit (gettext.info.gz) PO Mode (gettext.info.gz) Auxiliary
automatically generated byinfo2html