bugGNU troff - Bugs: bug #57618, man/groff_char.7.man: page needs...

 
 

bug #57618: man/groff_char.7.man: page needs an overhaul

Submitted by:  Dave <barx>
Submitted on:  Fri 17 Jan 2020 08:20:22 AM UTC  
 
Category:  None Severity:  2 - Minor
Item Group:  Documentation Status:  Confirmed
Privacy:  Public Assigned to:  G. Branden Robinson <gbranden>
Open/Closed:  Open Planned Release:  None

Add a New Comment (Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

( Jump to the original submission)

Sat 18 Jan 2020 03:36:22 PM UTC, comment #6: 

Reconsidering the matter after reading Dave's comment #4, he is probably right that his arguments are stronger than those i brought forward, so i don't insist on keeping the PostScript column.

I don't think that the glyph list should be moved out of the groff_char(7) manual page, though.  As i see it, the whole point of that manual page is providing that glyph list; the rest of the text in that page are merely explanatory notes on the glyph list that would hang in limbo if the list itself were moved elsewhere.

Also, i'm not sure the grops(1) manual needs a list of glyph names.  The grops(1) manual explains how the grops utility works in general and individual glyphs are somewhat tangential to that topic.  Also, glyph naming appears to depend on the individual font (even though it seems everybody encourages using standard names for glyphs whenever possible).  So maybe pointing to something like https://github.com/adobe-type-tools/agl-aglfn/blob/master/aglfn.txt moght be more useful than maintaining our own copy?  I'm not sure, though.  Also, this may be drifting off-topic from what this ticket is about.

Ingo Schwarze <schwarze>
Project Member
Sat 18 Jan 2020 04:16:54 AM UTC, comment #5: 

Other things being equal, I lean toward getting rid of the PostScript column or, more precisely, moving it to the grops(1) page.  (I'd have gropdf(1) just direct the reader to grops(1) for the glyph list with PostScript names.  Now's the time to tell me if/how PDF glyph names are incompatible with, or extend, PostScript names.)

The main thing stopping me at this point is the DRY principle.  The groff glyph list should probably maintained external to both pages and inlined into each, with columns appropriate to the page.

But that would mean that groff_char.7.man and grops.1.man need to become .in files, and bleah.

A bit of tedium.  But not insuperable.

G. Branden Robinson <gbranden>
Project MemberIn charge of this item.
Fri 17 Jan 2020 09:12:49 PM UTC, comment #4: 

I concede the good points made on the usefulness of 80-column limits and the uselessness of the "sic"s.  But I must confess I don't find either of these points particularly compelling:

comment #3:

> I consider the PostScript column useful for two reasons: it
> provides a nice reminder that while almost every character can
> be expressed in terms of Unicode, not every system of glyphs
> is a subset of Unicode nor necessarily organized in a strictly
> numeric manner.  Also, PostScript plays a special role in the
> history of roff, and some aspects of the roff character system -
> like the distinction of \- and \(mi - can be better understood
> when considering PostScript output than when considering Unicode.


The first reason, especially, seems more philosophical than practical in the context of someone merely trying to use the language -- and also redundant, considering roff's own character names are largely neither numeric nor Unicode-derived.  The second point carries a bit more weight, but -- again, as a practical matter to users in 2020 and beyond, who only need to create documents and for whom the origin of certain roff-isms is merely a tangent -- probably not enough to justify the column's retention.

Additionally, the man page itself does nothing to explain why the column is there or what a user could do with its information, the likeliest outcome of which -- for readers who don't gloss over the column entirely -- is to make them wonder, "What am I missing here?"

I'm not opposed to the PostScript column, just not sure I see its need in the modern roff ecosystem, especially if its presence requires other contortions to keep tables within 80 TTY columns.  Further down the page, for example, just about every entry in the Notes column of the Brackets table spans two lines, while many could easily fit on one (and look much nicer) if the PostScript column went away.

Dave <barx>
Fri 17 Jan 2020 01:46:44 PM UTC, comment #3: 

Eliminating the "sic"s was just fine, i think.  When a manual page quotes a syntax element, users should assume that there is no typo.  If a name is really too badly misleading, causing a risk of users misusing the feature, than a mere "sic" is not enough, but a warning needs to be given in a complete, easily understandable sentence - see the last two paragraphs of the DESCRIPTION of https://man.openbsd.org/man3/SSL_CTX_use_certificate.3 (regarding SSL_CTX_check_private_key(3)) for a drastic example.  In the case at hand, there is no risk because users are unlikely to type in the PostScript glyph name.  And even if they do so and get the spelling wrong because they don't want any seabirds in their document, there won't be any dire consequences.  Manual pages should remain concise, focussing on their own topic, and refrain from picking apart unrelated weaknesses in other software.

I consider the PostScript column useful for two reasons: it provides a nice reminder that while almost every character can be expressed in terms of Unicode, not every system of glyphs is a subset of Unicode nor necessarily organized in a strictly numeric manner.  Also, PostScript plays a special role in the history of roff, and some aspects of the roff character system - like the distinction of \- and \(mi - can be better understood when considering PostScript output than when considering Unicode.

As a minor detail, i agree that a description as "left-pointing guillemet" would be better than "left guillemet".

Branden, your todo list looks good to me, so please do use this ticket for that purpose.

Regarding table width, you can shorten "Output" to "Out" and the column width to 3n, and you can reduce inter-column spacing from 3 to 1.  That probably isn't sufficient for all lines, but for most.  Maybe some Notes can be made more concise, but in cases of possible doubt, i'd prioritize precision over nice layout.

Also note how mandoc(1) deals with lines of excessive length (showing an extract from the groff to mandoc diff here, compressing whitespace such that it becomes intelligible in this web interface):

- i \[.i] dotlessi u0131 i without a dot (Turkish)
+ i \[.i] dotlessi u0131 i without a dot
+                        (Turkish)

I.e. mandoc puts multiple text lines into single table cells when needed, making sure that it stays inside the page width specified by the user (or the default of 78).

I think the 80 column limit is still very relevant.  It is still very widespread in coding styles, so many programmers use 80-column virtual terminals (and that's an important audience for groff).  Also, the markup of practically all manual pages i'm aware of is optimized such that it looks good in 80-column terminals.   Finally, some argue that shorter lines are easier to follow when reading; consider printed newspapers, for example, so optimizing for something like 200-character lines may not be a bright idea regardless of the century.

Ingo Schwarze <schwarze>
Project Member
Fri 17 Jan 2020 09:51:09 AM UTC, comment #2: 

comment #1:

> I already got rid of the 4 "sic"s.


Well.  Serves me right for not doing a "git pull" before submitting this.

I'm not sure eliminating the "sic"s entirely is the right answer, though: PostScript does use the wrong term, and the man page should let readers know that this wrong term is not a typo on the man page.

A more interesting question is whether the PostScript column adds any value at all.  Even roff code targeting -Tps output would very rarely use a PostScript name for a glyph--perhaps rarely enough that it's inappropriate to have it in a quick-reference guide for groff characters.

> But the page still has much that ails it, as you note.


I don't recall noting any such thing...but sure, I'll take credit for it!

> There is a theory that the [sic] was not for the guillemot/met spelling,
> but due to the problematic terminology of "left" and "right", because
> these glyphs are supposed to mirror-reflect when used in RTL languages.


This was my brief conjecture (I don't know that it rises to the level of a theory) in bug #57546's discussion, but Werner, who originally added the "sic"s, quickly squelched it by clarifying his intended meaning.

> So I guess "forward" (in the direction of text flow) and
> "backward" are about the only terms we can use.


...except, as Werner also points out in that thread, even some languages that have the same text-flow direction use the guillemets in opposite senses.  "left-pointing" and "right-pointing" seem the only truly semantic-neutral descriptors.

Dave <barx>
Fri 17 Jan 2020 09:08:30 AM UTC, comment #1: 

commit 9fd6d7b45d9bb19c9bc3348cbe703c64a662b020
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Thu Jan 16 17:14:49 2020 +1100

    groff_char(7): Fix typos in glyph descriptions.

    ...and a bogus "sic".  A "guillemet" is in fact a kind of quotation
    mark.  Adobe got it wrong with "guillemot", which is a seabird.

I already got rid of the 4 "sic"s.

But the page still has much that ails it, as you note.

  • The stuff in the first paragraph about "(N/A)" for unavailable glyphs is a lie, as far as I can tell.
  • As you note, the tables are often too wide.  It would be nice to get them fitting on an 80-column terminal.  This often means getting them to fit on a U.S. letter page when typeset, too, so it's a good norm to observe.
  • Way too much emphasis on Latin-1.  We use preconv now.  IMO groff input should be pure ASCII plus groff escapes, but preconv gives us more flexibility than that.
  • In fact I'd nuke the Latin-1 section altogether.  It's an old, uninteresting encoding, and people had switched away to ISO 8859-15 even before they went to full-on UTF-8, because they needed the Euro sign.
  • Lots of Bernd-isms in this page, like repeatedly putting noun phrases in italics.

I'd have fixed this page long ago if it didn't require so much work.

But fixing the irritating typos was a start.

There is a theory that the [sic] was not for the guillemot/met spelling, but due to the problematic terminology of "left" and "right", because these glyphs are supposed to mirror-reflect when used in RTL languages.  So I guess "forward" (in the direction of text flow) and "backward" are about the only terms we can use.

But does groff even support RTL languages at all?  As far as I know it does not, and this left/right is not worth fixing, in my view, until and unless it does.

I am therefore, instead of closing this bug, adapting it to my own foul purposes.  The laundry list of things I think it needs is above.

Comments are welcome on my proposed actions.

G. Branden Robinson <gbranden>
Project MemberIn charge of this item.
Fri 17 Jan 2020 08:20:22 AM UTC, original submission:  

groff_char(1) has "[sic]" in four places: twice in the latin1 table and twice in the Quotes table.  In both tables, the "[sic]" is in the Notes column, but bug #57546 comment #4 clarifies that it's intended to apply to the PostScript column.  Thus its present placement obscures its meaning.

For TTY output, the latin1 table already runs to 89 columns, which is more than is ideal.  But only about a dozen of its 94 rows exceeds the 80-column mark, so it still looks mostly OK in an 80-column window.

Moving the "[sic]" from the Notes column to the PostScript column, where its meaning is much clearer, pushes the table to 95 columns, and more than doubles the number of lines that overflow an 80-column window (with most of these in the top quarter of the table, making them especially noticeable).

So, net result of this change: clearer semantics, uglier presentation.

The Quotes table currently stands at exactly 80 columns, and expands to 86 with the same edit.  Not as bad, but still suboptimal.

Still, hardly anyone's display is limited to 80 columns anymore (or, it's on a pocket-sized screen and limited to much less than 80 columns), so maybe that arbitrary constraint is no longer important.

Or maybe someone will think of a clever way to improve the semantic clarity that doesn't result in widening the whole table.

Dave <barx>

 

(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 schwarze (Posted a comment)
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by barx (Submitted the item)
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

     

     

    Follow 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2020-01-17 schwarze Severity3 - Normal => 2 - Minor
    2020-01-17 gbranden StatusNone => Confirmed
        Assigned toNone => gbranden
        Summaryman/groff_char.7.man: meaning of "[sic]" is unclear => man/groff_char.7.man: page needs an overhaul

    Back to the top


    Powered by Savane 3.5