bugGNU roff - Bugs: bug #58933, [PATCH] doc/groff.texi,...

 
 

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

Submitter:  Dave <barx>
Submitted:  Mon 10 Aug 2020 09:17:20 PM UTC
   
 
Category:  Core Severity:  3 - Normal
Item Group:  Documentation Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sun 05 Feb 2023 07:27:46 AM UTC, comment #7: 


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.

G. Branden Robinson <gbranden>
Group administrator
Sat 22 Aug 2020 03:52:33 AM UTC, comment #6: 

I had a moment of wavering doubt involving "string comparisons", but I overcame them after writing enough short experiments.  The key conclusion I reached there is that formatting is not the same thing as rendering.

Closing per Dave's observation.


G. Branden Robinson <gbranden>
Group administrator
Wed 19 Aug 2020 09:30:06 PM UTC, comment #5: 

Looks to be fixed in commit 36b5c885 (and I see my patch missed two of the four files that used the less accurate terminology).

Dave <barx>
Group Member
Sun 16 Aug 2020 10:06:56 PM UTC, comment #4: 

Ah.  I only have the November 1992 revision of CSTR #54 (I can't actually find any earlier versions on the web), which calls it a "non-printing, zero-width filler character."  But I think the word "filler" is slightly misleading, so the version without it is definitely better to me.  I have no opinion about the presence or absence of "zero-width."

Dave <barx>
Group Member
Sat 15 Aug 2020 04:50:22 PM UTC, comment #3: 


> It's Peter's term; I'm just a fanboy.  I agree that "zero-width" seems redundant, but maybe he can think of something additional it communicates.


It's the definition used by Ossana and Kernighan in the cstr54, not mine, though they switch it around.  I'm inclined to think zero-width is not redundant, since a non-printing character could have a width.  Zero-width, non-printing clarifies this.  I'd rather risk overstating than leaving room for doubt. I suspect that was O&K's reasoning, too.

Peter Schaffter <PTPi>
Group Member
Sat 15 Aug 2020 12:02:40 AM UTC, comment #2: 

It's Peter's term; I'm just a fanboy.  I agree that "zero-width" seems redundant, but maybe he can think of something additional it communicates.

Dave <barx>
Group Member
Fri 14 Aug 2020 08:45:41 AM UTC, comment #1: 

How about just "non-printing character"?


commit b423e4ce784e7ad0ca1027ba6b57553ed272c74a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Thu Aug 13 21:42:26 2020 +1000

[...]
    * [style] Redefine \& as "non-printing character" in light of recent
      discussion on groff list.  (I find "zero-width" unnecessary; does a
      character that doesn't print take up any space?  Certainly not when it
      isn't an \h or \v escape... ;-) )
[...]


G. Branden Robinson <gbranden>
Group administrator
Mon 10 Aug 2020 09:17:20 PM UTC, original submission:  

On a suggestion from Peter Schaffter (http://lists.gnu.org/archive/html/groff/2020-07/msg00100.html) that \& is best described as "a zero-width, non-printing character" -- itself in reply to my observation that groff's current term, "zero-width space," is a bit misleading, especially as that's the name of a Unicode character (U+200B) equivalent to groff's \: rather than its \& -- I created this patch (originally posted at http://lists.gnu.org/archive/html/groff/2020-08/msg00014.html) to update groff's documentation accordingly.

Both target files have changed since I created the patch, but it still (as of commit 4ce01df7) applies cleanly.

Dave <barx>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #49650:  zwnpc.patch added by barx (3KiB - text/x-patch - update description of \& in doc/groff.texi and man/groff.7.man)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by PTPi (Posted a comment)
  • -email is unavailable- added by barx
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by barx (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2020-08-22 gbranden StatusNeed Info Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2020-08-15 barx Carbon-Copy- Added ptpi
    2020-08-14 gbranden StatusNone Need Info
        Assigned toNone gbranden
    2020-08-10 barx Attached File- Added zwnpc.patch, #49650

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code