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

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.13-02a9.
    Corresponding source code