[bug #58933] [PATCH] doc/groff.texi, man/groff.7.man: clarify description of \&

[G. Branden Robinson]

Follow-up Comment #7, bug #58933 (project groff):


commit 36b5c8852af098e6f06dbe2ab8e452a45b43d315
Author:     G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Aug 15 22:08:01 2020 +1000
Commit:     G. Branden Robinson <g.branden.robinson@gmail.com>
CommitDate: Sat Aug 15 22:54:03 2020 +1000

    documentation: Re-christen 'ESCAPE_AMPERSAND'.
    
    Recent discussions on the groff mailing list and in the Savannah bug
    tracker have made me realize that our terminology for this escape
    sequence is poor.  Rename it consistently to give users a more precise
    idea of its function.
    
    s/zero[- ]width space character/non-printing input break/
    
    Justification:
    
    First, the case for the prosecution:
    
    * Can something that does not print have a width?  Note that elewhere,
      in documentation of \z, things that do print are also described as
      having zero width, probably for mnemonic purposes ("z").
      "Non-advancing" might be a better term there.  In any case, the
      "width" of this escape is not a salient feature.
    * It is hard to argue that it is a "space".  It differs from space
      behavior in both input and output.  A major use of it is in fact to
      _cancel_ the effect of nearby space, as in suppressing end-of-sentence
      detection, so it is more like an anti-space in that regard.  It is
      therefore not like a space on input, and not like one on output
      either; it does not change the printing position, and there is nothing
      to break or not break when filling.
    * It is also hard to argue that it is a character.  It certainly an
      escape; it produces neither a space node nor a glyph node internally.
      Do we call \R or \s "characters"?  No, they simply change the state of
      the engine in different ways, as does \&.
    
    Now, the case for the defense (of my replacement wording):
    
    * Everybody agrees that whatever this is, it doesn't print.  Say that.
    * Nothing about the harmlessness of this escape sequence to output that
      is suggestion by "zero-width" is not implied even more strongly by
      "non-printing".
    * As noted in the final point in the previous section, the purpose of
      this escape is to change the state of the parser.  It produces nothing
      on its own; it simply moves the interpreting automaton to a different
      region of its semantic space.  Like a function that takes void and
      returns void, you invoke it _only_ for its side effects.
    * Consequently it acts like a jump, branch, or "break" in the
      interpreter of input.  The first two are too comp sci for the general
      reader.  The last can be usefully understood by the reader by analogy
      to the other types of "break" in groff; the usual course of events is
      being interrupted.  To avoid confusion, I advocate being scrupulous
      about including the word "input" before "break".
    
    * doc/groff.texi (Requests): Rename.  Update conceptual index entries;
      retain old name (with an appended "[sic]") to aid readers accustomed
      to it.
      (Ligatures and kerning): Update conceptual index entries.  Supply
      context ("effect on kerning").
      (Drawing requests): Update conceptual index entries.  Supply context
      ("effect on '\l'").
    
    * man/groff.7.man (Description): Rename in macro-advice-writing
      shorthand.
      (Escape Sequences/Escape short reference): Rename.  Also hyphenate
      attribute phrase "zero-width" in descriptions of \| and \^.  Also
      update possibly miseadling source comment.
    * tmac/groff_man.7.man.in (Description/Command synopsis macros [style]:
      Rename.
      (Description/Portability) [style]: Rename.
    * tmac/groff_mdoc.7.man (TROFF IDIOSYNCRASIES/Macro Usage): Rename.
      (TROFF IDIOSYNCRASIES/Other Possible Pitfalls): Rename.


Also see bug #62816.


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?58933>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/