gettext: Subedit

1 
1 8.3.11 Details of Sub Edition
1 -----------------------------
1 
1    The PO subedit minor mode has a few peculiarities worth being
1 described in fuller detail.  It installs a few commands over the usual
1 editing set of Emacs, which are described below.
1 
1 ‘C-c C-c’
1      Complete edition (‘po-subedit-exit’).
1 
1 ‘C-c C-k’
1      Abort edition (‘po-subedit-abort’).
1 
1 ‘C-c C-a’
1      Consult auxiliary PO files (‘po-subedit-cycle-auxiliary’).
1 
1    The window’s contents represents a translation for a given message,
1 or a translator comment.  The translator may modify this window to her
1 heart’s content.  Once this is done, the command ‘C-c C-c’
1 (‘po-subedit-exit’) may be used to return the edited translation into
1 the PO file, replacing the original translation, even if it moved out of
1 sight or if buffers were switched.
1 
1    If the translator becomes unsatisfied with her translation or
1 comment, to the extent she prefers keeping what was existent prior to
1 the ‘<RET>’ or ‘#’ command, she may use the command ‘C-c C-k’
1 (‘po-subedit-abort’) to merely get rid of edition, while preserving the
1 original translation or comment.  Another way would be for her to exit
1 normally with ‘C-c C-c’, then type ‘U’ once for undoing the whole effect
1 of last edition.
1 
1    The command ‘C-c C-a’ (‘po-subedit-cycle-auxiliary’) allows for
1 glancing through translations already achieved in other languages,
1 directly while editing the current translation.  This may be quite
1 convenient when the translator is fluent at many languages, but of
1 course, only makes sense when such completed auxiliary PO files are
1 already available to her (⇒Auxiliary).
1 
1    Functions found on ‘po-subedit-mode-hook’, if any, are executed after
1 the string has been inserted in the edit buffer.
1 
1    While editing her translation, the translator should pay attention to
1 not inserting unwanted ‘<RET>’ (newline) characters at the end of the
1 translated string if those are not meant to be there, or to removing
1 such characters when they are required.  Since these characters are not
1 visible in the editing buffer, they are easily introduced by mistake.
1 To help her, ‘<RET>’ automatically puts the character ‘<’ at the end of
1 the string being edited, but this ‘<’ is not really part of the string.
1 On exiting the editing window with ‘C-c C-c’, PO mode automatically
1 removes such ‘<’ and all whitespace added after it.  If the translator
1 adds characters after the terminating ‘<’, it looses its delimiting
1 property and integrally becomes part of the string.  If she removes the
1 delimiting ‘<’, then the edited string is taken _as is_, with all
1 trailing newlines, even if invisible.  Also, if the translated string
1 ought to end itself with a genuine ‘<’, then the delimiting ‘<’ may not
1 be removed; so the string should appear, in the editing window, as
1 ending with two ‘<’ in a row.
1 
1    When a translation (or a comment) is being edited, the translator may
1 move the cursor back into the PO file buffer and freely move to other
1 entries, browsing at will.  If, with an edition pending, the translator
1 wanders in the PO file buffer, she may decide to start modifying another
1 entry.  Each entry being edited has its own subedit buffer.  It is
1 possible to simultaneously edit the translation _and_ the comment of a
1 single entry, or to edit entries in different PO files, all at once.
1 Typing ‘<RET>’ on a field already being edited merely resumes that
1 particular edit.  Yet, the translator should better be comfortable at
1 handling many Emacs windows!
1 
1    Pending subedits may be completed or aborted in any order, regardless
1 of how or when they were started.  When many subedits are pending and
1 the translator asks for quitting the PO file (with the ‘q’ command),
1 subedits are automatically resumed one at a time, so she may decide for
1 each of them.
1