gettext: Entry Positioning

1 
1 8.3.3 Entry Positioning
1 -----------------------
1 
1    The cursor in a PO file window is almost always part of an entry.
1 The only exceptions are the special case when the cursor is after the
1 last entry in the file, or when the PO file is empty.  The entry where
1 the cursor is found to be is said to be the current entry.  Many PO mode
1 commands operate on the current entry, so moving the cursor does more
1 than allowing the translator to browse the PO file, this also selects on
1 which entry commands operate.
1 
1    Some PO mode commands alter the position of the cursor in a
1 specialized way.  A few of those special purpose positioning are
1 described here, the others are described in following sections (for a
1 complete list try ‘C-h m’):
1 
1 ‘.’
1      Redisplay the current entry (‘po-current-entry’).
1 
1 ‘n’
1      Select the entry after the current one (‘po-next-entry’).
1 
1 ‘p’
1      Select the entry before the current one (‘po-previous-entry’).
1 
1 ‘<’
1      Select the first entry in the PO file (‘po-first-entry’).
1 
1 ‘>’
1      Select the last entry in the PO file (‘po-last-entry’).
1 
1 ‘m’
1      Record the location of the current entry for later use
1      (‘po-push-location’).
1 
1 ‘r’
1      Return to a previously saved entry location (‘po-pop-location’).
1 
1 ‘x’
1      Exchange the current entry location with the previously saved one
1      (‘po-exchange-location’).
1 
1    Any Emacs command able to reposition the cursor may be used to select
1 the current entry in PO mode, including commands which move by
1 characters, lines, paragraphs, screens or pages, and search commands.
1 However, there is a kind of standard way to display the current entry in
1 PO mode, which usual Emacs commands moving the cursor do not especially
1 try to enforce.  The command ‘.’ (‘po-current-entry’) has the sole
1 purpose of redisplaying the current entry properly, after the current
1 entry has been changed by means external to PO mode, or the Emacs screen
1 otherwise altered.
1 
1    It is yet to be decided if PO mode helps the translator, or otherwise
1 irritates her, by forcing a rigid window disposition while she is doing
1 her work.  We originally had quite precise ideas about how windows
1 should behave, but on the other hand, anyone used to Emacs is often
1 happy to keep full control.  Maybe a fixed window disposition might be
1 offered as a PO mode option that the translator might activate or
1 deactivate at will, so it could be offered on an experimental basis.  If
1 nobody feels a real need for using it, or a compulsion for writing it,
1 we should drop this whole idea.  The incentive for doing it should come
1 from translators rather than programmers, as opinions from an
1 experienced translator are surely more worth to me than opinions from
1 programmers _thinking_ about how _others_ should do translation.
1 
1    The commands ‘n’ (‘po-next-entry’) and ‘p’ (‘po-previous-entry’) move
1 the cursor the entry following, or preceding, the current one.  If ‘n’
1 is given while the cursor is on the last entry of the PO file, or if ‘p’
1 is given while the cursor is on the first entry, no move is done.
1 
1    The commands ‘<’ (‘po-first-entry’) and ‘>’ (‘po-last-entry’) move
1 the cursor to the first entry, or last entry, of the PO file.  When the
1 cursor is located past the last entry in a PO file, most PO mode
1 commands will return an error saying ‘After last entry’.  Moreover, the
1 commands ‘<’ and ‘>’ have the special property of being able to work
1 even when the cursor is not into some PO file entry, and one may use
1 them for nicely correcting this situation.  But even these commands will
1 fail on a truly empty PO file.  There are development plans for the PO
11 mode for it to interactively fill an empty PO file from sources.  ⇒
 Marking.
1 
1    The translator may decide, before working at the translation of a
1 particular entry, that she needs to browse the remainder of the PO file,
1 maybe for finding the terminology or phraseology used in related
1 entries.  She can of course use the standard Emacs idioms for saving the
1 current cursor location in some register, and use that register for
1 getting back, or else, use the location ring.
1 
1    PO mode offers another approach, by which cursor locations may be
1 saved onto a special stack.  The command ‘m’ (‘po-push-location’) merely
1 adds the location of current entry to the stack, pushing the already
1 saved locations under the new one.  The command ‘r’ (‘po-pop-location’)
1 consumes the top stack element and repositions the cursor to the entry
1 associated with that top element.  This position is then lost, for the
1 next ‘r’ will move the cursor to the previously saved location, and so
1 on until no locations remain on the stack.
1 
1    If the translator wants the position to be kept on the location
1 stack, maybe for taking a look at the entry associated with the top
1 element, then go elsewhere with the intent of getting back later, she
1 ought to use ‘m’ immediately after ‘r’.
1 
1    The command ‘x’ (‘po-exchange-location’) simultaneously repositions
1 the cursor to the entry associated with the top element of the stack of
1 saved locations, and replaces that top element with the location of the
1 current entry before the move.  Consequently, repeating the ‘x’ command
1 toggles alternatively between two entries.  For achieving this, the
1 translator will position the cursor on the first entry, use ‘m’, then
1 position to the second entry, and merely use ‘x’ for making the switch.
1