[pkg-lynx-maint] Bug#1037353: lynx.1: a few formatting fixes for the manual

[G. Branden Robinson]

Hi Thomas,

At 2023-06-14T17:49:04-0400, Thomas Dickey wrote:
> On Mon, Jun 12, 2023 at 01:56:56AM +0000, Bjarni Ingi Gislason wrote:
> > Output from "mandoc -T lint lynx.1"
> > mandoc: lynx.1:27:2: WARNING: missing date, using "": TH
> > mandoc: lynx.1:109:2: WARNING: unknown font, skipping request: ft C			
> > mandoc: lynx.1:317:2: WARNING: unknown font, skipping request: ft C			
> > mandoc: lynx.1:366:2: WARNING: unknown font, skipping request: ft C			
> > mandoc: lynx.1:831:2: WARNING: unknown font, skipping request: ft C			
> > mandoc: lynx.1:838:2: WARNING: unknown font, skipping request: ft C			
> > mandoc: lynx.1:1131:2: WARNING: unknown font, skipping request: ft C			
> 
> That seems to be harmless for nroff, but mainly is for troff (and
> groff) to select a fixed-pitch font for PDFs and PostScript.  I'll see
> if this is at least no worse than the plain "C".

groff 1.23.0 warns about that font name too.  Here's one place the issue
was explored (and remedied).

https://sourceforge.net/p/docutils/patches/205/

> Solaris 10 appears to have "CO" for "Courier" (troff), while an AIX
> that I can access uses "CR".  But on those systems, I'm not actually
> using troff :-)

As far as I can tell, font names simply were not standardized, even by
common practice.  Each troff vendor came up with their own set of names,
I would guess inspired by whatever PostScript fonts they paid to license
from relevant foundries, and aliases may have been set up on an ad hoc
basis if/as problems with document rendering arose.

> I've been using "C" quite a while, and hadn't noticed a problem with
> the indicated usage (i.e., generating PDFs, etc).

Selecting a nonexistent font is a no-op, so it's unlikely to ruin
a document's formatting.  Proportional fonts generally set with more
horizontal compactness constant-width ones, so lines written in the
expectation of, say, Courier are unlikely to overrun when set in Times.

To detect a problem, you'd have to know that a constant-width face was
expected there, and man page styling conventions were (are?) seldom
consistent enough that you'd notice this unless you were a page's
author, or an editor of a collection.

> > #######
> > 
> > Increase size of ~ (tilde) to make it more visible
> > with "troff" by using character \(ti.
> 
> That appears to be groff-specific.

Historically, the troff semantics of ~ are that it's a high-flown
character that will compose well with alphabetic glyphs when overstruck
with them.  I'm attaching a screenshot of Table I from a scan of the
CSTR #54 1976 document, Joseph Ossanna's "Nroff/Troff User's Manual".  A
tilde glyph did not exist in the Times faces, but appeared in the
"Special Mathematical Font" that Bell Labs commissioned.  One of the
purposes of that font was to get full coverage of the ASCII character
set, which typographers in those days did not respect as a necessary
basis for a font's glyph repertoire.

However, it is true that there was only variety of tilde available to
troff back then, so there was no need for a `\(ti` special character,
and none was defined.

Enter Kernighan's device-independent troff circa 1980.  An output device
could use any font names it wanted, and any special character names it
wanted.

As fonts' glyph repertoires grew, this freedom saw some exercise.
Eventually the arrival of a larger, lower tilde character necessitated
the invention of a name to refer to the "full" or "spacing" tilde as
depicted at U+007E in Unicode 2.0 and later.[1]

So, for example, while Documenter's Workbench 3.3 troff, one of several
lines of descent from Kernighan troff, does not define a `ti` special
character, its descendant Heirloom Doctools troff _does_.  And mandoc(1)
recognizes it as well.

I wouldn't expect any System V troff to do so.  But strings can be
defined to work around that problem just as they can for typographer's
(and programmers' neutral) quotation marks.

> > an.tmac:lynx.1:27: style: .TH missing third argument; suggest document modification date in ISO 8601 format (YYYY-MM-DD)
> > an.tmac:lynx.1:27: style: .TH missing fourth argument; suggest package/project name and version (e.g., "lynx ...")
> 
> maybe - there are pros/cons (the version number is in the manpage,
> and that indirectly gives an accurate date).  If I did put a date,
> it would be the modification date for _that_ file.

That appears to be a best practice, if not quite a common one, and it is
what groff_man_style(7) recommends.

     .TH topic section [footer‐middle [footer‐inside [header‐middle]]]
[...]
            By convention, footer‐middle is the date of the most recent
            modification to the man page source document, and footer‐
            inside is the name and version or release of the project
            providing it.

Regards,
Branden

[1] I don't say "Unicode [1.0]" because the standard supported ambiguity
    at U+007E in its first version.  But not afterward.

    Contrast:
    https://www.unicode.org/versions/Unicode1.0.0/CodeCharts1.pdf
    (p. 127, PDF page 3)

    with:
    https://www.unicode.org/versions/Unicode2.0.0/CodeCharts1.pdf
    (p. 7-6, PDF page 1).
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://alioth-lists.debian.net/pipermail/pkg-lynx-maint/attachments/20240117/e8f0f48a/attachment.sig>