Re: [docutils:bugs] #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

"G. Branden Robinson" <[email protected]> Tue, 14 Nov 2023 17:03:22 -0600
Newsgroups	gmane.text.docutils.devel
Message-ID	<20231114230322.r4khukf75lhr3vlg@illithid>
At 2023-11-13T04:43:40-0000, engelbert gruber via Docutils-develop wrote:
> the title is misleading and the solution looks like something was
> dropped on the keyboard

You mean `'\" t`?

Yes, that is pretty ugly.  But it is a convention that dates back to the
1980s and approximately every man(1) program in the world supports it.

We can dissect the splat to better understand what it is.

1.  the *roff no-break control character

https://www.gnu.org/software/groff/manual/groff.html.node/Control-Characters.html

2.  the *roff comment escape sequence

https://www.gnu.org/software/groff/manual/groff.html.node/Comments.html

3.  a space

4.  the letter "t" which tells man(1) to run tbl(1)

> on my system "man 7 man" says
> ~~~
>    Title line
>        The  first command in a man page (after comment lines, that is, lines that start
>        with .\") should be
> 
>               .TH title section date source manual

Yes, that's the man(7) page from the Linux man-pages project.  It was
largely written by people without a mastery of the *roff language or
man(7) macro package history.  It's not terrible but it has gaps.

> ~~~
> I had to move a lot of lines before .TH because indexers had problems

Yes.  groff_man(7) tries to warn about this too.

> and I will add this droplet too,

> BUT please is there anyone considering
> the fact that a manual-system should be less cryptic
> 
> and the page might be in need of a cleanup, it also says
> ~~~
>        Many  man pages begin with '\" followed by a space and a list of characters, indicating how the page is to be preprocessed.  For  portability’s  sake  to  non-troff  translators we recommend that you avoid using anything other than tbl(1),
>        and Linux can detect that automatically.
> ~~~

In the next release, the Linux man-pages project is dropping its own
man(7) page in favor of a redirect to groff's (groff_man(7)).  I've
spent a significant part of the past 6 years rewriting that page. It was
much improved for groff 1.22.4 (December 2018) and even more so for
groff 1.23.0 (July 2023).  I am also trying to reach more people with
the new page groff_man_style(7), and trying to steer people to it.

groff_man(7):

Description
       The GNU implementation of the man macro package is part of the
       groff document formatting system.  It is used to produce manual
       pages (“man pages”) like the one you are reading.

       This document presents the macros thematically; for those needing
       only a quick reference, the following table lists them
       alphabetically, with cross references to appropriate subsections
       below.

       Man page authors and maintainers who are not already experienced
       groff users should consult groff_man_style(7), an expanded
       version of this document, for additional explanations and advice.
       It covers only those concepts required for man page document
       maintenance, and not the full breadth of the groff typesetting
       system.

> then the fact that the apostrophe and the dot are the same comes up at
> sometime ...

They are not the same, as noted in the first URL above.  However, a
portable man(7) document is unlikely to ever rely on the distinction
between them and, except for the splat that gives man(1) a hint which
preprocessors to run, a man(7) document should use the normal control
character (the dot .) exclusively.

I've never seen any commentary on the issue, but my guess is that the
no-break control character was drafted into use for the man(1) hint to
avoid confusion arising from the following input.

$ cat > myprog.1
.\" this is my first man page!

Regards,
Branden
signature.asc (application/pgp-signature, 833 B)