bugGNU roff - Bugs: bug #55278, src/devices/grotty/grotty.1.man,...

 
 

bug #55278: src/devices/grotty/grotty.1.man, doc/groff.texi updates

Submitter:  Dave <barx>
Submitted:  Tue 25 Dec 2018 12:26:00 AM 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 15 Sep 2024 08:04:16 AM UTC, comment #8: 


commit c105b1725cc928e225d23237f3cf1a7a5239d5ba
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Thu Jun 27 22:14:50 2019 +1000

grotty.1.man: Make editorial fixes.
* Add "terminal" keyword to summary line.
* Reorganize synopsis.
  + Distinguish modes of operation.
    - Only SGR mode (the default) accepts -i or -r.
    - Only legacy mode accepts -[bBuU].
    - Note --help and --version modes.
* Recast introductory paragraph; because groff does its own pipeline
  management, people tend to think of "the output of *roff" not as the
  device-independent form but of device-specific output (PDF, TTY, ...).
* Add man page cross-references, particularly to groff(1) itself.
* Hyphenate attributive phrases (e.g., "EBCDIC-based hosts").
* Note the historically-driven practice of rendering (and speaking of)
  underlined text as "italics" in nroff/TTY contexts.
  + Also call out the relatively new grotty -i option which gives you
    something closer to true italics on xterm(1).
* Set pathnames/filenames in italics, not bold.
* Remove false claim about the default color scheme for terminals being
  black text on a white background "in most cases".
  + I don't know who wrote that, but I suspect a Macintosh or Sun
    workstation partisan.  Whoever they were, they ignored a huge number
    of monochrome hardware terminals by that were manufactured after
    1980 (when green and amber phosphors grew popular) and by about 1987
    the DEC VT340 was supporting color escapes (the VT420 and VT520
    reverted to monochrome, and the VT525 (~1993) brought color back
    again).  The rise of the IBM 5150 ("PC") -compatible microcomputer
    and the default white-on-black color scheme of MS-DOS/PC-DOS
    contributed to user expectations of similar terminal color schemes
    by 1990.  By the mid-1990s when people started to hear of the Linux
    kernel, official maintenance of the X Window System by the Open
    Group was moribund, and the xterm client in the sample
    implementation was _still_ monochrome as late as X11R6.5.1 (August
    2000), but the Linux console (white-on-black, on PC VGA hardware)
    wasn't, and a thousand clueless flowers bloomed across the land as
    system integrators rushed to bring refugees from Microsoft Windows
    the joy of colorized GNU ls(1) output in a GUI terminal window.  For
    the sake of "brand differentiation", these vendors chose "attractive
    color schemes" for "the desktop", and imposed this scheme on the
    terminal emulator without regard for the color palette, often
    resulting in unreadable foreground colors against the "pleasant"
    default background.  But venture capitalists and IPO-hungry day
    traders cared little for usability issues, being concerned more with
    who was going to do the biggest cannonball into the swimming pool.
    Had they bothered to look, they'd have noticed the similarity
    between these initiatives and the ill-fated COSE/CDE at the tail end
    of the Unix Wars only a few years previous.  Upon these
    lavishly-funded but dubiously-engineered foundations the dot-com
    bubble burst, and billions of dollars of notional wealth disappeared
    overnight.  After that we had terrorist attacks and wars in the
    Middle East, and it's all thanks to people who don't support their
    claims about what "most" terminals use as a default color scheme.
* Structure a somewhat miscellaneous compendium of information into
  subsections:
  + SGR support in pagers
  + Legacy output format
  + Device control commands
  + Device description files
* Comment out paragraph that I think might better belong elsewhere.
  Feedback welcome.
* Add internal cross-references.
* Carefully distinguish *roff escape sequences from SGR escape sequences
  in narrative.  There's no escaping the terminology, so be clear about
  context in each case.
* Note that horizontal and vertical lines are drawn with Unicode
  box-drawing characters on the utf8 device.
* Don't set a metasyntactical ellipsis in bold.  It's not a literal.
* Document supported long options.
* Don't talk about an option being "active"; talk about whether it's
  specified--that's what the user has control over.
* Quote output device names instead of shouting them in bold (except
  when part of option syntax).
* Comment out claim that cp1047 device files are only shipped on EBCDIC
  platforms.  The build no longer seems to practice this restriction?
* Style: ensure two empty requests between paragraphs.

commit 69c400e082f2b11c8b79a4a6224f174ee8a28d53
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Fri Jun 12 18:27:39 2020 +1000

    Update descriptions of groff -a and grotty -c.

    * doc/groff.texi (Groff Options): Remove editorial comment about '-a'
      option being "useless".  It isn't.  Update example for contemporary
      systems (like Debian) and to reflect the fact that the GNU troff(1)
      man page needs to be preprocessed with tbl(1).

      (Invoking grotty): Recast discussion of -c option, importing much
      language from grotty(1) page rewrite from a year ago.  Add program
      index entries for col, more, and ul.  Fix transposition error in ISO
      document number.

    * src/devices/grotty/grotty.1.man (Description/Legacy output format):
      Make slight wording changes prompted by content of parallel section in
      Texinfo manual.

    * src/roff/groff/groff.1.man (Options/-a): Parallelize with first
      sentence of corresponding material in Texinfo manual.

    * src/roff/troff/troff.1.man (Options/-a): Parallelize with Texinfo
      manual.

    Fixes the rest of <https://savannah.gnu.org/bugs/index.php?55278>.


G. Branden Robinson <gbranden>
Group administrator
Sat 13 Jun 2020 02:35:45 AM UTC, comment #7: 

I see your point on some of those. The stuff about how spacing isn't preserved might be worth a mention.

But I think there's value in not overdocumenting what can be easily gleaned by looking at the output; e.g., the line "<beginning of page>" is essentially self-documenting.

The output is called an "ASCII approximation," which already communicates that it won't reflect its input exactly.  And documenting exactly how special characters are output today means locking in that output forevermore; leaving them unspecified gives the groff maintainers of 2040 flexibility to change them if the need arises.  (Hopefully no one is using -a output in production, minimizing back-compatibility concerns if it changes.  But it strengthens that position if the only documented result is that that output is an approximation, with no promises about just how things are approximated.)

Dave <barx>
Group Member
Fri 12 Jun 2020 11:16:58 PM UTC, comment #6: 

comment #5:

> comment #4:
> I'll leave that in your capable hands, since I'm not quite sure what you mean.  I look at -a output as a low-res human-readable preview of typeset output, so how it "should" be read depends on the reader's needs.  But you seem to have something specific in mind.


Okay, some disorganized observations.

  • Horizontal motions seem to be reduced to just one space (a space node internally, I think).
  • Multiple adjacent space nodes, however, are not coalesced.
  • Vertical motions seem to be ignored.
  • Hyphens inserted by groff are rendered as "<hy>".
  • Other special characters are rendered as their names in less-than/greater-than signs.
  • Less-than and greater-than signs in the input are not escaped or quoted.
  • To finish with the most obvious item, "<beginning of page>" is emitted at each page transition, including what I have seen called the "pseudo-page-transition" at the beginning of input.



$ cat EXPERIMENTS/groff-a-example.roff
mother-in-law
pneumonoultramicroscopicsilicovolcanoconiosis
pneumonoultramicroscopicsilicovolcanoconiosis
<foo><bar>
foo\h'16n'bar
baz\h'8n'\h'8n'qux
.br
\[sc] section sign
.br
em\[em]dash
.br
en\[en]dash
.br
P. J. Soles was in the movie \fIAnimal House\fP.
Now let's have some vertical space.
.sp 3v
clich\[e aa]
page break
.bp
Here's a new page.
$ groff -Tutf8 -a <EXPERIMENTS/groff-a-example.roff
<beginning of page>
mother-in-law pneumonoultramicroscopicsilicovolcanoconiosis pneu<hy>
monoultramicroscopicsilicovolcanoconiosis <foo><bar>
foo bar baz  qux
<sc> section sign
em<em>dash
en<en>dash
P. J. Soles was in the movie Animal House. Now let's have some
vertical space.
clich<'e> page break
<beginning of page>
Here's a new page.


Also, there is a factual error in the above.  I confused Animal House with Stripes.

G. Branden Robinson <gbranden>
Group administrator
Fri 12 Jun 2020 09:36:04 PM UTC, comment #5: 

comment #4:

> A separate bug could/should be filed for describing how the troff -a output should actually be read.


I'll leave that in your capable hands, since I'm not quite sure what you mean.  I look at -a output as a low-res human-readable preview of typeset output, so how it "should" be read depends on the reader's needs.  But you seem to have something specific in mind.

Dave <barx>
Group Member
Fri 12 Jun 2020 08:41:57 AM UTC, comment #4: 

Fixed in 69c400e082f2b11c8b79a4a6224f174ee8a28d53.

A separate bug could/should be filed for describing how the troff -a output should actually be read.  Now that I've seen inside src/roff/troff/*.cpp I have a notion, but the subject sure could use some explanation for a general audience.

G. Branden Robinson <gbranden>
Group administrator
Thu 04 Jun 2020 06:59:00 AM UTC, comment #3: 

comment #2:

> Point 1 fixed in commit c105b1725cc928e225d23237f3cf1a7a5239d5bavax.


Not sure where the extra characters on the end came from.  The correct commit is commit c105b1725cc928e225d23237f3cf1a7a5239d5ba.

Dave <barx>
Group Member
Thu 19 Dec 2019 10:46:26 AM UTC, comment #2: 

Point 1 fixed in commit c105b1725cc928e225d23237f3cf1a7a5239d5bavax.

Side note on point 3: According to http://en.wikipedia.org/wiki/Caret_navigation, "caret" can be a synonym for "cursor" in the context of a text editor or similar UI, but that's not what this sentence is referring to.

Dave <barx>
Group Member
Wed 02 Jan 2019 03:11:21 AM UTC, comment #1: 

Side note on point 1: There is also the question of what "supporting" this actually means.  One Android terminal app, for instance (specifically, JuiceSSH), renders text delineated with these escape sequences in reverse video.  This is arguably uglier than underlining, but the app does recognize the escape sequences and gamely tries to distinguish affected text.  So this app arguably supports it, even if the results aren't attractive.

Dave <barx>
Group Member
Tue 25 Dec 2018 12:26:00 AM UTC, original submission:  

Three proposed documentation changes submitted for discussion.

1. src/devices/grotty/grotty.1.man

Part of the documentation for -i says "most terminals (including xterm) don't support this."

No doubt this was true when it was added (Feb 2002, commit e30e96cf2e61dc8dced25f426b7615573916eee4), but today it's not true of at least xterm or MacOS's Terminal.  Is it true of enough modern terminals to reduce it down to "many terminals" or "some terminals"?  Or should it just be removed altogether?

2. doc/groff.texi

Part of the documentation for -a says "this option is rather useless today since graphic output devices are available virtually everywhere."  This seems a needless bit of editorializing -- and of questionable accuracy: see threads starting at

http://lists.gnu.org/archive/html/groff/2018-02/msg00028.html
http://lists.gnu.org/archive/html/groff/2018-02/msg00042.html

For one, this sentence implies that -a output has no use besides as a poor substitute for graphical output.  And the ubiquity of graphic-output devices doesn't mean you're working in a session that has easy access to one (e.g., over ssh).

The simplest fix is to axe this sentence.  A better fix might be to give the user ideas on how the option enables tasks (e.g., allowing easy diffs of typeset output; grepping for widows; automated regression testing; probably more) that are difficult or impossible with PostScript and PDF output.

3. doc/groff.texi

Underlining by overstrike is described as "printing an underline character, then moving the caret back one character position, and printing the actual character at the same position as the underline character."

I'm betting "moving the caret back" was intended to say "moving the cursor back."  If so, probably shortening it to "moving back" is just as clear (and arguably more accurate, as there's no cursor involved).  Note that the prior wording of this phrase (changed in 58e63bf373fbf31765e62a0e05fab686ab395898) was exactly that.

Dave <barx>
Group Member

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -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 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2020-06-12 gbranden StatusNone Fixed
        Assigned toNone gbranden
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0

    Back to the top

    Powered by Savane 3.15-e6e5.
    Corresponding source code