Bug#1037353: lynx.1: a few formatting fixes for the manual
Hi Thomas, At 2023-06-14T17:49:04-0400, Thomas Dickey wrote: > On Mon, Jun 12, 2023 at 01:56:56AM +, 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 (-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
Bug#1037353: lynx.1: a few formatting fixes for the manual
On Wed, Jun 14, 2023 at 05:49:04PM -0400, Thomas Dickey wrote: > On Mon, Jun 12, 2023 at 01:56:56AM +, Bjarni Ingi Gislason wrote: > > Package: lynx > > Version: 2.9.0dev.12-1 > > Severity: minor > > Tags: patch > > > > Dear Maintainer, > > > > here are some fixes. > > > > Input file is lynx.1 > > > > 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". > > 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 :-) > > I've been using "C" quite a while, and hadn't noticed a problem with > the indicated usage (i.e., generating PDFs, etc). > The C font is aliased with the CR font in some tmac files in "groff", so it actually does not need a change. Also, in the "man.local" file, it can be changed for nroff to "R" avoiding a warning. > > ### > > > > Increase size of ~ (tilde) to make it more visible > > with "troff" by using character \(ti. > > That appears to be groff-specific. > Possible, so a better transformation is a size change, "\s+3~\s-3". > > 264:If none is specified, the default value is ~/.lynx_cookies > > 265:for most systems, but ~/cookies for MS-DOS. > > > [...]
Bug#1037353: lynx.1: a few formatting fixes for the manual
On Mon, Jun 12, 2023 at 01:56:56AM +, Bjarni Ingi Gislason wrote: > Package: lynx > Version: 2.9.0dev.12-1 > Severity: minor > Tags: patch > > Dear Maintainer, > > here are some fixes. > > Input file is lynx.1 > > 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". 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 :-) I've been using "C" quite a while, and hadn't noticed a problem with the indicated usage (i.e., generating PDFs, etc). > ### > > Increase size of ~ (tilde) to make it more visible > with "troff" by using character \(ti. That appears to be groff-specific. > 264:If none is specified, the default value is ~/.lynx_cookies > 265:for most systems, but ~/cookies for MS-DOS. > > # > > The following issue is not in the patch: > > an.tmac:lynx.1:27: style: .TH missing third argument; suggest document > modification date in ISO 8601 format (-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. > # > > --- lynx.12023-06-05 16:20:24.0 + > +++ lynx.1.new2023-06-12 01:32:27.0 + > @@ -15,7 +15,7 @@ > .ie n .in +4 > .el.in +2 > .nf > -.ft C\" Courier > +.ft CR \" Courier > .. > .de NE > .fi > @@ -261,8 +261,8 @@ Sets the connection timeout, where N is > .TP > .B \-cookie_file\fR=\fIFILENAME > specifies a file to use to read cookies. > -If none is specified, the default value is ~/.lynx_cookies > -for most systems, but ~/cookies for MS-DOS. > +If none is specified, the default value is \(ti/.lynx_cookies > +for most systems, but \(ti/cookies for MS-DOS. > .TP > .B \-cookie_save_file\fR=\fIFILENAME > specifies a file to use to store cookies. > > > -- System Information: > Debian Release: 12.0 > APT prefers testing > APT policy: (500, 'testing') > Architecture: amd64 (x86_64) > > Kernel: Linux 6.1.27-1 (SMP w/2 CPU threads; PREEMPT) > Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), > LANGUAGE not set > Shell: /bin/sh linked to /usr/bin/dash > Init: sysvinit (via /sbin/init) > > Versions of packages lynx depends on: > ii libbsd0 0.11.7-2 > ii libbz2-1.01.0.8-5+b1 > ii libc6 2.36-9 > ii libgnutls30 3.7.9-2 > ii libidn2-0 2.3.3-1+b1 > ii libncursesw6 6.4-4 > ii libtinfo6 6.4-4 > ii lynx-common 2.9.0dev.12-1 > ii zlib1g1:1.2.13.dfsg-1 > > Versions of packages lynx recommends: > ii mailcap 3.70+nmu1 > > lynx suggests no packages. > > -- no debconf information > -- Thomas E. Dickey https://invisible-island.net signature.asc Description: PGP signature
Bug#1037353: lynx.1: a few formatting fixes for the manual
Package: lynx Version: 2.9.0dev.12-1 Severity: minor Tags: patch Dear Maintainer, here are some fixes. Input file is lynx.1 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 ### Increase size of ~ (tilde) to make it more visible with "troff" by using character \(ti. 264:If none is specified, the default value is ~/.lynx_cookies 265:for most systems, but ~/cookies for MS-DOS. # The following issue is not in the patch: an.tmac:lynx.1:27: style: .TH missing third argument; suggest document modification date in ISO 8601 format (-MM-DD) an.tmac:lynx.1:27: style: .TH missing fourth argument; suggest package/project name and version (e.g., "lynx ...") # --- lynx.1 2023-06-05 16:20:24.0 + +++ lynx.1.new 2023-06-12 01:32:27.0 + @@ -15,7 +15,7 @@ .ie n .in +4 .el.in +2 .nf -.ft C \" Courier +.ft CR \" Courier .. .de NE .fi @@ -261,8 +261,8 @@ Sets the connection timeout, where N is .TP .B \-cookie_file\fR=\fIFILENAME specifies a file to use to read cookies. -If none is specified, the default value is ~/.lynx_cookies -for most systems, but ~/cookies for MS-DOS. +If none is specified, the default value is \(ti/.lynx_cookies +for most systems, but \(ti/cookies for MS-DOS. .TP .B \-cookie_save_file\fR=\fIFILENAME specifies a file to use to store cookies. -- System Information: Debian Release: 12.0 APT prefers testing APT policy: (500, 'testing') Architecture: amd64 (x86_64) Kernel: Linux 6.1.27-1 (SMP w/2 CPU threads; PREEMPT) Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set Shell: /bin/sh linked to /usr/bin/dash Init: sysvinit (via /sbin/init) Versions of packages lynx depends on: ii libbsd0 0.11.7-2 ii libbz2-1.01.0.8-5+b1 ii libc6 2.36-9 ii libgnutls30 3.7.9-2 ii libidn2-0 2.3.3-1+b1 ii libncursesw6 6.4-4 ii libtinfo6 6.4-4 ii lynx-common 2.9.0dev.12-1 ii zlib1g1:1.2.13.dfsg-1 Versions of packages lynx recommends: ii mailcap 3.70+nmu1 lynx suggests no packages. -- no debconf information
