gettext: Modifying Comments

1 
1 8.3.10 Modifying Comments
1 -------------------------
1 
1    Any translation work done seriously will raise many linguistic
1 difficulties, for which decisions have to be made, and the choices
1 further documented.  These documents may be saved within the PO file in
1 form of translator comments, which the translator is free to create,
1 delete, or modify at will.  These comments may be useful to herself when
1 she returns to this PO file after a while.
1 
1    Comments not having whitespace after the initial ‘#’, for example,
1 those beginning with ‘#.’ or ‘#:’, are _not_ translator comments, they
1 are exclusively created by other ‘gettext’ tools.  So, the commands
1 below will never alter such system added comments, they are not meant
1 for the translator to modify.  ⇒PO Files.
1 
1    The following commands are somewhat similar to those modifying
1 translations, so the general indications given for those apply here.
1 ⇒Modifying Translations.
1 
1 ‘#’
1      Interactively edit the translator comments (‘po-edit-comment’).
1 
1 ‘K’
1      Save the translator comments on the kill ring, and delete it
1      (‘po-kill-comment’).
1 
1 ‘W’
1      Save the translator comments on the kill ring, without deleting it
1      (‘po-kill-ring-save-comment’).
1 
1 ‘Y’
1      Replace the translator comments, taking the new from the kill ring
1      (‘po-yank-comment’).
1 
1    These commands parallel PO mode commands for modifying the
1 translation strings, and behave much the same way as they do, except
1 that they handle this part of PO file comments meant for translator
1 usage, rather than the translation strings.  So, if the descriptions
1 given below are slightly succinct, it is because the full details have
1 already been given.  ⇒Modifying Translations.
1 
1    The command ‘#’ (‘po-edit-comment’) opens a new Emacs window
1 containing a copy of the translator comments on the current PO file
1 entry.  If there are no such comments, PO mode understands that the
1 translator wants to add a comment to the entry, and she is presented
1 with an empty screen.  Comment marks (‘#’) and the space following them
1 are automatically removed before edition, and reinstated after.  For
1 translator comments pertaining to obsolete entries, the uncommenting and
1 recommenting operations are done twice.  Once in the editing window, the
1 keys ‘C-c C-c’ allow the translator to tell she is finished with editing
1 the comment.  ⇒Subedit, for further details.
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    The command ‘K’ (‘po-kill-comment’) gets rid of all translator
1 comments, while saving those comments on the kill ring.  The command ‘W’
1 (‘po-kill-ring-save-comment’) takes a copy of the translator comments on
1 the kill ring, but leaves them undisturbed in the current entry.  The
1 command ‘Y’ (‘po-yank-comment’) completely replaces the translator
1 comments by a string taken at the front of the kill ring.  When this
1 command is immediately repeated, the comments just inserted are
1 withdrawn, and replaced by other strings taken along the kill ring.
1 
1    On the kill ring, all strings have the same nature.  There is no
1 distinction between _translation_ strings and _translator comments_
1 strings.  So, for example, let’s presume the translator has just
1 finished editing a translation, and wants to create a new translator
1 comment to document why the previous translation was not good, just to
1 remember what was the problem.  Foreseeing that she will do that in her
1 documentation, the translator may want to quote the previous translation
1 in her translator comments.  To do so, she may initialize the translator
1 comments with the previous translation, still at the head of the kill
1 ring.  Because editing already pushed the previous translation on the
1 kill ring, she merely has to type ‘M-w’ prior to ‘#’, and the previous
1 translation will be right there, all ready for being introduced by some
1 explanatory text.
1 
1    On the other hand, presume there are some translator comments already
1 and that the translator wants to add to those comments, instead of
1 wholly replacing them.  Then, she should edit the comment right away
1 with ‘#’.  Once inside the editing window, she can use the regular Emacs
1 commands ‘C-y’ (‘yank’) and ‘M-y’ (‘yank-pop’) to get the previous
1 translation where she likes.
1