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

[G. Branden Robinson]

Follow-up Comment #8, bug #55278 (group groff):


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>.




    _______________________________________________________

Reply to this item at:

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

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

signature.asc
Description: PGP signature