Re: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

Re: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 5973 bytes --]

Hi Colin, Ingo, and Branden,

On 11/17/22 01:06, G. Branden Robinson wrote:
 >> I used temporarily the term [sub]chapter to see how it fits.
 > I think the adoption of the term (sub)chapter has a potential benefit in
 > that it removes a terminological collision with (sub)sections as
 > subdivisions of individual man pages (man: SH, SS; mdoc: Sh, Ss).
 >
 > If this terminological reform is adopted, I think it should be done
 > across all of (1) Linux man-pages, (2) groff, (3) mandoc, and (4)
 > man-db.  If we can't speak with one voice on this then I think it's
 > better not to undertake that reform at all, to avoid frustrating the
 > discoverabilty of man pages.
 >
 > Possibly the biggest barrier to this is the mnemonic and documentation
 > of the man(1) '-s' option.  In man-db man, '-C' and '-c' are both
 > already in use.

That can be documented as a historical detail in the documentation of the option 
itself, which makes sense, as to avoid programmers that have heard of sections 
to try to grep section and find nothing.

 >
 > Probably a good idea to loop Colin Watson in on this proposal of yours,
 > which is strictly speaking severable from the below.

Yes, especially since part of the discussion is in linux-man@ (I'm not sure if 
he reads it; I think not) and not in groff@ (which he reads, AFAIK).  So, I'll 
merge the 2 discussions about this by forwarding the 2 most interesting other 
emails below.

So, does it make sense to all of us to start using the term chapter for 
divisions of the man-pages single volume, so that the manual pages in Linux are 
organized from now on in chapters 1 to 9 instead of sections 1 to 9?

Cheers,

Alex


-------- Forwarded Message --------
Subject: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: 
.TH 5th field shouldn't be empty)
Date: Wed, 16 Nov 2022 23:46:13 +0100
From: Alejandro Colomar <alx.manpages@gmail.com>
To: G. Branden Robinson <g.branden.robinson@gmail.com>
CC: groff@gnu.org, Michael Haardt <michael@moria.de>, Andries Brouwer 
<Andries.Brouwer@cwi.nl>, Michael Kerrisk <mtk.manpages@gmail.com>, Douglas 
McIlroy <douglas.mcilroy@dartmouth.edu>

Hi Branden!

On 9/7/22 00:13, Alejandro Colomar wrote:
 >>> I've seen sporadically references to the numbers as chapters, probably
 >>> from when the manual was a proper book, but that term seems to have
 >>> fallen in use.
 >>
 >> I don't recall seeing this.  While not my preference, I would regard it
 >> as an excusable innovation in response to an unhelpful overlap in prior
 >> usage.
 >
 > I don't remember where I've seen this.  I seem to recall it, but maybe it's just
 > a glitch in my memory.  It would certainly simplify nomenclature.  If we come up
 > with a good term for subsections such as 3head, I might start using the term
 > colloquially.  Does subchapter sound good to you?
 >


I've got good news for you.  I started writing intro(3type), after I got the 
first contribution of a new page to chapter 3type of the manual.

And while doing it, I found a place where the term 'chapter' is used.  It's very 
likely that there's where I saw it the other time.  It's in a comment in the 
intro(3) page, which seems to be there since there's git history.

The author of the page seems to be Michael Haardt; his last commit to the 
man-pages is from 2015, so I guess his email is still active.  Maybe he can 
comment.  I also CCed aeb and mtk, as they maintained the pages before me and 
may know if that term was in use at the time.


Cheers,

Alex






-------- Forwarded Message --------
Subject: Re: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: 
rst2man: .TH 5th field shouldn't be empty)
Date: Thu, 17 Nov 2022 00:47:43 +0100
From: Alejandro Colomar <alx.manpages@gmail.com>
To: Andries E. Brouwer <aeb@cwi.nl>
CC: G. Branden Robinson <g.branden.robinson@gmail.com>, groff@gnu.org, Michael 
Haardt <michael@moria.de>, Andries Brouwer <Andries.Brouwer@cwi.nl>, Michael 
Kerrisk <mtk.manpages@gmail.com>, Douglas McIlroy <douglas.mcilroy@dartmouth.edu>

Hi Andries!

On 11/17/22 00:40, Andries E. Brouwer wrote:
 >
 >> On 9/7/22 00:13, Alejandro Colomar wrote:
 >>>>> I've seen sporadically references to the numbers as chapters, probably
 >>>>> from when the manual was a proper book, but that term seems to have
 >>>>> fallen in use.
 >
 > Unix Programmer's Manual (4.2 BSD) August, 1983
 > Volume 1
 > Chapter I: Commands: intro, adb, ...
 > Chapter II: System calls: intro, accept, access, ...
 > Chapter III: Subroutines: intro, abort, abs, ...
 > Chapter IV: Special files: intro, acc, ...
 > Chapter V: File formats and conventions: a.out, ...
 > Chapter VI: Games: aardvark, adventure, ...
 > Chapter VII: Macro packages and language conventions: intro, ascii, ...
 > Chapter VIII: Maintenance commands and procedures: intro, ac, ...
 >
 > Seventh Edition, January, 1979
 > Volume 2A
 > 1 and 2: General Works
 > 3 through 7: Getting Started
 > 8 through 13: Document Preparation
 > 14 through 18: Programming
 >
 > Volume 2B:
 > 19 through 28: Supporting Tools and Languages
 > 29 through 38: Implementation, Maintenance and Miscellaneous
 > ...
 >
 > Volume 1 had chapters. The later volumes had numbered documents.

Thanks for the prompt reply!
'chapter' definitely makes more sense, at least considering the manual as a 
book.  Since it seems to have been in general use in the past, it's not so much 
of a breaking change to start using it now again.  So, to avoid ambiguity 
between section referring to a chapter or section referring to part of a page, 
I'll start using the term [sub]chapter consistently.

With time, I expect to replace all occurrences of section that should be chapter 
in the man-pages.

 >
 > Andries

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 6743 bytes --]

Hi!

This is a gentle ping about my terminological reforms about manual page chapters.

Cheers,

Alex

-------- Forwarded Message --------
Subject: Re: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: 
rst2man: .TH 5th field shouldn't be empty)
Date: Thu, 17 Nov 2022 01:28:12 +0100
From: Alejandro Colomar <alx.manpages@gmail.com>
To: Colin Watson <cjwatson@debian.org>, Ingo Schwarze <schwarze@usta.de>, G. 
Branden Robinson <g.branden.robinson@gmail.com>, linux-man 
<linux-man@vger.kernel.org>, groff@gnu.org
CC: Michael Haardt <michael@moria.de>, Andries Brouwer <Andries.Brouwer@cwi.nl>, 
Michael Kerrisk <mtk.manpages@gmail.com>, Douglas McIlroy 
<douglas.mcilroy@dartmouth.edu>, Andries E. Brouwer <aeb@cwi.nl>

Hi Colin, Ingo, and Branden,

On 11/17/22 01:06, G. Branden Robinson wrote:
  >> I used temporarily the term [sub]chapter to see how it fits.
  > I think the adoption of the term (sub)chapter has a potential benefit in
  > that it removes a terminological collision with (sub)sections as
  > subdivisions of individual man pages (man: SH, SS; mdoc: Sh, Ss).
  >
  > If this terminological reform is adopted, I think it should be done
  > across all of (1) Linux man-pages, (2) groff, (3) mandoc, and (4)
  > man-db.  If we can't speak with one voice on this then I think it's
  > better not to undertake that reform at all, to avoid frustrating the
  > discoverabilty of man pages.
  >
  > Possibly the biggest barrier to this is the mnemonic and documentation
  > of the man(1) '-s' option.  In man-db man, '-C' and '-c' are both
  > already in use.

That can be documented as a historical detail in the documentation of the option 
itself, which makes sense, as to avoid programmers that have heard of sections 
to try to grep section and find nothing.

  >
  > Probably a good idea to loop Colin Watson in on this proposal of yours,
  > which is strictly speaking severable from the below.

Yes, especially since part of the discussion is in linux-man@ (I'm not sure if 
he reads it; I think not) and not in groff@ (which he reads, AFAIK).  So, I'll 
merge the 2 discussions about this by forwarding the 2 most interesting other 
emails below.

So, does it make sense to all of us to start using the term chapter for 
divisions of the man-pages single volume, so that the manual pages in Linux are 
organized from now on in chapters 1 to 9 instead of sections 1 to 9?

Cheers,

Alex


-------- Forwarded Message --------
Subject: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: 
.TH 5th field shouldn't be empty)
Date: Wed, 16 Nov 2022 23:46:13 +0100
From: Alejandro Colomar <alx.manpages@gmail.com>
To: G. Branden Robinson <g.branden.robinson@gmail.com>
CC: groff@gnu.org, Michael Haardt <michael@moria.de>, Andries Brouwer 
<Andries.Brouwer@cwi.nl>, Michael Kerrisk <mtk.manpages@gmail.com>, Douglas 
McIlroy <douglas.mcilroy@dartmouth.edu>

Hi Branden!

On 9/7/22 00:13, Alejandro Colomar wrote:
  >>> I've seen sporadically references to the numbers as chapters, probably
  >>> from when the manual was a proper book, but that term seems to have
  >>> fallen in use.
  >>
  >> I don't recall seeing this.  While not my preference, I would regard it
  >> as an excusable innovation in response to an unhelpful overlap in prior
  >> usage.
  >
  > I don't remember where I've seen this.  I seem to recall it, but maybe it's just
  > a glitch in my memory.  It would certainly simplify nomenclature.  If we come up
  > with a good term for subsections such as 3head, I might start using the term
  > colloquially.  Does subchapter sound good to you?
  >


I've got good news for you.  I started writing intro(3type), after I got the 
first contribution of a new page to chapter 3type of the manual.

And while doing it, I found a place where the term 'chapter' is used.  It's very 
likely that there's where I saw it the other time.  It's in a comment in the 
intro(3) page, which seems to be there since there's git history.

The author of the page seems to be Michael Haardt; his last commit to the 
man-pages is from 2015, so I guess his email is still active.  Maybe he can 
comment.  I also CCed aeb and mtk, as they maintained the pages before me and 
may know if that term was in use at the time.


Cheers,

Alex






-------- Forwarded Message --------
Subject: Re: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: 
rst2man: .TH 5th field shouldn't be empty)
Date: Thu, 17 Nov 2022 00:47:43 +0100
From: Alejandro Colomar <alx.manpages@gmail.com>
To: Andries E. Brouwer <aeb@cwi.nl>
CC: G. Branden Robinson <g.branden.robinson@gmail.com>, groff@gnu.org, Michael 
Haardt <michael@moria.de>, Andries Brouwer <Andries.Brouwer@cwi.nl>, Michael 
Kerrisk <mtk.manpages@gmail.com>, Douglas McIlroy <douglas.mcilroy@dartmouth.edu>

Hi Andries!

On 11/17/22 00:40, Andries E. Brouwer wrote:
  >
  >> On 9/7/22 00:13, Alejandro Colomar wrote:
  >>>>> I've seen sporadically references to the numbers as chapters, probably
  >>>>> from when the manual was a proper book, but that term seems to have
  >>>>> fallen in use.
  >
  > Unix Programmer's Manual (4.2 BSD) August, 1983
  > Volume 1
  > Chapter I: Commands: intro, adb, ...
  > Chapter II: System calls: intro, accept, access, ...
  > Chapter III: Subroutines: intro, abort, abs, ...
  > Chapter IV: Special files: intro, acc, ...
  > Chapter V: File formats and conventions: a.out, ...
  > Chapter VI: Games: aardvark, adventure, ...
  > Chapter VII: Macro packages and language conventions: intro, ascii, ...
  > Chapter VIII: Maintenance commands and procedures: intro, ac, ...
  >
  > Seventh Edition, January, 1979
  > Volume 2A
  > 1 and 2: General Works
  > 3 through 7: Getting Started
  > 8 through 13: Document Preparation
  > 14 through 18: Programming
  >
  > Volume 2B:
  > 19 through 28: Supporting Tools and Languages
  > 29 through 38: Implementation, Maintenance and Miscellaneous
  > ...
  >
  > Volume 1 had chapters. The later volumes had numbered documents.

Thanks for the prompt reply!
'chapter' definitely makes more sense, at least considering the manual as a 
book.  Since it seems to have been in general use in the past, it's not so much 
of a breaking change to start using it now again.  So, to avoid ambiguity 
between section referring to a chapter or section referring to part of a page, 
I'll start using the term [sub]chapter consistently.

With time, I expect to replace all occurrences of section that should be chapter 
in the man-pages.

  >
  > Andries

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Michael Haardt]

I just checked what is easily available to me:

v7 calls them sections in intro pages, but chapters in man(1) and man(7).

Celerity Computing UNIX (looks like a BSD port) calls them sections in
intro pages and man(7), but chapter in manv(7) (dtroff version of man(7)).

SunOS 4.1.1 calls them sections everywhere.

HP-UX 11.11 calls them sections everywhere.

Given the changes it looks like you are not the first person to note an
inconsistency here, but I see a majority calling them sections and
getting rid of the term chapter over time.

Now all of the above is commercially obsolete by now and Linux
dominates, but I don't see a good reason to break an established term
and instead suggest to follow the above and s/chapter/section/g.

Michael

Re: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2088 bytes --]

Hi Michael,

On 12/11/22 20:05, Michael Haardt wrote:
> I just checked what is easily available to me: >
> v7 calls them sections in intro pages, but chapters in man(1) and man(7).
> 
> Celerity Computing UNIX (looks like a BSD port) calls them sections in
> intro pages and man(7), but chapter in manv(7) (dtroff version of man(7)).
> 
> SunOS 4.1.1 calls them sections everywhere.
> 
> HP-UX 11.11 calls them sections everywhere.

Thanks for checking!

> 
> Given the changes it looks like you are not the first person to note an
> inconsistency here, but I see a majority calling them sections and
> getting rid of the term chapter over time.

It seems like a regression to me.  The old term was, at least in terms of 
ambiguity, better.

Do we need to fix a decades-old regression in the manual pages?  Well, _need_ is 
a strong word for that.

> 
> Now all of the above is commercially obsolete by now and Linux
> dominates, but I don't see a good reason to break an established term
> and instead suggest to follow the above and s/chapter/section/g.

Admittedly, it's hard to defend my proposal as _necessary_.  Especially after 
the world has lived for decades with the ambiguity of having chapters as 
sections and sections also as... sections.

I have several times had to come up with imaginative ways to disambiguate the 
term section.  Am I a corner case that has to live with that ambiguity way more 
than the average programmer?  Quite likely.

Since I'll some day (likely for 6.02, that's 2 years from now) be publishing the 
Linux man-pages as a single-volume PDF, the term chapter will regain significance.

IMO, there's undoubtedly a reason to fix the regression, and reform the old 
term.  However, the reason is not very strong, so it all depends on reaching an 
agreement with all of man-db, mandoc(1), and groff(1).  That would probably have 
the side-effect that we also have agreement with OpenBSD.  That would be a large 
subset of the relevant parties.

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Michael Haardt]

> Admittedly, it's hard to defend my proposal as _necessary_.  Especially after 
> the world has lived for decades with the ambiguity of having chapters as 
> sections and sections also as... sections.

Well, one are the volume sections and the other manpage sections. :)

Originally, Unix documentation was split into volumes, each taking many
heavy books or binders and a site typically had a big shelf or closet
holding those. In addition there was a documentation overview and a giant
permuted index.

One volume was the reference documentation, that's what we know as
manual pages, and those were also available online. There were no
chapters really. After yacc(1) came intro(2) and then all pages from (2)
in alphabetical order. No separation page or title and the intro pages
looked like all others. Hence .TH, so you could quickly browse through
the pages up to the top line of the page you were looking for. The
binders were labelled with volume and section on their back to speed up
finding something.

The Oxford dictionary defines chapter as "a separate section of a book,
usually with a number or title". Given the lack of separation I see why
they were just called sections, not chapters, and why the term chapter
was removed where it was used in the old days. No ambiguity or regression
there.

The other volumes were a collection of papers on various subsystems and
topics, often written using ms(7). Each Unix distribution extended them
to their desire. Those were not online, because they consumed more space
than the reference manual volume, so they are much less known.

> IMO, there's undoubtedly a reason to fix the regression, and reform the old 
> term.  However, the reason is not very strong, so it all depends on reaching an 
> agreement with all of man-db, mandoc(1), and groff(1).  That would probably have 
> the side-effect that we also have agreement with OpenBSD.  That would be a large 
> subset of the relevant parties.

If those agree, I won't object. That's not an area where I argue about
semantics of single words.

In addition, you could separate the sections into true chapters by making
sure the intro pages can be recognized as introduction, and provide an
chapter overview that links to all intro pages. Back then new users got
to know them from the printed versions, but that is decades ago.

Michael

Re: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Douglas McIlroy]

A nice property of "section" is that it's recursive--applies to any
level of a hierarchy--so you don't have to struggle to keep
level-specific terminology straight.

Doug

On Sun, Dec 11, 2022 at 2:21 PM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> Hi Michael,
>
> On 12/11/22 20:05, Michael Haardt wrote:
> > I just checked what is easily available to me: >
> > v7 calls them sections in intro pages, but chapters in man(1) and man(7).
> >
> > Celerity Computing UNIX (looks like a BSD port) calls them sections in
> > intro pages and man(7), but chapter in manv(7) (dtroff version of man(7)).
> >
> > SunOS 4.1.1 calls them sections everywhere.
> >
> > HP-UX 11.11 calls them sections everywhere.
>
> Thanks for checking!
>
> >
> > Given the changes it looks like you are not the first person to note an
> > inconsistency here, but I see a majority calling them sections and
> > getting rid of the term chapter over time.
>
> It seems like a regression to me.  The old term was, at least in terms of
> ambiguity, better.
>
> Do we need to fix a decades-old regression in the manual pages?  Well, _need_ is
> a strong word for that.
>
> >
> > Now all of the above is commercially obsolete by now and Linux
> > dominates, but I don't see a good reason to break an established term
> > and instead suggest to follow the above and s/chapter/section/g.
>
> Admittedly, it's hard to defend my proposal as _necessary_.  Especially after
> the world has lived for decades with the ambiguity of having chapters as
> sections and sections also as... sections.
>
> I have several times had to come up with imaginative ways to disambiguate the
> term section.  Am I a corner case that has to live with that ambiguity way more
> than the average programmer?  Quite likely.
>
> Since I'll some day (likely for 6.02, that's 2 years from now) be publishing the
> Linux man-pages as a single-volume PDF, the term chapter will regain significance.
>
> IMO, there's undoubtedly a reason to fix the regression, and reform the old
> term.  However, the reason is not very strong, so it all depends on reaching an
> agreement with all of man-db, mandoc(1), and groff(1).  That would probably have
> the side-effect that we also have agreement with OpenBSD.  That would be a large
> subset of the relevant parties.
>
> Cheers,
>
> Alex
>
> --
> <http://www.alejandro-colomar.es/>

Re: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 737 bytes --]

Hi Doug,

On 12/12/22 01:34, Douglas McIlroy wrote:
> A nice property of "section" is that it's recursive--applies to any
> level of a hierarchy--so you don't have to struggle to keep
> level-specific terminology straight.
> 
> Doug
> 

Hmm, since the concerns expressed by Ralph seem to be at least as itchy as mine, 
and the status quo today is that we have sections, it seems reasonable to keep 
it like that.  Fixing my itches would create itches with man(1)'s -s, and I 
don't like that.

Assuming we'll have to live with that, maybe your explanation serves as a 
consolation.  :)

So, I dismiss my prompt to reform the old non-recursive terminology.

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Ralph Corderoy]

Hi Michael,

> I don't see a good reason to break an established term and instead
> suggest to follow the above and s/chapter/section/g.

man(1), apropos(1), and other commands use -s to specify sections and
many finger muscles won't change now.

-- 
Cheers, Ralph.

Re: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 10379 bytes --]

Hi Alex,

At 2022-12-11T17:40:10+0100, Alejandro Colomar wrote:
> This is a gentle ping about my terminological reforms about manual
> page chapters.
[...]
> Hi Colin, Ingo, and Branden,
> On 11/17/22 01:06, G. Branden Robinson wrote:
>  > I think the adoption of the term (sub)chapter has a potential
>  > benefit in that it removes a terminological collision with
>  > (sub)sections as subdivisions of individual man pages (man: SH, SS;
>  > mdoc: Sh, Ss).

I reiterate that using the word "section" to refer to two distinct
concepts in the same domain of discussion is helpful to no one.

>  > If this terminological reform is adopted, I think it should be done
>  > across all of (1) Linux man-pages, (2) groff, (3) mandoc, and (4)
>  > man-db.  If we can't speak with one voice on this then I think it's
>  > better not to undertake that reform at all, to avoid frustrating
>  > the discoverabilty of man pages.

I'd still like to hear from Colin and Ingo to see if they have any
ideas.  But the future doesn't look bright on this point.

>  > Possibly the biggest barrier to this is the mnemonic and
>  > documentation of the man(1) '-s' option.  In man-db man, '-C' and
>  > '-c' are both already in use.
> 
> That can be documented as a historical detail in the documentation of
> the option itself, which makes sense, as to avoid programmers that
> have heard of sections to try to grep section and find nothing.

Right now we (I) have to explain this distinction in the groff_man(7)
page.[1]

Here's what it says (italics in original are lost in email).

    .TH topic section [footer-middle] [footer-inside] [header-middle]
        Determine the contents of the page header and footer.  roff
        systems refer to these collectively as "titles".  The subject of
        the man page is topic and the section of the manual to which it
        belongs is section.  This use of "section" has nothing to do
        with the section headings otherwise discussed in this page; it
        arises from the organizational scheme of printed and bound Unix
        manuals.  See man(1) for details on the section numbers and
        suffixes applicable to your system.  [...]

I don't know if anyone else bothers to explain this distinction.  There
is a lengthy, sad tradition of Unix experts keeping gates by maintaining
knowledge at the level of folklore rather than proper documentation,
despite the excellent precedents set by the Bell Labs CSRC and UCB CSRG.

Thus when implementors with imperfect knowledge come along later, their
mistaken grasp of history determines the "finger memory" of users for
decades afterward.

>  > Probably a good idea to loop Colin Watson in on this proposal of
>  > yours, which is strictly speaking severable from the below.
> 
> Yes, especially since part of the discussion is in linux-man@ (I'm not
> sure if he reads it; I think not) and not in groff@ (which he reads,
> AFAIK).  So, I'll merge the 2 discussions about this by forwarding the
> 2 most interesting other emails below.
> 
> So, does it make sense to all of us to start using the term chapter
> for divisions of the man-pages single volume, so that the manual pages
> in Linux are organized from now on in chapters 1 to 9 instead of
> sections 1 to 9?

The users appear to be speaking against it, on the rather pitiful
grounds of "finger memory".  I term this "pitiful" not as a knock on the
protestors--I have finger memory too--but on the situation causing it.
Once again we see how cramming everything into a minimal name space
causes problems.  (The usual grognard rebuttal to affording a more
capacious name space is to have one's interface do less, which is only
sometimes a wise prescription.[2])

But yeah, man-db man(1) has occupied a large number of positions in the
base-62 conventional single-character option name space.

Using '#' as an unused slot for a numeral and '$' as an unused slot for
a letter, I see:

# # # # # # # 7 # #
$ $ C D E $ $ H I $ K L M $ $ P $ R S T $ V W X $ Z
a $ c d e f $ $ i $ k l m $ $ p $ r s t u $ w $ $ $

[email about intro(3type) and Michael Haardt snipped; I have no useful
comment on it]

> On 11/17/22 00:40, Andries E. Brouwer wrote:
>  >> On 9/7/22 00:13, Alejandro Colomar wrote:
>  >>>>> I've seen sporadically references to the numbers as chapters,
>  >>>>> probably from when the manual was a proper book, but that term
>  >>>>> seems to have fallen in use.
>  >
>  > Unix Programmer's Manual (4.2 BSD) August, 1983
>  > Volume 1
>  > Chapter I: Commands: intro, adb, ...
>  > Chapter II: System calls: intro, accept, access, ...
>  > Chapter III: Subroutines: intro, abort, abs, ...
>  > Chapter IV: Special files: intro, acc, ...
>  > Chapter V: File formats and conventions: a.out, ...
>  > Chapter VI: Games: aardvark, adventure, ...
>  > Chapter VII: Macro packages and language conventions: intro, ascii, ...
>  > Chapter VIII: Maintenance commands and procedures: intro, ac, ...
>  >
>  > Seventh Edition, January, 1979
>  > Volume 2A
>  > 1 and 2: General Works
>  > 3 through 7: Getting Started
>  > 8 through 13: Document Preparation
>  > 14 through 18: Programming
>  >
>  > Volume 2B:
>  > 19 through 28: Supporting Tools and Languages
>  > 29 through 38: Implementation, Maintenance and Miscellaneous
>  > ...
>  >
>  > Volume 1 had chapters. The later volumes had numbered documents.

I have to admit that the thought of using Unix (Version 7) Programmer's
Manual Volume 1 editor Doug McIlroy as a bludgeon of authority with
which to beat the grognards at their own game is tempting.

But Doug's a benevolent soul, seems disinclined to see his CV employed
as weaponry, and we younglings, as gray-bearded as some of us have
become, have to cope with our own problems.

Nevertheless, the above knowledge is well worth keeping in mind and
having in reserve for quotation, as the quantity of ignorantly jerking
knees against any reform as radical and ahistorical is large.  (Just
don't expect to actually convince a disputant with facts; the bystanding
audience is typically more edified than those who have already committed
themselves to a position.[3])

The 4.2BSD provenance is particularly valuable, in that it illustrates
how the terminology was retained rather than thrown out as an ugly
"USG-ism" (or some other derogatory epithet) at the first opportunity.

> Thanks for the prompt reply!  'chapter' definitely makes more sense,
> at least considering the manual as a book.  Since it seems to have
> been in general use in the past, it's not so much of a breaking change
> to start using it now again.

Yeah, people will fight you on that even when you put unimpeachable
evidence of their incorrect characterization of history directly in
their faces.

There is a quote that is not famous enough to suit me.  The first three
sentences suffice, but it feels wrong to omit the remaining context.

"The whole modern world has divided itself into Conservatives and
Progressives.  The business of Progressives is to go on making mistakes.
The business of Conservatives is to prevent mistakes from being
corrected.  Even when the revolutionist might himself repent of his
revolution, the traditionalist is already defending it as part of his
tradition.  Thus we have two great types -- the advanced person who
rushes us into ruin, and the retrospective person who admires the ruins.
He admires them especially by moonlight, not to say moonshine.  Each new
blunder of the progressive or prig becomes instantly a legend of
immemorial antiquity for the snob.  This is called the balance, or
mutual check, in our Constitution." -- G. K. Chesterton

> So, to avoid ambiguity between section referring to a chapter or
> section referring to part of a page, I'll start using the term
> [sub]chapter consistently.
> 
> With time, I expect to replace all occurrences of section that should
> be chapter in the man-pages.

I'm not a -1 on this but I'm not hopeful for its future.  I refuse to
veto it but I think is probably gentler to maintain apologies as shown
above in the description of the `TH` macro, which is aimed at man page
_writers_, than to explain the anti-mnemonic value of man(1)'s -[Ss]
flags, which are used by more numerous man page _readers_.

At the same time, I remain close to the fence because even man page
readers have to cope with both senses of the word "section" simply to
navigate within and among pages.

So you can count on me, like Stalin in August 1945, to join the war
against Japan only once the outcome is assured by my allies, so that I
can claim the right to participate at the postwar negotiating table.[4]

	This use of "section" has nothing to do with the section
	headings otherwise discussed in this page; it arises from the
	organizational scheme of printed and bound Unix manuals.

I imagine being able to deport that sentence from groff_man(7) and sigh.
South Sakhalin Island never looked so good.

Regards,
Branden

[1] Strictly, it should be in groff_mdoc(7) as well.  As I'm finally
    rewriting that page, maybe such a change will show up in time for
    groff 1.23.

[2] In principle, man(1)'s librarian and presentation functions could be
    decoupled; the former would deal only with parameters that locate a
    page (or list of pages) [much as "-aw" works today], while the
    latter would collect the results for passage as operands to a *roff
    formatter.  In working on groff, I have occasionally wished that
    man(1) had a single option that simply meant "pass the following
    argument to the formatter" (as GNU [gnt]roff's own "-P" option can
    be used to pass arguments to the output driver).  But a change like
    this might be so disruptive to user experience that the resulting
    resulting reärchitected command would need to be called "man2" or
    something silly like that.[5]  If I were Colin I'm not sure I would
    be eager to face the howling cacophony of les doigt-mémoires.

[3] https://weeklysift.com/2022/06/27/the-january-6-hearings-are-accomplishing-more-than-you-think/
[4] https://en.wikipedia.org/wiki/Soviet%E2%80%93Japanese_War
[5] I dedicate that dieresis to the editorial staff of the _New Yorker_.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Andries E. Brouwer]

On Mon, Dec 12, 2022 at 07:19:22AM -0600, G. Branden Robinson wrote:

> The 4.2BSD provenance is particularly valuable, in that it illustrates
> how the terminology was retained

Earlier I replied and showed a snapshot of the history.
Contemporary:

https://www.freebsd.org/cgi/man.cgi
All Sections

https://man.openbsd.org
All Sections

A random Oracle man page for SunOS:
man pages section 2: System Calls

https://developer.apple.com/documentation/os/reading_unix_manual_pages
"Section 1 of the man pages covers command-line tools, section 2 covers system calls, section 3 covers user-space libraries, and so on."

Etc.

It may be true that there was historical use of "chapter", but
all common places today have "section".

Andries

Re: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Colin Watson]

[Sorry for the delay; a succession of business travel, holidays, and
Covid have together eaten up much of my time recently.]

On Thu, Nov 17, 2022 at 01:28:12AM +0100, Alejandro Colomar wrote:
> On 11/17/22 01:06, G. Branden Robinson wrote:
> > I think the adoption of the term (sub)chapter has a potential benefit in
> > that it removes a terminological collision with (sub)sections as
> > subdivisions of individual man pages (man: SH, SS; mdoc: Sh, Ss).
> >
> > If this terminological reform is adopted, I think it should be done
> > across all of (1) Linux man-pages, (2) groff, (3) mandoc, and (4)
> > man-db.  If we can't speak with one voice on this then I think it's
> > better not to undertake that reform at all, to avoid frustrating the
> > discoverabilty of man pages.
> >
> > Possibly the biggest barrier to this is the mnemonic and documentation
> > of the man(1) '-s' option.  In man-db man, '-C' and '-c' are both
> > already in use.
> 
> That can be documented as a historical detail in the documentation of the
> option itself, which makes sense, as to avoid programmers that have heard of
> sections to try to grep section and find nothing.
> 
> > Probably a good idea to loop Colin Watson in on this proposal of yours,
> > which is strictly speaking severable from the below.
> 
> Yes, especially since part of the discussion is in linux-man@ (I'm not sure
> if he reads it; I think not) and not in groff@ (which he reads, AFAIK).  So,
> I'll merge the 2 discussions about this by forwarding the 2 most interesting
> other emails below.

I'm not subscribed to linux-man@, and while I am technically subscribed
to groff@ I read it very infrequently these days, so thanks for
explicitly copying me in.

> So, does it make sense to all of us to start using the term chapter for
> divisions of the man-pages single volume, so that the manual pages in Linux
> are organized from now on in chapters 1 to 9 instead of sections 1 to 9?

I find myself relatively agnostic on this whole discussion.  There are
good reasons for reform, and also some good reasons to wonder whether
the grass will in fact be greener on the other side (given the necessity
to keep many bits of "section" terminology around in things like
man(1)'s option handling and the man-db configuration file more or less
indefinitely).

I'm not going to veto it, but I also have no great enthusiasm for the
upheaval.  If the community consensus is for it to happen, then I'd ask
that somebody who is enthusiastic about it put the work into the various
necessary updates to man-db's code and documentation and send an
appropriate merge request.

-- 
Colin Watson (he/him)                              [cjwatson@debian.org]

Re: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3077 bytes --]

Hi Colin!

On 12/12/22 14:39, Colin Watson wrote:
> [Sorry for the delay; a succession of business travel, holidays, and
> Covid have together eaten up much of my time recently.]
> 
> On Thu, Nov 17, 2022 at 01:28:12AM +0100, Alejandro Colomar wrote:
>> On 11/17/22 01:06, G. Branden Robinson wrote:
>>> I think the adoption of the term (sub)chapter has a potential benefit in
>>> that it removes a terminological collision with (sub)sections as
>>> subdivisions of individual man pages (man: SH, SS; mdoc: Sh, Ss).
>>>
>>> If this terminological reform is adopted, I think it should be done
>>> across all of (1) Linux man-pages, (2) groff, (3) mandoc, and (4)
>>> man-db.  If we can't speak with one voice on this then I think it's
>>> better not to undertake that reform at all, to avoid frustrating the
>>> discoverabilty of man pages.
>>>
>>> Possibly the biggest barrier to this is the mnemonic and documentation
>>> of the man(1) '-s' option.  In man-db man, '-C' and '-c' are both
>>> already in use.
>>
>> That can be documented as a historical detail in the documentation of the
>> option itself, which makes sense, as to avoid programmers that have heard of
>> sections to try to grep section and find nothing.
>>
>>> Probably a good idea to loop Colin Watson in on this proposal of yours,
>>> which is strictly speaking severable from the below.
>>
>> Yes, especially since part of the discussion is in linux-man@ (I'm not sure
>> if he reads it; I think not) and not in groff@ (which he reads, AFAIK).  So,
>> I'll merge the 2 discussions about this by forwarding the 2 most interesting
>> other emails below.
> 
> I'm not subscribed to linux-man@, and while I am technically subscribed
> to groff@ I read it very infrequently these days, so thanks for
> explicitly copying me in.
> 
>> So, does it make sense to all of us to start using the term chapter for
>> divisions of the man-pages single volume, so that the manual pages in Linux
>> are organized from now on in chapters 1 to 9 instead of sections 1 to 9?
> 
> I find myself relatively agnostic on this whole discussion.  There are
> good reasons for reform, and also some good reasons to wonder whether
> the grass will in fact be greener on the other side (given the necessity
> to keep many bits of "section" terminology around in things like
> man(1)'s option handling and the man-db configuration file more or less
> indefinitely).
> 
> I'm not going to veto it, but I also have no great enthusiasm for the
> upheaval.  If the community consensus is for it to happen, then I'd ask
> that somebody who is enthusiastic about it put the work into the various
> necessary updates to man-db's code and documentation and send an
> appropriate merge request.

I can do that.  Don't expect it to be perfect, but I can iterate on it upon your 
requests.

Branden's seems to have predisposition for the change, like me.  But like you we 
have some doubts.  Let's see what Ingo has to say.

Thanks!

Alex

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2641 bytes --]

Hi Deri,

On 12/17/22 02:04, Deri wrote:
> On Friday, 16 December 2022 19:31:41 GMT Alejandro Colomar wrote:
>> Hi Deri!
>>
>> On 12/16/22 20:13, Deri wrote:
>>> On Sunday, 11 December 2022 19:21:27 GMT Alejandro Colomar wrote:
>>>> Since I'll some day (likely for 6.02, that's 2 years from now) be
>>>> publishing the Linux man-pages as a single-volume PDF, the term chapter
>>>> will regain significance.
>>>
>>> Hi Alejandro,
>>>
>>> I saw this on the groff list and wondered what would be involved, so I
>>> cloned the git from your website
>>
>> I guess you mean <//www.alejandro-colomar.es/src/>, right?  I guess so,
>> since the MR branch is only there.
>>
>>> and wrote a perl script, plus a few customisations
>>> of groff tmacs, and produced the attached pdf.
>>
>> Wow!  It looks really nice!
>>
>> I noticed a few small issues:
>>
> Hi Alex,
> 
>> -  link (.so) pages appear misplaced in the navigation.  For example
>> writev.2 appears inside man2type.
>>
>> -  intro(*) should be the first page of each section.  (So far, subsections
>> don't have intro, but I wouldn't discard that.)
> 
> Both fixed in latest version. Which you can find here:-
> 
> http://chuzzlewit.co.uk/LinuxManBook.pdf

It looks great!  We could release it already :)

> 
>>> You will notice all the internal .MR calls are working.
>>
>> Yep
>>
>>> It is not perfect yet,
>>> but I thought I would let you see how far I have got, and find out whether
>>> this is something you would like contributed.
>>
>> Sure!  We can even merge something already.  I doesn't need to be perfect at
>> the begining.  Is perl necessary, or could it be transformed into a shell
>> script? I'm not comfortable at maintaining a perl script.
> 
> I think it may be a bit beyond a shell script, but I am not an accomplished
> shell script programmer. I am hoping it will end up as part of your build.

Please send your perl script as a patch, adding it to the <scripts/> directory. 
Put your copyright and your preferred license, and we can work from there to 
transform it into something I can better understand.  I'll probably be asking 
you many questions :)

Cheers,

Alex

> 
> Cheers
> 
> Deri
> 
>>> I would welcome any views on
>>> what I have done so far.
>>
>> It looks great.  I'd like to hook it into the build system, so we can `make
>> build-pdf` and generate it.
>>
>>> In case you don't know, I'm the chap who developed the groff pdf driver.
>>
>> Yep, I know
>>
>>> Cheers
>>>
>>> Deri
>>
>> Cheers,
>>
>> Alex
> 
> 
> 
> 

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[BUG] gropdf, tbl: Completely broken table (was: Ping^1: Chapters of the manual (was: Bug#1018737: ...))

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3028 bytes --]

Hi Deri,

On 12/17/22 12:51, Alejandro Colomar wrote:
>>> I noticed a few small issues:
>>>
>> Hi Alex,
>>
>>> -  link (.so) pages appear misplaced in the navigation.  For example
>>> writev.2 appears inside man2type.
>>>
>>> -  intro(*) should be the first page of each section.  (So far, subsections
>>> don't have intro, but I wouldn't discard that.)
>>
>> Both fixed in latest version. Which you can find here:-
>>
>> http://chuzzlewit.co.uk/LinuxManBook.pdf
> 

Another bug report (but not about the script; this seems to be about tbl(1) 
interaction with gropdf(1), I guess):

<http://chuzzlewit.co.uk/LinuxManBook.pdf#pdf%3Abm11813>

Running all the linters I know doesn't trigger any warnings on the page source:

$ touch ./man7/suffixes.7
$ make lint
LINT (groff)	tmp/lint/man7/suffixes.7.lint-man.groff.touch
LINT (mandoc)	tmp/lint/man7/suffixes.7.lint-man.mandoc.touch
LINT (tbl)	tmp/lint/man7/suffixes.7.lint-man.tbl.touch
$ touch ./man7/suffixes.7
$ make lint V=1
LINT (groff)	tmp/lint/man7/suffixes.7.lint-man.groff.touch
tbl man7/suffixes.7 \
| eqn -Tutf8  \
| troff -man -t -M ./etc/groff/tmac -m checkstyle -rCHECKSTYLE=3 -ww -Tutf8 
-rLL=78n  \
| grotty -c  \
| col -b -p -x  \
| (! grep -n '.\{80\}.' | sed 's,^,man7/suffixes.7:,' >&2)
touch tmp/lint/man7/suffixes.7.lint-man.groff.touch
LINT (mandoc)	tmp/lint/man7/suffixes.7.lint-man.mandoc.touch
! (mandoc -man -Tlint  man7/suffixes.7 2>&1 \
    | grep -v 'STYLE: lower case character in document title:' \
    | grep -v 'UNSUPP: ignoring macro in table:' \
    | grep -v 'WARNING: cannot parse date, using it verbatim: TH (date)' \
    | grep -v 'WARNING: empty block: UR' \
    ||:; \
) \
| grep '.' >&2
touch tmp/lint/man7/suffixes.7.lint-man.mandoc.touch
LINT (tbl)	tmp/lint/man7/suffixes.7.lint-man.tbl.touch
if grep -q '^\.TS$' man7/suffixes.7 && ! head -n1 man7/suffixes.7 | grep -q '\\" 
t$'; \
then \
	2>&1 echo "man7/suffixes.7:1: missing '\\\" t' comment:"; \
	2>&1 head -n1 <man7/suffixes.7; \
	exit 1; \
fi
if head -n1 man7/suffixes.7 | grep -q '\\" t$' && ! grep -q '^\.TS$' 
man7/suffixes.7; \
then \
	2>&1 echo "man7/suffixes.7:1: spurious '\\\" t' comment:"; \
	2>&1 head -n1 <man7/suffixes.7; \
	exit 1; \
fi
if tail -n+2 <man7/suffixes.7 | grep -q '\\" t$'; \
then \
	2>&1 echo "man7/suffixes.7: spurious '\\\" t' not in first line:"; \
	2>&1 grep -n '\\" t$' man7/suffixes.7 /dev/null; \
	exit 1; \
fi
touch tmp/lint/man7/suffixes.7.lint-man.tbl.touch



Okay, I have a few disabled because they were noisy, but I guess they shouldn't 
be important.  You can see the mandoc(1) ignored warnings just from the above 
command.  Here are the groff ones:


$ cat ./etc/groff/tmac/checkstyle.tmac
.am an-style-warn
.	ds LANDMINE\"
..
.\"
.de end-of-input-macro
.	if d LANDMINE .ab found style problems; aborting
..
.\"
.em end-of-input-macro
.\"
.de an-blank-line-trap
.	sp
..


Cheers,

Alex


-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [BUG] gropdf, tbl: Completely broken table (was: Ping^1: Chapters of the manual (was: Bug#1018737: ...))

[G. Branden Robinson]

[-- Attachment #1.1: Type: text/plain, Size: 4002 bytes --]

Hi Alex,

At 2022-12-17T14:19:55+0100, Alejandro Colomar wrote:
> Another bug report (but not about the script; this seems to be about
> tbl(1) interaction with gropdf(1), I guess):
> 
> <http://chuzzlewit.co.uk/LinuxManBook.pdf#pdf%3Abm11813>

The suffixes(7) page, which I've managed to never see in 25 years as a
GNU/Linux user!  Ah, well.

Dude, I'm friggin' _trying_ to get groff ready for 1.23.0.rc2 and you
nerd-snipe me with this huge list of things that hasn't been updated in
twenty years and has all kinds of fiddly little things wrong with it--
this of course constitutes an OCD emergency for me!

https://xkcd.com/356/

> Running all the linters I know doesn't trigger any warnings on the
> page source:

That tbl(1) source isn't invalid but it is pretty weird.

I tend to agree that there is a gropdf(1) bug here, as grops(1) handles
the same input fine.  But Deri is the real expert and I will let him
speak to that.

I'm attaching a patch that does three things:

1. Removes the hack to shut up warnings from grotty(1).  This was indeed
   a bug, it's been around forever (possibly since ~1990), and it is
   fixed in groff Git.  Expect that in 1.23.0.  man-db man(1) conceals
   these diagnostic messages anyway.

   https://savannah.gnu.org/bugs/index.php?63449

2. Stops using leading spaces in table entries.  This is a kind of weird
   thing to do.  The likely reason is that the table author(s) had a ton
   of entries that started with dots (the *roff control character) and
   didn't know to prefix them with the *roff dummy character (`\&`) to
   keep them from being interpreted as requests or macro calls.  The
   tbl(1) page in groff 1.23.0 explicitly documents this use (the old
   one seems to have expected the reader to have access to CSTR #49 by
   Lesk).

    Rows of table entries can be interleaved with groff control lines;
    these do not count as table data.  On such lines the default control
    character (.) must be used (and not changed); the no‐break control
    character is not recognized.  To start the first table entry in a
    row with a dot, precede it with the token \&.

3. I added the dummy character even on "continuation" lines where a
   description overran.  This does no damage since the tab character
   remains there as an entry separator and the dummy character by itself
   is harmless as a marker of an empty table entry.  I even recommend
   this in the GNU tbl 1.23.0 man page; it's much nicer for people whose
   text editors don't visibly highlight tabs.

A _more_ idiomatic thing to do would be to use a spanning table
entry `\^` for rows where the description get continued, but that makes
no practical difference for a simple table layout like this one.

More idiomatic still, and well worth considering for the future, is
setting _all_ of these descriptions in text blocks.  This table looks to
me like it was laid out for an 80-column terminal with the excessively
long descriptions manually broken.  This looks suboptimal when typeset
and will look ridiculous on a wide terminal.

Also, use of a text block enables the employment of man(7) macros
instead of font selection escape sequences to change the typeface, and,
importantly for the near Linux man-pages future, use of the new `MR`
macro to cross reference the many pages referred to in these
descriptions.

I didn't pursue further revision along either of these lines because the
as I look at these the entries, the intensity of my urge to do a
top-to-bottom revision fixing the many infelicities and a few outright
errors increases exponentially with time.  There is even at least one
unescaped hyphen!  🤯

Regrettably, if a moderately experienced GNU/Linux user has gone 25
years without seeing this page, likely many others will go 25 more
without seeing it.  A good intro(1) page would cross reference it,
aiding the novice.

Unofficial patch attached.

Regards,
Branden

[-- Attachment #1.2: suffixes.7.diff --]
[-- Type: text/x-diff, Size: 15336 bytes --]

--- suffixes.7	2022-12-17 09:41:14.444969997 -0600
+++ suffixes.7.new	2022-12-17 09:41:06.261023174 -0600
@@ -13,9 +13,6 @@
 .\" Modified Thu Nov 16 23:28:25 2000 by David A. Wheeler
 .\"    <dwheeler@dwheeler.com>
 .\"
-.\" "nroff" ("man") (or "tbl") needs a long page to avoid warnings
-.\" from "grotty" (at imagined page breaks).  Bug in grotty?
-.if n .pl 1000v
 .TH SUFFIXES 7 (date) "Linux man-pages (unreleased)"
 .SH NAME
 suffixes \- list of file suffixes
@@ -36,222 +33,222 @@
 _ | _
 lI |  l .
 Suffix	File type
- ,v	files for RCS (Revision Control System)
- -	backup file
- .C	C++ source code, equivalent to \fI.cc\fP
- .F	Fortran source with \fBcpp\fP(1) directives
-	or file compressed using freeze
- .S	assembler source with \fBcpp\fP(1) directives
- .Y	file compressed using yabba
- .Z	file compressed using \fBcompress\fP(1)
- .[0\-9]+gf	TeX generic font files
- .[0\-9]+pk	TeX packed font files
- .[1\-9]	manual page for the corresponding section
- .[1\-9][a-z]	manual page for section plus subsection
- .a	static object code library
- .ad	X application default resource file
- .ada	Ada source (may be body, spec, or combination)
- .adb	Ada body source
- .ads	Ada spec source
- .afm	PostScript font metrics
- .al	Perl autoload file
- .am	\fBautomake\fP(1) input file
- .arc	\fBarc\fP(1) archive
- .arj	\fBarj\fP(1) archive
- .asc	PGP ASCII-armored data
- .asm	(GNU) assembler source file
- .au	Audio sound file
- .aux	LaTeX auxiliary file
- .avi	(msvideo) movie
- .awk	AWK language program
- .b	LILO boot loader image
- .bak	backup file
- .bash	\fBbash\fP(1) shell script
- .bb	basic block list data produced by
-	gcc \-ftest\-coverage
- .bbg	basic block graph data produced by
-	gcc \-ftest\-coverage
- .bbl	BibTeX output
- .bdf	X font file
- .bib	TeX bibliographic database, BibTeX input
- .bm	bitmap source
- .bmp	bitmap
- .bz2	file compressed using \fBbzip2\fP(1)
- .c	C source
- .cat	message catalog files
- .cc	C++ source
- .cf	configuration file
- .cfg	configuration file
- .cgi	WWW content generating script or program
- .cls	LaTeX Class definition
- .class	Java compiled byte-code
- .conf	configuration file
- .config	configuration file
- .cpp	equivalent to \fI.cc\fR
- .csh	\fBcsh\fP(1) shell script
- .cxx	equivalent to \fI.cc\fR
- .dat	data file
- .deb	Debian software package
- .def	Modula-2 source for definition modules
- .def	other definition files
- .desc	initial part of mail message unpacked with
-	\fBmunpack\fP(1)
- .diff	file differences (\fBdiff\fP(1) command output)
- .dir	dbm data base directory file
- .doc	documentation file
- .dsc	Debian Source Control (source package)
- .dtx	LaTeX package source file
- .dvi	TeX's device independent output
- .el	Emacs-Lisp source
- .elc	compiled Emacs-Lisp source
- .eps	encapsulated PostScript
- .exp	Expect source code
- .f	Fortran source
- .f77	Fortran 77 source
- .f90	Fortran 90 source
- .fas	precompiled Common-Lisp
- .fi	Fortran include files
- .fig	FIG image file (used by \fBxfig\fP(1))
- .fmt	TeX format file
- .gif	Compuserve Graphics Image File format
- .gmo	GNU format message catalog
- .gsf	Ghostscript fonts
- .gz	file compressed using \fBgzip\fP(1)
- .h	C or C++ header files
- .help	help file
- .hf	equivalent to \fI.help\fP
- .hlp	equivalent to \fI.help\fP
- .htm	poor man's \fI.html\fP
- .html	HTML document used with the World Wide Web
- .hqx	7-bit encoded Macintosh file
- .i	C source after preprocessing
- .icon	bitmap source
- .idx	reference or datum-index file for hypertext
-	or database system
- .image	bitmap source
- .in	configuration template, especially for GNU Autoconf
- .info	files for the Emacs info browser
- .info-[0\-9]+	split info files
- .ins	LaTeX package install file for docstrip
- .itcl	itcl source code;
-	itcl ([incr Tcl]) is an OO extension of tcl
- .java	a Java source file
- .jpeg	Joint Photographic Experts Group format
- .jpg	poor man's \fI.jpeg\fP
- .kmap	\fBlyx\fP(1) keymap
- .l	equivalent to \fI.lex\fP or \fI.lisp\fP
- .lex	\fBlex\fP(1) or \fBflex\fP(1) files
- .lha	lharc archive
- .lib	Common-Lisp library
- .lisp	Lisp source
- .ln	files for use with \fBlint\fP(1)
- .log	log file, in particular produced by TeX
- .lsm	Linux Software Map entry
- .lsp	Common-Lisp source
- .lzh	lharc archive
- .m	Objective-C source code
- .m4	\fBm4\fP(1) source
- .mac	macro files for various programs
- .man	manual page (usually source rather than formatted)
- .map	map files for various programs
- .me	Nroff source using the me macro package
- .mf	Metafont (font generator for TeX) source
- .mgp	MagicPoint file
- .mm	sources for \fBgroff\fP(1) in mm - format
- .mo	Message catalog binary file
- .mod	Modula-2 source for implementation modules
- .mov	(quicktime) movie
- .mp	Metapost source
- .mp2	MPEG Layer 2 (audio) file
- .mp3	MPEG Layer 3 (audio) file
- .mpeg	movie file
- .o	object file
- .old	old or backup file
- .orig	backup (original) version of a file, from \fBpatch\fP(1)
- .out	output file, often executable program (a.out)
- .p	Pascal source
- .pag	dbm data base data file
- .patch	file differences for \fBpatch\fP(1)
- .pbm	portable bitmap format
- .pcf	X11 font files
- .pdf	Adobe Portable Data Format
-	(use Acrobat/\fBacroread\fP or \fBxpdf\fP)
- .perl	Perl source (see .ph, .pl, and .pm)
- .pfa	PostScript font definition files, ASCII format
- .pfb	PostScript font definition files, binary format
- .pgm	portable greymap format
- .pgp	PGP binary data
- .ph	Perl header file
- .php	PHP program file
- .php3	PHP3 program file
- .pid	File to store daemon PID (e.g., crond.pid)
- .pl	TeX property list file or Perl library file
- .pm	Perl module
- .png	Portable Network Graphics file
- .po	Message catalog source
- .pod	\fBperldoc\fP(1) file
- .ppm	portable pixmap format
- .pr	bitmap source
- .ps	PostScript file
- .py	Python source
- .pyc	compiled python
- .qt	quicktime movie
- .r	RATFOR source (obsolete)
- .rej	patches that \fBpatch\fP(1) couldn't apply
- .rpm	RPM software package
- .rtf	Rich Text Format file
- .rules	rules for something
- .s	assembler source
- .sa	stub libraries for a.out shared libraries
- .sc	\fBsc\fP(1) spreadsheet commands
- .scm	Scheme source code
- .sed	sed source file
- .sgml	SGML source file
- .sh	\fBsh\fP(1) scripts
- .shar	archive created by the \fBshar\fP(1) utility
- .so	Shared library or dynamically loadable object
- .sql	SQL source
- .sqml	SQML schema or query program
- .sty	LaTeX style files
- .sym	Modula-2 compiled definition modules
- .tar	archive created by the \fBtar\fP(1) utility
- .tar.Z	tar(1) archive compressed with \fBcompress\fP(1)
- .tar.bz2	tar(1) archive compressed with \fBbzip2\fP(1)
- .tar.gz	tar(1) archive compressed with \fBgzip\fP(1)
- .taz	tar(1) archive compressed with \fBcompress\fP(1)
- .tcl	tcl source code
- .tex	TeX or LaTeX source
- .texi	equivalent to \fI.texinfo\fP
- .texinfo	Texinfo documentation source
- .text	text file
- .tfm	TeX font metric file
- .tgz	tar archive compressed with \fBgzip\fP(1)
- .tif	poor man's \fI.tiff\fP
- .tiff	Tagged Image File Format
- .tk	tcl/tk script
- .tmp	temporary file
- .tmpl	template files
- .txt	equivalent to \fI.text\fP
- .uu	equivalent to \fI.uue\fP
- .uue	binary file encoded with \fBuuencode\fP(1)
- .vf	TeX virtual font file
- .vpl	TeX virtual property list file
- .w	Silvio Levi's CWEB
- .wav	wave sound file
- .web	Donald Knuth's WEB
- .wml	Source file for Web Meta Language
- .xbm	X11 bitmap source
- .xcf	GIMP graphic
- .xml	eXtended Markup Language file
- .xpm	X11 pixmap source
- .xs	Perl xsub file produced by h2xs
- .xsl	XSL stylesheet
- .y	\fByacc\fP(1) or \fBbison\fP(1) (parser generator) files
- .z	File compressed using \fBpack\fP(1) (or an old \fBgzip\fP(1))
- .zip	\fBzip\fP(1) archive
- .zoo	\fBzoo\fP(1) archive
- \(ti	Emacs or \fBpatch\fP(1) backup file
- rc	startup (`run control') file, e.g., \fI.newsrc\fP
+\&,v	files for RCS (Revision Control System)
+\&-	backup file
+\&.C	C++ source code, equivalent to \fI.cc\fP
+\&.F	Fortran source with \fBcpp\fP(1) directives
+\&	or file compressed using freeze
+\&.S	assembler source with \fBcpp\fP(1) directives
+\&.Y	file compressed using yabba
+\&.Z	file compressed using \fBcompress\fP(1)
+\&.[0\-9]+gf	TeX generic font files
+\&.[0\-9]+pk	TeX packed font files
+\&.[1\-9]	manual page for the corresponding section
+\&.[1\-9][a-z]	manual page for section plus subsection
+\&.a	static object code library
+\&.ad	X application default resource file
+\&.ada	Ada source (may be body, spec, or combination)
+\&.adb	Ada body source
+\&.ads	Ada spec source
+\&.afm	PostScript font metrics
+\&.al	Perl autoload file
+\&.am	\fBautomake\fP(1) input file
+\&.arc	\fBarc\fP(1) archive
+\&.arj	\fBarj\fP(1) archive
+\&.asc	PGP ASCII-armored data
+\&.asm	(GNU) assembler source file
+\&.au	Audio sound file
+\&.aux	LaTeX auxiliary file
+\&.avi	(msvideo) movie
+\&.awk	AWK language program
+\&.b	LILO boot loader image
+\&.bak	backup file
+\&.bash	\fBbash\fP(1) shell script
+\&.bb	basic block list data produced by
+\&	gcc \-ftest\-coverage
+\&.bbg	basic block graph data produced by
+\&	gcc \-ftest\-coverage
+\&.bbl	BibTeX output
+\&.bdf	X font file
+\&.bib	TeX bibliographic database, BibTeX input
+\&.bm	bitmap source
+\&.bmp	bitmap
+\&.bz2	file compressed using \fBbzip2\fP(1)
+\&.c	C source
+\&.cat	message catalog files
+\&.cc	C++ source
+\&.cf	configuration file
+\&.cfg	configuration file
+\&.cgi	WWW content generating script or program
+\&.cls	LaTeX Class definition
+\&.class	Java compiled byte-code
+\&.conf	configuration file
+\&.config	configuration file
+\&.cpp	equivalent to \fI.cc\fR
+\&.csh	\fBcsh\fP(1) shell script
+\&.cxx	equivalent to \fI.cc\fR
+\&.dat	data file
+\&.deb	Debian software package
+\&.def	Modula-2 source for definition modules
+\&.def	other definition files
+\&.desc	initial part of mail message unpacked with
+\&	\fBmunpack\fP(1)
+\&.diff	file differences (\fBdiff\fP(1) command output)
+\&.dir	dbm data base directory file
+\&.doc	documentation file
+\&.dsc	Debian Source Control (source package)
+\&.dtx	LaTeX package source file
+\&.dvi	TeX's device independent output
+\&.el	Emacs-Lisp source
+\&.elc	compiled Emacs-Lisp source
+\&.eps	encapsulated PostScript
+\&.exp	Expect source code
+\&.f	Fortran source
+\&.f77	Fortran 77 source
+\&.f90	Fortran 90 source
+\&.fas	precompiled Common-Lisp
+\&.fi	Fortran include files
+\&.fig	FIG image file (used by \fBxfig\fP(1))
+\&.fmt	TeX format file
+\&.gif	Compuserve Graphics Image File format
+\&.gmo	GNU format message catalog
+\&.gsf	Ghostscript fonts
+\&.gz	file compressed using \fBgzip\fP(1)
+\&.h	C or C++ header files
+\&.help	help file
+\&.hf	equivalent to \fI.help\fP
+\&.hlp	equivalent to \fI.help\fP
+\&.htm	poor man's \fI.html\fP
+\&.html	HTML document used with the World Wide Web
+\&.hqx	7-bit encoded Macintosh file
+\&.i	C source after preprocessing
+\&.icon	bitmap source
+\&.idx	reference or datum-index file for hypertext
+\&	or database system
+\&.image	bitmap source
+\&.in	configuration template, especially for GNU Autoconf
+\&.info	files for the Emacs info browser
+\&.info-[0\-9]+	split info files
+\&.ins	LaTeX package install file for docstrip
+\&.itcl	itcl source code;
+\&	itcl ([incr Tcl]) is an OO extension of tcl
+\&.java	a Java source file
+\&.jpeg	Joint Photographic Experts Group format
+\&.jpg	poor man's \fI.jpeg\fP
+\&.kmap	\fBlyx\fP(1) keymap
+\&.l	equivalent to \fI.lex\fP or \fI.lisp\fP
+\&.lex	\fBlex\fP(1) or \fBflex\fP(1) files
+\&.lha	lharc archive
+\&.lib	Common-Lisp library
+\&.lisp	Lisp source
+\&.ln	files for use with \fBlint\fP(1)
+\&.log	log file, in particular produced by TeX
+\&.lsm	Linux Software Map entry
+\&.lsp	Common-Lisp source
+\&.lzh	lharc archive
+\&.m	Objective-C source code
+\&.m4	\fBm4\fP(1) source
+\&.mac	macro files for various programs
+\&.man	manual page (usually source rather than formatted)
+\&.map	map files for various programs
+\&.me	Nroff source using the me macro package
+\&.mf	Metafont (font generator for TeX) source
+\&.mgp	MagicPoint file
+\&.mm	sources for \fBgroff\fP(1) in mm - format
+\&.mo	Message catalog binary file
+\&.mod	Modula-2 source for implementation modules
+\&.mov	(quicktime) movie
+\&.mp	Metapost source
+\&.mp2	MPEG Layer 2 (audio) file
+\&.mp3	MPEG Layer 3 (audio) file
+\&.mpeg	movie file
+\&.o	object file
+\&.old	old or backup file
+\&.orig	backup (original) version of a file, from \fBpatch\fP(1)
+\&.out	output file, often executable program (a.out)
+\&.p	Pascal source
+\&.pag	dbm data base data file
+\&.patch	file differences for \fBpatch\fP(1)
+\&.pbm	portable bitmap format
+\&.pcf	X11 font files
+\&.pdf	Adobe Portable Data Format
+\&	(use Acrobat/\fBacroread\fP or \fBxpdf\fP)
+\&.perl	Perl source (see .ph, .pl, and .pm)
+\&.pfa	PostScript font definition files, ASCII format
+\&.pfb	PostScript font definition files, binary format
+\&.pgm	portable greymap format
+\&.pgp	PGP binary data
+\&.ph	Perl header file
+\&.php	PHP program file
+\&.php3	PHP3 program file
+\&.pid	File to store daemon PID (e.g., crond.pid)
+\&.pl	TeX property list file or Perl library file
+\&.pm	Perl module
+\&.png	Portable Network Graphics file
+\&.po	Message catalog source
+\&.pod	\fBperldoc\fP(1) file
+\&.ppm	portable pixmap format
+\&.pr	bitmap source
+\&.ps	PostScript file
+\&.py	Python source
+\&.pyc	compiled python
+\&.qt	quicktime movie
+\&.r	RATFOR source (obsolete)
+\&.rej	patches that \fBpatch\fP(1) couldn't apply
+\&.rpm	RPM software package
+\&.rtf	Rich Text Format file
+\&.rules	rules for something
+\&.s	assembler source
+\&.sa	stub libraries for a.out shared libraries
+\&.sc	\fBsc\fP(1) spreadsheet commands
+\&.scm	Scheme source code
+\&.sed	sed source file
+\&.sgml	SGML source file
+\&.sh	\fBsh\fP(1) scripts
+\&.shar	archive created by the \fBshar\fP(1) utility
+\&.so	Shared library or dynamically loadable object
+\&.sql	SQL source
+\&.sqml	SQML schema or query program
+\&.sty	LaTeX style files
+\&.sym	Modula-2 compiled definition modules
+\&.tar	archive created by the \fBtar\fP(1) utility
+\&.tar.Z	tar(1) archive compressed with \fBcompress\fP(1)
+\&.tar.bz2	tar(1) archive compressed with \fBbzip2\fP(1)
+\&.tar.gz	tar(1) archive compressed with \fBgzip\fP(1)
+\&.taz	tar(1) archive compressed with \fBcompress\fP(1)
+\&.tcl	tcl source code
+\&.tex	TeX or LaTeX source
+\&.texi	equivalent to \fI.texinfo\fP
+\&.texinfo	Texinfo documentation source
+\&.text	text file
+\&.tfm	TeX font metric file
+\&.tgz	tar archive compressed with \fBgzip\fP(1)
+\&.tif	poor man's \fI.tiff\fP
+\&.tiff	Tagged Image File Format
+\&.tk	tcl/tk script
+\&.tmp	temporary file
+\&.tmpl	template files
+\&.txt	equivalent to \fI.text\fP
+\&.uu	equivalent to \fI.uue\fP
+\&.uue	binary file encoded with \fBuuencode\fP(1)
+\&.vf	TeX virtual font file
+\&.vpl	TeX virtual property list file
+\&.w	Silvio Levi's CWEB
+\&.wav	wave sound file
+\&.web	Donald Knuth's WEB
+\&.wml	Source file for Web Meta Language
+\&.xbm	X11 bitmap source
+\&.xcf	GIMP graphic
+\&.xml	eXtended Markup Language file
+\&.xpm	X11 pixmap source
+\&.xs	Perl xsub file produced by h2xs
+\&.xsl	XSL stylesheet
+\&.y	\fByacc\fP(1) or \fBbison\fP(1) (parser generator) files
+\&.z	File compressed using \fBpack\fP(1) (or an old \fBgzip\fP(1))
+\&.zip	\fBzip\fP(1) archive
+\&.zoo	\fBzoo\fP(1) archive
+\&\(ti	Emacs or \fBpatch\fP(1) backup file
+\&rc	startup (`run control') file, e.g., \fI.newsrc\fP
 .TE
 .SH STANDARDS
 General UNIX conventions.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [BUG] gropdf, tbl: Completely broken table (was: Ping^1: Chapters of the manual (was: Bug#1018737: ...))

[Deri]

On Saturday, 17 December 2022 16:08:30 GMT G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2022-12-17T14:19:55+0100, Alejandro Colomar wrote:
> > Another bug report (but not about the script; this seems to be about
> > tbl(1) interaction with gropdf(1), I guess):
> > 
> > <http://chuzzlewit.co.uk/LinuxManBook.pdf#pdf%3Abm11813>
> 
> The suffixes(7) page, which I've managed to never see in 25 years as a
> GNU/Linux user!  Ah, well.
> 
> Dude, I'm friggin' _trying_ to get groff ready for 1.23.0.rc2 and you
> nerd-snipe me with this huge list of things that hasn't been updated in
> twenty years and has all kinds of fiddly little things wrong with it--
> this of course constitutes an OCD emergency for me!

Hi Alex,

This is a bug in my perl script which assembles the Linux Manpage Book, 
nothing to do with groff, tbl or gropdf, just a bad habit I have of scrubbing 
leading spaces before parsing a line, normally fine, but disastrous when the 
space is intended to protect a full stop being the first character.

For this reason, if you find issues with the book it probably is not relevent 
to the groff list, since it is more likely to be an issue with code which is 
just a few hours old. Any faults, or changes you would like, please send to 
me, since it is not relevent to the groff list.

Cheers 

Deri

Re: [BUG] gropdf, tbl: Completely broken table (was: Ping^1: Chapters of the manual (was: Bug#1018737: ...))

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 993 bytes --]

Hi Deri,

On 12/17/22 22:26, Deri wrote:
> Hi Alex,
> 
> This is a bug in my perl script which assembles the Linux Manpage Book,
> nothing to do with groff, tbl or gropdf, just a bad habit I have of scrubbing
> leading spaces before parsing a line, normally fine, but disastrous when the
> space is intended to protect a full stop being the first character.

Ahh, makes sense.

I thought it could be a bug in groff, since I had seen the same issue last year, 
I think with grohtml (but I'm talking from memory).  Maybe Branden remembers.

> 
> For this reason, if you find issues with the book it probably is not relevent
> to the groff list, since it is more likely to be an issue with code which is
> just a few hours old. Any faults, or changes you would like, please send to
> me, since it is not relevent to the groff list.

Understood!

I'm impatient to see that script :)

Cheers,

Alex

> 
> Cheers
> 
> Deri

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [BUG] gropdf, tbl: Completely broken table

[Ralph Corderoy]

Hi Branden,

> The suffixes(7) page, which I've managed to never see in 25 years as a
> GNU/Linux user!

Me neither.

        .text        │ text file
        .txt         │ equivalent to .text

I don't recall seeing .text used as it's the default on Unix.
.txt is an import from foreign lands.

    BUGS
	This list is not exhaustive.

Just delete the page and anything that refers to it.  Bug fixed.
Either the user has the Internet, which is exhaustive, or they're savvy
enough to use a system without the Internet and don't need suffixes(7).

-- 
Cheers, Ralph.

Re: [BUG] gropdf, tbl: Completely broken table

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1493 bytes --]

Hi Ralph!

On 12/18/22 06:49, Ralph Corderoy wrote:
> Hi Branden,
> 
>> The suffixes(7) page, which I've managed to never see in 25 years as a
>> GNU/Linux user!
> 
> Me neither.

Me neither.  I just found it because in the PDF it was next to standards(7), 
IIRC. :)

> 
>          .text        │ text file
>          .txt         │ equivalent to .text
> 
> I don't recall seeing .text used as it's the default on Unix.
> .txt is an import from foreign lands.

I sometimes use .txt for some notes or ASCII art, just to remind myself when I 
see the file months or years after that it's just text, as opposed to for 
example a script, for which I don't use extensions.  Directory organization 
would be more useful, but we all know that when you write something fast such as 
text notes, you don't always follow the best organization...

> 
>      BUGS
> 	This list is not exhaustive.
> 
> Just delete the page and anything that refers to it.  Bug fixed.
> Either the user has the Internet, which is exhaustive, or they're savvy
> enough to use a system without the Internet and don't need suffixes(7).

But now that I know it, it's an interesting thing to know.  Web search engines 
sometimes (more often than not) disappoint me; especially those that don't track 
me.  Having the page around can be useful.  I'll try to update with whatever new 
extension I meet and is not documented.

Cheers,

Alex


-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [BUG] gropdf, tbl: Completely broken table (was: Ping^1: Chapters of the manual (was: Bug#1018737: ...))

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 5051 bytes --]

Hi Branden,

On 12/17/22 17:08, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2022-12-17T14:19:55+0100, Alejandro Colomar wrote:
>> Another bug report (but not about the script; this seems to be about
>> tbl(1) interaction with gropdf(1), I guess):
>>
>> <http://chuzzlewit.co.uk/LinuxManBook.pdf#pdf%3Abm11813>
> 
> The suffixes(7) page, which I've managed to never see in 25 years as a
> GNU/Linux user!  Ah, well.
> 
> Dude, I'm friggin' _trying_ to get groff ready for 1.23.0.rc2 and you
> nerd-snipe me with this huge list of things that hasn't been updated in
> twenty years and has all kinds of fiddly little things wrong with it--
> this of course constitutes an OCD emergency for me!
> 
> https://xkcd.com/356/

:D

BTW, how is the status of 1.23.0?  How many RC bugs are there?  Are they growing 
faster than they are eaten by birds?  :P

> 
>> Running all the linters I know doesn't trigger any warnings on the
>> page source:
> 
> That tbl(1) source isn't invalid but it is pretty weird.
> 
> I tend to agree that there is a gropdf(1) bug here, as grops(1) handles
> the same input fine.  But Deri is the real expert and I will let him
> speak to that.
> 
> I'm attaching a patch that does three things:
> 
> 1. Removes the hack to shut up warnings from grotty(1).  This was indeed
>     a bug, it's been around forever (possibly since ~1990), and it is
>     fixed in groff Git.  Expect that in 1.23.0.  man-db man(1) conceals
>     these diagnostic messages anyway.
> 
>     https://savannah.gnu.org/bugs/index.php?63449
> 
> 2. Stops using leading spaces in table entries.  This is a kind of weird
>     thing to do.  The likely reason is that the table author(s) had a ton
>     of entries that started with dots (the *roff control character) and
>     didn't know to prefix them with the *roff dummy character (`\&`) to
>     keep them from being interpreted as requests or macro calls.  The
>     tbl(1) page in groff 1.23.0 explicitly documents this use (the old
>     one seems to have expected the reader to have access to CSTR #49 by
>     Lesk).
> 
>      Rows of table entries can be interleaved with groff control lines;
>      these do not count as table data.  On such lines the default control
>      character (.) must be used (and not changed); the no‐break control
>      character is not recognized.  To start the first table entry in a
>      row with a dot, precede it with the token \&.
> 
> 3. I added the dummy character even on "continuation" lines where a
>     description overran.  This does no damage since the tab character
>     remains there as an entry separator and the dummy character by itself
>     is harmless as a marker of an empty table entry.  I even recommend
>     this in the GNU tbl 1.23.0 man page; it's much nicer for people whose



>     text editors don't visibly highlight tabs.

BTW, I've seen in groff really bad cases of broken indentation where some lines 
use tabs, others use spaces, and others use a mix.  What's the coding style 
regarding tabs in groff source code?  I want to know in case I send a patch some 
day.

> 
> A _more_ idiomatic thing to do would be to use a spanning table
> entry `\^` for rows where the description get continued, but that makes
> no practical difference for a simple table layout like this one.
> 
> More idiomatic still, and well worth considering for the future, is
> setting _all_ of these descriptions in text blocks.  This table looks to
> me like it was laid out for an 80-column terminal with the excessively
> long descriptions manually broken.  This looks suboptimal when typeset
> and will look ridiculous on a wide terminal.

Yep.  Probably I'll do that; but (probably) not soon.

> 
> Also, use of a text block enables the employment of man(7) macros
> instead of font selection escape sequences to change the typeface, and,
> importantly for the near Linux man-pages future, use of the new `MR`
> macro to cross reference the many pages referred to in these
> descriptions.
> 
> I didn't pursue further revision along either of these lines because the
> as I look at these the entries, the intensity of my urge to do a
> top-to-bottom revision fixing the many infelicities and a few outright
> errors increases exponentially with time.  There is even at least one
> unescaped hyphen!  🤯 >
> Regrettably, if a moderately experienced GNU/Linux user has gone 25
> years without seeing this page, likely many others will go 25 more
> without seeing it.  A good intro(1) page would cross reference it,
> aiding the novice.

But if the intro(*) page references _everything_, then it would be a huge page 
(there are thousands of pages in the Linux man-pages).  Although, in the PDF, 
I'd like to have an index.  That might help.

> 
> Unofficial patch attached.

Do you like the patch?  Should I apply it, or is it just a draft?

> 
> Regards,
> Branden

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

groff 1.23.0.rc2 status report (was: [BUG] gropdf, tbl: Completely broken table)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 13299 bytes --]

Hi Alex,

At 2022-12-18T12:46:59+0100, Alejandro Colomar wrote:
> BTW, how is the status of 1.23.0?

Getting closer.  Details below.

> How many RC bugs are there?

Five, but one of these is basically "please release", so 4 of
development work and one of release engineering, which is partially in
Bertrand's hands.

Savannah's URLs are stupefyingly long, but I have an RC
[release-critical] bug dashboard for you.[1]

One of the development RC bugs is a documentation issue that I don't
plan to tackle until _after_ rc2 [release candidate 2] (unless Bertrand
is unavailable when I tell him I'm done hacking).  Because I will need
_something_ do while waiting for build and field test reports to come
back so I don't chew my fingers off.

So that's 3 issues.

Number one:

[mdoc] align rendering parameters with man(7)
https://savannah.gnu.org/bugs/index.php?62926

I noticed some inconsistencies between the way groff man(7) and groff
mdoc(7) format pages--ones that can't be attributed simply to the
different underlying macro languages.  To attack that problem I needed
to do something I had been putting off for 5 years, which is to learn
mdoc(7).  I think I now know enough mdoc(7) to write a man page of
average complexity in it without needing the package's own man page
open.  As I noted somewhere (in email or in an editorial comment at the
end of a commit message, maybe), groff mdoc(7) as it was in 1.22.4 "uses
too much Courier and too much bold".  I have significant esthetic
reservations about inline switches to Courier, particularly for syntax
synopses where the font falls back automatically to Times for
punctuation characters like brackets, but "variable" content is also in
Courier italic.  This combination makes the interword spacing wildly
inconsistent, and it can be hard to tell whether you're supposed to type
a space or not.  This is not helpful.

I plan to fiddle various groff mdoc(7) internal register settings so
that Courier is only used with ".Bd -literal" and ".Bd -literal".  These
are comparable to groff man(7)'s EX/EE regions.  Some more state
registers like the Booleans that identify whether you're "in" a "Name"
or "Synopsis" section, for instance, may be necessary.  But maybe not.
If I can keep the numerous strings that are used to customize the
styling of dozens of mdoc(7) macros under control by confining them to
switching font _styles_ rather than the family as well, this might be
low-effort.

Probably not a lot of this will be visible to terminal-only users.

A side effect of learning more about mdoc(7) is that I've fixed some
bugs in our implementation, including one that was documented in
4.3BSD-Reno.[2]

Number two:

[mdoc] handle rendering option strings and registers as man(7) does
https://savannah.gnu.org/bugs/index.php?63046

There is partial overlap with the previous bug.  It refers to the
registers and strings you can said to configure various rendering
parameters, long documented in groff man(7)'s "Options" section.

The idea is that when batch-rendering a collection of man(7) and mdoc(7)
pages, which didn't work in groff 1.22.4 or earlier, you want both macro
packages to honor the rendering parameters you specify.  groff mdoc(7)
has been falling farther out of sync with groff man(7) for years at this
point.  This one's almost done: all that is left is "HF", "MF", and "U".

Number three:

bug #62933: [man] produce hyperlinks in PDF output
https://savannah.gnu.org/bugs/index.php?62933

We've got man page cross-reference hyperlinks but, weirdly, not regular
URL support in groff_man(7).  To my dismay this doesn't appear to be
trivial.  Whoever came up with the "pdfhref" macro had Unix
command-line-itis, and constructed an interface that looked like that
instead of something you might use in a *roff document.  The problem is
that it expects the URL and, particularly, the link text to be macro
arguments.  This is a violent impedance mismatch with the way groff
man(7)'s email and web macros were set up to work; they format the link
text in a diversion.  Diversions and strings are not the same thing.
(Try putting diversion contents into a device control command and you
will rapidly be deafened by the screams of a thousand damned "can't
output node in transparent throughput" souls.)  So to solve this I have
to learn crazy stuff about PDFmark hotspots and how their boundaries are
computed, and then the thought of what happens when the link text
crosses a trap boundary (like a page break) causes the blood to drain
from my face.  At some point I may have to tell Regis I need to phone a
friend,[3] and I'll crawl to Deri the PDF wizard to knock some clues
into my head.

Then, though the bug doesn't say this, I have to do it all over again
for mdoc(7), because that doesn't have support for this, either.  On the
bright side, I have a much better grasp of mdoc(7)'s internals than I
used to, and pretty much everything to do with page location traps is
the same now anyway, thanks to my incessant meddling^W^W^Wthe problems I
had to solve to get batch-rendering working.

By the way, we're up to 158 automated test scripts and 398 bugs fixed
since groff 1.22.4.  I have another statistic on changed files at the
end of this message.

> Are they growing faster than they are eaten by birds?  :P

No.  They've been slowly but steadily dwindling for the last 2-3 months.

In the meantime I continue to fix documentation problems as I spot them,
and fix the occasional "bonus bug" when someone reports one I recently
introduced.  (John Gardner found one in my change to .Nm, the
4.3BSD-Reno bug fix mentioned above.)  Also, today I pushed a fix for
what was the oldest open bug against groff, a problem with mm(7)'s
memorandum type 5.  Werner filed that in 2008.

I've also started to revise the groff_mdoc(7) man page itself.

A possible project for after groff 1.23.0 final is to write an essay
about how mdoc(7) is over-hyped and the grass is not greener over there.
It has some nice properties, but some perverse ones too.  Some people on
this mailing list over the years have suggested that the groff project's
2014 Mission Statement commits us to promoting mdoc(7) over man(7), and
doing what we can to erase the horrid crapware that is man(7).  The
document says nothing of the sort.[4]

I am beginning to learn that passionate mdoc(7) proponents are not
reliable witnesses.

> BTW, I've seen in groff really bad cases of broken indentation where
> some lines use tabs, others use spaces, and others use a mix.  What's
> the coding style regarding tabs in groff source code?  I want to know
> in case I send a patch some day.

It varies from one part of the source tree to another.  :-/  Most of
James Clark's C++ is pretty consistent.  It's two-space "tab" stops with
literal tab characters replacing every 8 spaces.  Emacs local variables
and Vim modeline info is available in many files; I tend to add the
latter the first time I work on a file, because I get annoyed when my
editor doesn't do the right thing.

Keep in mind that the stuff in contrib/ often has its own conventions.
Even though a lot of that is no longer maintained by its contributor, I
seldom feel the urge to force a change in indentation style on anything.

Personally I'm more frequently annoyed by the inconsistency in _macro
package_ indentation conventions.

> > More idiomatic still, and well worth considering for the future, is
> > setting _all_ of these descriptions in text blocks.  This table
> > looks to me like it was laid out for an 80-column terminal with the
> > excessively long descriptions manually broken.  This looks
> > suboptimal when typeset and will look ridiculous on a wide terminal.
> 
> Yep.  Probably I'll do that; but (probably) not soon.

I see no reason to hurry.  Clearly few people read the suffixes(7) page
or they'd have said something about what a time capsule it is.

> But if the intro(*) page references _everything_, then it would be a
> huge page (there are thousands of pages in the Linux man-pages).

That's true, but consider the topic at issue--pieces of file names.
It's hard to crawl, let alone walk, on a Unix system without some grasp
of file manipulation.  This is the system that brought us the idea that
"everything is a file" (even if Plan 9 did better at delivering on the
promise).

There may not be much point linking to it today, but ping me to pick a
fight with suffixes(7) in six months.  :)

> Although, in the PDF, I'd like to have an index.  That might help.

Early editions of the Unix manual had permuted indexes.  I haven't yet
developed any practical experience with preparing indexes of any sort
for *roff documents.  That's something I'd like to remedy.  One thing I
don't like is the SunOS man(7) convention of littering the page source
with `IX` macro calls (behavior that pod2man faithfully replicates).
They don't format anything, so like 4.2BSD ms(7) section headings they
duplicate text someone has already typed, and nothing, or nearly
nothing, _reads_ these IX tags to do something useful with them.  They
thus simply become clutter.

Remember my DC/TG proposal I re-raised the other day?  Anything you'd
want to tag as having semantic value is a sure-fire good candidate for
indexing.

> > Unofficial patch attached.
> 
> Do you like the patch?

"Like" is a strong word.  It makes the page less weird.  I'll stand by
it, if that's what you mean.

> Should I apply it, or is it just a draft?

Go right ahead.  The real work is in auditing that table line by line.

I saw reference to some compression program called "yabba" and I
thought, "what the Hutt?"

Regards,
Branden

[1] https://savannah.gnu.org/bugs/index.php?go_report=Apply&group=groff&func=&set=custom&msort=0&report_id=225&advsrch=0&bug_id=&summary=&submitted_by=0&resolution_id=0&assigned_to=0&bug_group_id=0&status_id=1&severity=0&category_id=0&plan_release_id=103&history_search=0&history_field=0&history_event=modified&history_date_dayfd=19&history_date_monthfd=12&history_date_yearfd=2022&chunksz=50&spamscore=5&boxoptionwanted=1#options

[2] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=0d85615c62d07b028b972dff38bfa7589dad8cf1
[3] obligatory obscure cultural reference
[4] https://www.gnu.org/software/groff/groff-mission-statement.html

For fun I thought I'd see what the diffstat between 1.22.4 and master
looked like, and filtered out files with fewer than 1,000 lines of diff.

 ChangeLog                                          | 18832 +++++++++++++++----
 ChangeLog.122                                      |  5331 ++++++
 NEWS                                               |  2302 ++-
 contrib/glilypond/glilypond.pl                     |  1296 +-
 contrib/groffer/groffer.1.man                      |  3822 ----
 contrib/groffer/main_subs.pl                       |  2132 ---
 contrib/mm/groff_mm.7.man                          |  2444 ++-
 contrib/mom/om.tmac                                |  2339 ++-
 contrib/rfc1345/rfc1345.tmac                       |  1705 ++
 doc/groff.texi                                     | 18782 +++++++++---------
 doc/meref.me                                       |  2241 ---
 doc/meref.me.in                                    |  2439 +++
 doc/ms.ms                                          |  4378 +++++
 m4/groff.m4                                        |  1397 +-
 man/groff.7.man                                    |  9025 +++++----
 man/groff_char.7.man                               |  2992 +--
 man/groff_diff.7.man                               |  5039 +++--
 man/groff_font.5.man                               |  1252 +-
 man/groff_tmac.5.man                               |  1575 +-
 man/roff.7.man                                     |  2921 ++-
 src/devices/grohtml/post-html.cpp                  |  1282 +-
 src/devices/gropdf/gropdf.1.man                    |  1008 +-
 src/devices/grops/grops.1.man                      |  1615 +-
 src/preproc/eqn/eqn.1.man                          |  1621 +-
 src/preproc/pic/pic.1.man                          |  1196 +-
 src/preproc/refer/refer.1.man                      |  1260 +-
 src/preproc/tbl/tbl.1.man                          |  2404 ++-
 src/roff/groff/groff.1.man                         |  2844 +--
 src/roff/grog/subs.pl                              |  1266 --
 src/roff/troff/input.cpp                           |  1424 +-
 src/roff/troff/troff.1.man                         |  1012 +-
 tmac/an.tmac                                       |  1553 +-
 tmac/{doc.tmac-u => doc.tmac}                      |  1218 +-
 tmac/groff_man.7.man                               |  2613 ---
 tmac/groff_man.7.man.in                            |  4187 +++++
 tmac/groff_mdoc.7.man                              |  3470 ++--
 tmac/groff_ms.7.man                                |  3508 ++--
 tmac/hyphenex.us                                   |  1454 --
 960 files changed, 126084 insertions(+), 72911 deletions(-)

I hope people will take me seriously when I suggest that groff's
documentation has undergone revision.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: groff 1.23.0.rc2 status report (was: [BUG] gropdf, tbl: Completely broken table)

[Deri]

On Monday, 19 December 2022 05:32:45 GMT G. Branden Robinson wrote:
> Number three:
> 
> bug #62933: [man] produce hyperlinks in PDF output
> https://savannah.gnu.org/bugs/index.php?62933
> 
> We've got man page cross-reference hyperlinks but, weirdly, not regular
> URL support in groff_man(7).  To my dismay this doesn't appear to be
> trivial.  Whoever came up with the "pdfhref" macro had Unix
> command-line-itis, and constructed an interface that looked like that
> instead of something you might use in a *roff document. 

Hi Branden,

To be fair, he had little choice since the api was designed by adobe:-

https://opensource.adobe.com/dc-acrobat-sdk-docs/acrobatsdk/pdfs/
acrobatsdk_pdfmark.pdf

> The problem is
> that it expects the URL and, particularly, the link text to be macro
> arguments.  This is a violent impedance mismatch with the way groff
> man(7)'s email and web macros were set up to work; they format the link
> text in a diversion.  Diversions and strings are not the same thing.
> (Try putting diversion contents into a device control command and you
> will rapidly be deafened by the screams of a thousand damned "can't
> output node in transparent throughput" souls.)  

The .URL, .MTO and .FTO macros in www.tmac should be easy to convert to using 
.pdfhref, the difficult one is the .UR/.UE pair from an.tmac you are talking 
about.

In order to solve this to get all man pages as fully linked pdfs - I cheated! 
I used a sort of pre-gropdf which changed the mail and email links to pdfhref 
calls. So I don't think I can help much with this. However, this is the code I 
use to "clean" a string, may be helpful:-

.         ds pdf:cleaned \\$*
.         ev pdfcln
.         tr \[em]-
.         nf
.         box pdf:clean
.         nop \\$*
.         fl
.         box
.         chop pdf:clean
.         asciify pdf:clean
.         length pdf:clean:len \\*[pdf:clean]
.         ds pdf:cleaned \\*[pdf:clean]
.         rm pdf:clean
.         ev
.         tr \[em]\[em]

There may be much better ways of doing it!

> So to solve this I have
> to learn crazy stuff about PDFmark hotspots and how their boundaries are
> computed, and then the thought of what happens when the link text
> crosses a trap boundary (like a page break) causes the blood to drain
> from my face.  

Don't worry, the gropdf man page says:-

If you are using page traps to produce headings, footings, etc., you need to 
use these in case a ‘hotspot’ crosses a page boundary, otherwise any text 
output by the heading or footing macro will be marked as part of the ‘hot 
spot’. To stop this happening just place ‘.pdfmarksuspend’ and 
‘.pdfmarkrestart’ at the start and end of the page trap macro, respectively. 
(These are just convenience macros which emit the \X code. These macros must 
only be used within page traps.)

If you look at om.tmac you will see these used in the FOOTER macro. I'm not 
sure how -mpdfmark handles it since these are gropdf extensions.

Cheers

Deri

> At some point I may have to tell Regis I need to phone a
> friend,[3] and I'll crawl to Deri the PDF wizard to knock some clues
> into my head.
> 
> Then, though the bug doesn't say this, I have to do it all over again
> for mdoc(7), because that doesn't have support for this, either.  On the
> bright side, I have a much better grasp of mdoc(7)'s internals than I
> used to, and pretty much everything to do with page location traps is
> the same now anyway, thanks to my incessant meddling^W^W^Wthe problems I
> had to solve to get batch-rendering working.
> 

Re: groff 1.23.0.rc2 status report (was: [BUG] gropdf, tbl: Completely broken table)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4584 bytes --]

Hi Branden,

On 12/19/22 06:32, G. Branden Robinson wrote:

>>> Unofficial patch attached.
>>
>> Do you like the patch?
> 
> "Like" is a strong word.  It makes the page less weird.  I'll stand by
> it, if that's what you mean.
> 
>> Should I apply it, or is it just a draft?
> 
> Go right ahead.  The real work is in auditing that table line by line.

Would you mind sending a patch that I can apply with git?  I could manually edit 
the file you attached, but I'm feeling lazy for that :\

> 
> I saw reference to some compression program called "yabba" and I
> thought, "what the Hutt?"

:)

I have a patch for an extension that wasn't covered by this file.  I'm guessing 
pkg-config wasn't invented when this page was written?  That's really old...  It 
seems the page goes back to man-pages 1.0 (with some additions later; mostly in 
1.21).

Cheers,

Alex

> 
> Regards,
> Branden
> 
> [1] https://savannah.gnu.org/bugs/index.php?go_report=Apply&group=groff&func=&set=custom&msort=0&report_id=225&advsrch=0&bug_id=&summary=&submitted_by=0&resolution_id=0&assigned_to=0&bug_group_id=0&status_id=1&severity=0&category_id=0&plan_release_id=103&history_search=0&history_field=0&history_event=modified&history_date_dayfd=19&history_date_monthfd=12&history_date_yearfd=2022&chunksz=50&spamscore=5&boxoptionwanted=1#options
> 
> [2] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=0d85615c62d07b028b972dff38bfa7589dad8cf1
> [3] obligatory obscure cultural reference
> [4] https://www.gnu.org/software/groff/groff-mission-statement.html
> 
> For fun I thought I'd see what the diffstat between 1.22.4 and master
> looked like, and filtered out files with fewer than 1,000 lines of diff.
> 
>   ChangeLog                                          | 18832 +++++++++++++++----
>   ChangeLog.122                                      |  5331 ++++++
>   NEWS                                               |  2302 ++-
>   contrib/glilypond/glilypond.pl                     |  1296 +-
>   contrib/groffer/groffer.1.man                      |  3822 ----
>   contrib/groffer/main_subs.pl                       |  2132 ---
>   contrib/mm/groff_mm.7.man                          |  2444 ++-
>   contrib/mom/om.tmac                                |  2339 ++-
>   contrib/rfc1345/rfc1345.tmac                       |  1705 ++
>   doc/groff.texi                                     | 18782 +++++++++---------
>   doc/meref.me                                       |  2241 ---
>   doc/meref.me.in                                    |  2439 +++
>   doc/ms.ms                                          |  4378 +++++
>   m4/groff.m4                                        |  1397 +-
>   man/groff.7.man                                    |  9025 +++++----
>   man/groff_char.7.man                               |  2992 +--
>   man/groff_diff.7.man                               |  5039 +++--
>   man/groff_font.5.man                               |  1252 +-
>   man/groff_tmac.5.man                               |  1575 +-
>   man/roff.7.man                                     |  2921 ++-
>   src/devices/grohtml/post-html.cpp                  |  1282 +-
>   src/devices/gropdf/gropdf.1.man                    |  1008 +-
>   src/devices/grops/grops.1.man                      |  1615 +-
>   src/preproc/eqn/eqn.1.man                          |  1621 +-
>   src/preproc/pic/pic.1.man                          |  1196 +-
>   src/preproc/refer/refer.1.man                      |  1260 +-
>   src/preproc/tbl/tbl.1.man                          |  2404 ++-
>   src/roff/groff/groff.1.man                         |  2844 +--
>   src/roff/grog/subs.pl                              |  1266 --
>   src/roff/troff/input.cpp                           |  1424 +-
>   src/roff/troff/troff.1.man                         |  1012 +-
>   tmac/an.tmac                                       |  1553 +-
>   tmac/{doc.tmac-u => doc.tmac}                      |  1218 +-
>   tmac/groff_man.7.man                               |  2613 ---
>   tmac/groff_man.7.man.in                            |  4187 +++++
>   tmac/groff_mdoc.7.man                              |  3470 ++--
>   tmac/groff_ms.7.man                                |  3508 ++--
>   tmac/hyphenex.us                                   |  1454 --
>   960 files changed, 126084 insertions(+), 72911 deletions(-)
> 
> I hope people will take me seriously when I suggest that groff's
> documentation has undergone revision.

Wow!

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

patching suffixes(7) (was: groff 1.23.0.rc2 status report)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 762 bytes --]

[dropping Deri and groff@]

At 2022-12-19T17:39:37+0100, Alejandro Colomar wrote:
> Would you mind sending a patch that I can apply with git?  I could
> manually edit the file you attached, but I'm feeling lazy for that :\

Damn.  Our lazinesses are duelling.  :P

Yes, I'll do it.  Maybe today, maybe later this week.

> I have a patch for an extension that wasn't covered by this file.  I'm
> guessing pkg-config wasn't invented when this page was written?
> That's really old...  It seems the page goes back to man-pages 1.0
> (with some additions later; mostly in 1.21).

The last person credited as changing it in the file itself, as you no
doubt saw, was David Wheeler (no, the other one) in 2000.  I think that
does antedate pkg-config.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: patching suffixes(7) (was: groff 1.23.0.rc2 status report)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2328 bytes --]

Hi Branden,

On 12/19/22 17:59, G. Branden Robinson wrote:
> [dropping Deri and groff@]
> 
> At 2022-12-19T17:39:37+0100, Alejandro Colomar wrote:
>> Would you mind sending a patch that I can apply with git?  I could
>> manually edit the file you attached, but I'm feeling lazy for that :\
> 
> Damn.  Our lazinesses are duelling.  :P

:P

I actually wonder how producing such a diff was simpler than just copying the 
output of git diff...

BTW, I still plan releasing man-pages-6.02 in a two days, and feel confident 
enough about the string changes (modulo a few tweaks that I'll apply) to ship 
them in it.  If you have any comments about them, please voice them :)

> 
> Yes, I'll do it.  Maybe today, maybe later this week.

Sure.  I don't think we can say this is an RC bug 22 years after the page was 
last updated in actual content (rather than minor updates from Michael, mostly 
as part of global fixes).

> 
>> I have a patch for an extension that wasn't covered by this file.  I'm
>> guessing pkg-config wasn't invented when this page was written?
>> That's really old...  It seems the page goes back to man-pages 1.0
>> (with some additions later; mostly in 1.21).
> 
> The last person credited as changing it in the file itself, as you no
> doubt saw,

Actually, I didn't.  I'm so used to git log, that I usually forget to check page 
headers.  Especially now that I have access to the entire history (no authors, 
but at least versions and times).

BTW, I agree with you that the reversed history is a bit weird and confusing.  I 
thought of a new method that would connect both histories while keeping a 
forward history:

A separate orphan branch in normal order, starting at 1.0, which ends at 1.70. 
And then git allows merging orphan branches, so I can create a merge commit 
between both 1.70 commits, which of course is a no-op, but one that tells git 
where and how these branches join.

> was David Wheeler (no, the other one)

Didn't know of the other David Wheeler.

> in 2000.  I think that
> does antedate pkg-config.

According to wikipedia, pkg-config(1)'s initial release is also from 2000.  So, 
yes, probably it wasn't widely known at the time.

> 
> Regards,
> Branden

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

prehistory branch (was: patching suffixes(7) (was: groff 1.23.0.rc2 status report))

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 8658 bytes --]



On 12/19/22 20:10, Alejandro Colomar wrote:
> BTW, I agree with you that the reversed history is a bit weird and confusing.  I 
> thought of a new method that would connect both histories while keeping a 
> forward history:
> 
> A separate orphan branch in normal order, starting at 1.0, which ends at 1.70. 
> And then git allows merging orphan branches, so I can create a merge commit 
> between both 1.70 commits, which of course is a no-op, but one that tells git 
> where and how these branches join.

It was easy to reverse the history.  After renaming the old prehistory branch to 
prehistory-backwards, and creating an orphan branch, and manually picking the 
first two commits to see how it works (thus the tail(1) invokation), it's 
automated as:

$ git log prehistory-backwards \
   | grep ^commit \
   | cut -f2 -d' ' \
   | tail -n+3 \
   | while read hash; do
           git checkout $hash -- . \
        && git commit --reuse-message=$hash;
   done;

And after the merge, we have something with which I'm quite happy: connected 
forward histories.

Cheers,

Alex

---

*   6d57ebaa3 - Mon, 19 Dec 2022 20:48:29 +0100 (4 minutes ago) (HEAD -> prehistory)
|\            Merge prehistory and history - Alejandro Colomar
| * fea681daf - Wed, 3 Nov 2004 13:51:07 +0000 (18 years ago) (tag: man-pages-1.70)
|             Import of man-pages 1.70 - Michael Kerrisk
* 75d20cea9 - Wed, 3 Nov 2004 13:51:07 +0000 (18 years ago)
|           Import of man-pages 1.70 - Michael Kerrisk
* a2b66da59 - Tue, 12 Oct 2004 00:03:00 +0200 (18 years ago)
|           man-pages 1.69 - Krónos
* 4075cd91b - Sun, 10 Oct 2004 21:37:00 +0200 (18 years ago)
|           man-pages 1.68 - Krónos
* 9dbf677a6 - Fri, 21 May 2004 01:36:00 +0200 (19 years ago)
|           man-pages 1.67 - Krónos
* df824df6a - Sun, 8 Feb 2004 06:59:00 +0100 (19 years ago)
|           man-pages 1.66 - Krónos
* 13b644d56 - Tue, 20 Jan 2004 23:38:00 +0100 (19 years ago)
|           man-pages 1.65 - Krónos
* c5dea9423 - Sat, 29 Nov 2003 01:36:00 +0100 (19 years ago)
|           man-pages 1.64 - Krónos
* 3a84c9581 - Mon, 17 Nov 2003 02:05:00 +0100 (19 years ago)
|           man-pages 1.63 - Krónos
* 08c9c0382 - Fri, 14 Nov 2003 01:48:00 +0100 (19 years ago)
|           man-pages 1.62 - Krónos
* 4a78724b4 - Thu, 13 Nov 2003 02:57:00 +0100 (19 years ago)
|           man-pages 1.61 - Krónos
* efd33757d - Tue, 26 Aug 2003 00:26:00 +0200 (19 years ago)
|           man-pages 1.60 - Krónos
* 38b782a16 - Fri, 22 Aug 2003 02:29:00 +0200 (19 years ago)
|           man-pages 1.59 - Krónos
* 7cb7d2947 - Fri, 25 Jul 2003 00:46:00 +0200 (19 years ago)
|           man-pages 1.58 - Krónos
* f7bfea7fb - Fri, 18 Jul 2003 21:44:00 +0200 (19 years ago)
|           man-pages 1.57 - Krónos
* b73d73174 - Thu, 27 Feb 2003 23:16:00 +0100 (20 years ago)
|           man-pages 1.56 - Krónos
* 657c8b945 - Fri, 7 Feb 2003 19:39:00 +0100 (20 years ago)
|           man-pages 1.55 - Krónos
* 273524524 - Mon, 30 Dec 2002 06:33:00 +0100 (20 years ago)
|           man-pages 1.54 - Krónos
* 2cef28bcc - Mon, 26 Aug 2002 01:30:00 +0200 (20 years ago)
|           man-pages 1.53 - Krónos
* abe7cac51 - Mon, 22 Jul 2002 02:07:00 +0200 (20 years ago)
|           man-pages 1.52 - Krónos
* e5687e13a - Sat, 8 Jun 2002 01:19:00 +0200 (21 years ago)
|           man-pages 1.51 - Krónos
* dc2e98c72 - Thu, 30 May 2002 22:57:00 +0200 (21 years ago)
|           man-pages 1.50 - Krónos
* 9bb551f6d - Thu, 30 May 2002 02:51:00 +0200 (21 years ago)
|           man-pages 1.49 - Krónos
* 23b3c2c7b - Fri, 1 Mar 2002 00:07:00 +0100 (21 years ago)
|           man-pages 1.48 - Krónos
* 4ea5a4fe6 - Wed, 26 Dec 2001 22:02:00 +0100 (21 years ago)
|           man-pages 1.47 - Krónos
* 96e5242eb - Sun, 23 Dec 2001 23:36:00 +0100 (21 years ago)
|           man-pages 1.46 - Krónos
* edd7a0eb3 - Sat, 15 Dec 2001 04:36:00 +0100 (21 years ago)
|           man-pages 1.45 - Krónos
* 20991cf28 - Fri, 30 Nov 2001 23:46:00 +0100 (21 years ago)
|           man-pages 1.44 - Krónos
* 15ee6e691 - Tue, 23 Oct 2001 18:58:00 +0200 (21 years ago)
|           man-pages 1.43 - Krónos
* 21e69fb7d - Fri, 19 Oct 2001 03:16:00 +0200 (21 years ago)
|           man-pages 1.42 - Krónos
* 43ca8d2d9 - Sun, 14 Oct 2001 21:30:00 +0200 (21 years ago)
|           man-pages 1.41 - Krónos
* 2bcc3e5f9 - Tue, 25 Sep 2001 17:44:00 +0200 (21 years ago)
|           man-pages 1.40 - Krónos
* 9d5558f2f - Thu, 26 Jul 2001 01:35:00 +0200 (21 years ago)
|           man-pages 1.39 - Krónos
* 6cc11b2fd - Sun, 10 Jun 2001 01:24:00 +0200 (22 years ago)
|           man-pages 1.38 - Krónos
* 0f65afdb6 - Sat, 2 Jun 2001 00:35:00 +0200 (22 years ago)
|           man-pages 1.37 - Krónos
* bb479545e - Thu, 17 May 2001 22:00:00 +0200 (22 years ago)
|           man-pages 1.36 - Krónos
* a3504cd2d - Sun, 18 Mar 2001 17:32:00 +0100 (22 years ago)
|           man-pages 1.35 - Krónos
* 6f6da5fa7 - Sun, 24 Dec 2000 17:52:00 +0100 (22 years ago)
|           man-pages 1.34 - Krónos
* c26274e15 - Tue, 12 Dec 2000 04:27:00 +0100 (22 years ago)
|           man-pages 1.33 - Krónos
* c4abcc9ee - Mon, 11 Dec 2000 05:34:00 +0100 (22 years ago)
|           man-pages 1.32 - Krónos
* c9348fce0 - Sun, 13 Aug 2000 03:50:00 +0200 (22 years ago)
|           man-pages 1.31 - Krónos
* 91c9890e7 - Sun, 4 Jun 2000 16:40:00 +0200 (23 years ago)
|           man-pages 1.30 - Krónos
* 47aa69480 - Mon, 6 Mar 2000 01:54:00 +0100 (23 years ago)
|           man-pages 1.29 - Krónos
* 167a90543 - Sun, 28 Nov 1999 05:16:00 +0100 (23 years ago)
|           man-pages 1.28 - Krónos
* d892e04e9 - Thu, 11 Nov 1999 04:55:00 +0100 (23 years ago)
|           man-pages 1.27 - Krónos
* 255eb5033 - Tue, 24 Aug 1999 23:48:00 +0200 (23 years ago)
|           man-pages 1.26 - Krónos
* 794948d0e - Mon, 19 Jul 1999 12:36:00 +0200 (23 years ago)
|           man-pages 1.25 - Krónos
* 44724eefc - Tue, 15 Jun 1999 00:37:00 +0200 (24 years ago)
|           man-pages 1.24 - Krónos
* 516f00ab4 - Mon, 29 Mar 1999 13:04:00 +0200 (24 years ago)
|           man-pages 1.23 - Krónos
* c0304f168 - Fri, 27 Nov 1998 21:16:00 +0100 (24 years ago)
|           man-pages 1.22 - Krónos
* 66a5251af - Mon, 7 Sep 1998 01:47:00 +0200 (24 years ago)
|           man-pages 1.21 - Krónos
* dfe1914e9 - Sat, 13 Jun 1998 22:36:00 +0200 (25 years ago)
|           man-pages 1.20 - Krónos
* 76e5b8416 - Sun, 19 Apr 1998 23:53:00 +0200 (25 years ago)
|           man-pages 1.19 - Krónos
* 278efb55a - Mon, 8 Dec 1997 02:11:00 +0100 (25 years ago)
|           man-pages 1.18 - Krónos
* 354ac5c81 - Fri, 18 Jul 1997 13:16:00 +0200 (25 years ago)
|           man-pages 1.17 - Krónos
* 93d136064 - Sat, 31 May 1997 16:14:00 +0200 (26 years ago)
|           man-pages 1.16 - Krónos
* 34a43139d - Sun, 2 Feb 1997 02:55:00 +0100 (26 years ago)
|           man-pages 1.15 - Krónos
* 48ac737ed - Mon, 20 Jan 1997 23:15:00 +0100 (26 years ago)
|           man-pages 1.14 - Krónos
* de7496a42 - Wed, 6 Nov 1996 02:51:00 +0100 (26 years ago)
|           man-pages 1.13 - Krónos
* 091c327d0 - Tue, 23 Jul 1996 12:46:00 +0200 (26 years ago)
|           man-pages 1.12a - Krónos
* b745d0fc7 - Tue, 23 Jul 1996 00:47:00 +0200 (26 years ago)
|           man-pages 1.12 - Krónos
* 308a405f0 - Mon, 15 Apr 1996 01:38:00 +0200 (27 years ago)
|           man-pages 1.11 - Krónos
* e1ba732be - Tue, 16 Jan 1996 00:26:00 +0100 (27 years ago)
|           man-pages 1.10 - Krónos
* d08a203d2 - Tue, 19 Sep 1995 17:13:00 +0200 (27 years ago)
|           man-pages 1.9 - Krónos
* 52cbc5589 - Tue, 15 Aug 1995 21:55:00 +0200 (27 years ago)
|           man-pages 1.8 - Krónos
* a9aefc28b - Sun, 23 Jul 1995 09:33:00 +0200 (27 years ago)
|           man-pages 1.7 - Krónos
* 059dcc4ba - Mon, 12 Jun 1995 01:22:00 +0200 (28 years ago)
|           man-pages 1.6 - Krónos
* feb5d965c - Sun, 26 Feb 1995 23:25:00 +0100 (28 years ago)
|           man-pages 1.5 - Krónos
* d1777189d - Wed, 14 Sep 1994 19:16:00 +0200 (28 years ago)
|           man-pages 1.4 - Krónos
* e6e3f5d0c - Sun, 3 Jul 1994 22:02:00 +0200 (28 years ago)
|           man-pages 1.3 - Krónos
* af6024498 - Mon, 29 Nov 1993 00:00:00 +0100 (29 years ago)
|           man-pages 1.2 - Krónos
* fbed6a6ed - Mon, 11 Oct 1993 00:00:00 +0100 (29 years ago)
|           man-pages 1.0 - Krónos
* c8eee6c3c - Mon, 19 Dec 2022 20:15:55 +0100 (36 minutes ago)
             void - Alejandro Colomar

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: prehistory branch (was: patching suffixes(7) (was: groff 1.23.0.rc2 status report))

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1569 bytes --]

[self-correction]

On 12/19/22 20:54, Alejandro Colomar wrote:
> 
> 
> On 12/19/22 20:10, Alejandro Colomar wrote:
>> BTW, I agree with you that the reversed history is a bit weird and confusing.  
>> I thought of a new method that would connect both histories while keeping a 
>> forward history:
>>
>> A separate orphan branch in normal order, starting at 1.0, which ends at 1.70. 
>> And then git allows merging orphan branches, so I can create a merge commit 
>> between both 1.70 commits, which of course is a no-op, but one that tells git 
>> where and how these branches join.
> 
> It was easy to reverse the history.  After renaming the old prehistory branch to 
> prehistory-backwards, and creating an orphan branch, and manually picking the 
> first two commits to see how it works (thus the tail(1) invokation), it's 
> automated as:
> 
> $ git log prehistory-backwards \
>    | grep ^commit \
>    | cut -f2 -d' ' \
>    | tail -n+3 \
>    | while read hash; do
>            git checkout $hash -- . \
>         && git commit --reuse-message=$hash;
>    done;
> 
> And after the merge, we have something with which I'm quite happy: connected 
> forward histories.
> 

That script was a bit buggy.  The good one is:

$ git log prehistory-backwards \
   | grep ^commit \
   | cut -f2 -d' ' \
   | while read hash; do
           rm -rf *;
           git checkout $hash -- . \
        && git add . \
        && git commit --reuse-message=$hash;
   done;

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: patching suffixes(7) (was: groff 1.23.0.rc2 status report)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 3316 bytes --]

At 2022-12-19T20:10:25+0100, Alejandro Colomar wrote:
> On 12/19/22 17:59, G. Branden Robinson wrote:
> > [dropping Deri and groff@]
> > 
> > At 2022-12-19T17:39:37+0100, Alejandro Colomar wrote:
> > > Would you mind sending a patch that I can apply with git?  I could
> > > manually edit the file you attached, but I'm feeling lazy for that
> > > :\
> > 
> > Damn.  Our lazinesses are duelling.  :P
> 
> :P
> 
> I actually wonder how producing such a diff was simpler than just
> copying the output of git diff...

I don't find "diff -u <tab-completion>{,.new}" very difficult.

(I often do that in repos that I mostly read as opposed to contributing
to; that way my half-baked ideas don't get in the way of a rebase pull.
Branching doesn't solve that problem, and if I git-stash something in
such a repo I'm likely to forget about it, or not think to check there.)

> BTW, I still plan releasing man-pages-6.02 in a two days, and feel
> confident enough about the string changes (modulo a few tweaks that
> I'll apply) to ship them in it.  If you have any comments about them,
> please voice them :)

I have weak preference for the name "string_copying(7)" over
"string_copy(7)", but leaving the summary-description the same.

Apart from that I have no comments, apart from encouraging you in your
effort to reform common practice to something less sloppy.  I think you
will get pushback from people who (1) don't appreciate how horrible the
C string library is, in part because they have mazed themselves with the
notion that the engineers at the Bell Labs CSRC were all infallible
giants who deigned to walk among us mortals for a while; and (2) would
rather wait until some total replacement solution comes along, which of
course they would oppose with at least much passion.

Nevertheless, once in a while they'll make good points.  Take that
opportunity to anneal the quality of your initiative.

The standard I/O library is a disaster, too.  Much more esteemed people
than I have made this point, such as Korn and Vo, who presented their
case at USENIX in 1991.[1]  Of course, they did the smart thing back
then and didn't FLOSS-license it, possibly under direction from AT&T
management.  Thanks to that shrewd advice, sfio.h stormed to success and
ubiquity instead of being nearly forgotten.

But even a permissive license may well have not been enough.  The
average programmer will happily drink from a pool of dioxin as long as
it is a familiar one.

> > was David Wheeler (no, the other one)
> 
> Didn't know of the other David Wheeler.

Well, David J. Wheeler (computer scientist) passed away in 2004, so
possibly David A. Wheeler (computer scientist) gets mistaken for him
less often now.

I've been making this joke for years.  It hasn't worked once.  Like the
average programmer, I learn nothing from this.

> According to wikipedia, pkg-config(1)'s initial release is also from
> 2000.  So, yes, probably it wasn't widely known at the time.

It was an innocent time, when packaging was still young and exciting,
and before JavaScript people getting paid a lot to work in e-commerce
decided they could do it better than everyone else.

Regards,
Branden

[1] https://www.cs.princeton.edu/courses/archive/fall97/cs595/sfio.ps

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: patching suffixes(7) (was: groff 1.23.0.rc2 status report)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4376 bytes --]

Hi Branden,

On 12/20/22 04:40, G. Branden Robinson wrote:
> At 2022-12-19T20:10:25+0100, Alejandro Colomar wrote:
>> On 12/19/22 17:59, G. Branden Robinson wrote:
>>> [dropping Deri and groff@]
>>>
>>> At 2022-12-19T17:39:37+0100, Alejandro Colomar wrote:
>>>> Would you mind sending a patch that I can apply with git?  I could
>>>> manually edit the file you attached, but I'm feeling lazy for that
>>>> :\
>>>
>>> Damn.  Our lazinesses are duelling.  :P
>>
>> :P
>>
>> I actually wonder how producing such a diff was simpler than just
>> copying the output of git diff...
> 
> I don't find "diff -u <tab-completion>{,.new}" very difficult.
> 
> (I often do that in repos that I mostly read as opposed to contributing
> to; that way my half-baked ideas don't get in the way of a rebase pull.
> Branching doesn't solve that problem, and if I git-stash something in
> such a repo I'm likely to forget about it, or not think to check there.)

Hmmm, can make sense.  (I branch for such occasions.)  (stash && rebase-pull && 
stash-pop is also common, but that's for repos in which I work more often and 
don't have to pull tons of changes.) :)

> 
>> BTW, I still plan releasing man-pages-6.02 in a two days, and feel
>> confident enough about the string changes (modulo a few tweaks that
>> I'll apply) to ship them in it.  If you have any comments about them,
>> please voice them :)
> 
> I have weak preference for the name "string_copying(7)" over
> "string_copy(7)", but leaving the summary-description the same.
> 

I prefer it too.  string_copy was for when this page was going to substitute the 
other ones, so I wanted it to have a name resembling them.  But now I like 
"copying" more.  So, done, and pushed.  A new page is born.

> Apart from that I have no comments, apart from encouraging you in your
> effort to reform common practice to something less sloppy.

Thanks :)

> I think you
> will get pushback from people who (1) don't appreciate how horrible the
> C string library is, in part because they have mazed themselves with the
> notion that the engineers at the Bell Labs CSRC were all infallible
> giants who deigned to walk among us mortals for a while; and (2) would
> rather wait until some total replacement solution comes along, which of
> course they would oppose with at least much passion.
> 
> Nevertheless, once in a while they'll make good points.  Take that
> opportunity to anneal the quality of your initiative.
> 
> The standard I/O library is a disaster, too.  Much more esteemed people
> than I have made this point, such as Korn and Vo, who presented their
> case at USENIX in 1991.[1]  Of course, they did the smart thing back
> then and didn't FLOSS-license it, possibly under direction from AT&T
> management.  Thanks to that shrewd advice, sfio.h stormed to success and
> ubiquity instead of being nearly forgotten.

That's why I went for public domain for the APIs and basic implementations, and 
BSD-3-Clause for the string_copying(7) page.  I'd like it to be as widespread as 
possible.

However, my own library implementation is LGPL-3.0-or-later, as couldn't be 
otherwise.

> 
> But even a permissive license may well have not been enough.  The
> average programmer will happily drink from a pool of dioxin as long as
> it is a familiar one. >
>>> was David Wheeler (no, the other one)
>>
>> Didn't know of the other David Wheeler.
> 
> Well, David J. Wheeler (computer scientist) passed away in 2004, so
> possibly David A. Wheeler (computer scientist) gets mistaken for him
> less often now.
> 
> I've been making this joke for years.  It hasn't worked once.  Like the
> average programmer, I learn nothing from this.
> 
>> According to wikipedia, pkg-config(1)'s initial release is also from
>> 2000.  So, yes, probably it wasn't widely known at the time.
> 
> It was an innocent time, when packaging was still young and exciting,

I need to learn packaging some day.  I should learn Debian packaging to package 
this new library...

> and before JavaScript people getting paid a lot to work in e-commerce
> decided they could do it better than everyone else.
> 
> Regards,
> Branden
> 
> [1] https://www.cs.princeton.edu/courses/archive/fall97/cs595/sfio.ps

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: groff 1.23.0.rc2 status report (was: [BUG] gropdf, tbl: Completely broken table)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1551 bytes --]

[self-follow-up to clarify two points]

At 2022-12-18T23:32:51-0600, G. Branden Robinson wrote:
> I plan to fiddle various groff mdoc(7) internal register settings so
> that Courier is only used with ".Bd -literal" and ".Bd -literal".

Brainfart here.  I was thinking of ".Bd -literal" and ".Dl".

I observe that the list-begin macro (`Bl`) lacks a "-literal" option, I
suppose because without further parameterization there would be
ambiguity whether the typeface applied to literals should apply to the
definiendum, the definiens,[1] or both.  (If both, you don't need the
option; use one of the other macros above.)

> Probably not a lot of this will be visible to terminal-only users.

I will add that it's possible that some of the problems with the
groff_mdoc(7) page can be overcome with better use of the package's own
macros.  I would have assumed that the page was written in the first
place by an mdoc(7) expert, but I no longer have confidence in that
assumption.[2]  Some time ago Ingo Schwarze made some suggestions
regarding macro selection when I was making a small change to the page,
and while I did not understand his advice in detail at the time, I now
do, and agree with it.  It's a shame when a document about documentation
is deficient as an exemplar of its own subject.

Regards,
Branden

[1] https://en.wikipedia.org/wiki/Definition#Basic_terminology
[2] It originates in the mdoc.samples document from the BSD Net-2
    release.  Perhaps this was not written by Livingston (who authored
    the package) but by someone else.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Deri]

On Saturday, 17 December 2022 11:51:08 GMT Alejandro Colomar wrote:
> Please send your perl script as a patch, adding it to the <scripts/>
> directory. Put your copyright and your preferred license, and we can work
> from there to transform it into something I can better understand.  I'll
> probably be asking you many questions 
> 
> Cheers,
> 
> Alex

Hi Alex,

I am still not happy enough with it yet, and it needs a cover. Please continue 
eye-balling, looking for any issues, and let me know.

Cheers 

Deri