Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

[G. B. R. <g.b...@gm...>]

Hi Engelbert,

At 2023-08-16T10:25:19+0200, engelbert gruber wrote:
> On Wed, 16 Aug 2023 at 05:38, G. Branden Robinson <
> g.b...@gm...> wrote:
> > For those whose systems don't have 1.23.0 installed yet, the
> > groff_man_style(7) document can be read in PDF; go to page 253.
> >
> > https://www.gnu.org/software/groff/manual/groff-man-pages.pdf
> 
> did put it on my list :-)

Cool.  Let me know what points, if any, need to be clarified.

> take him by his word  submit a minimal page pointing to the macros

I guess if someone installs the Linux man-pages package without
installing groff, and they get an error message, that a distributor's
problem to sort out.

> actually in my understanding man 7 man should be the man macros
> groff_man or man_roff or man _groff should container formatter
> requests

I don't think that's correct.  My understanding is that groff man pages
got prefixes 30+ years ago so that they could be simultaneously
installed with AT&T troff.  Part of that involved giving the GNU
reimplementation of AT&T troff commands a 'g' prefix ("gtroff", "gtbl",
"geqn", and so on).  But there were also man pages for things that
weren't commands, like font(5) in Research Unix, and the macro packages,
like man(7), ms(7), and mm(7).

So for sections 5 and 7, groff decided to just use its own name as a
prefix to avoid collisions.

The practice remains useful to distinguish implementations.  For
instance, on my Debian system there are also mandoc_man(7) and
mandoc_roff(7) pages.

So both man(7) and groff_man(7) would describe the "man" macro package.
To avoid repetition, as you suggest it's better if one just points to
the other.

The page documenting formatter requests, escape sequences, and
predefined register names (as well as, in groff 1.23.0, a lot of
specification and conceptual explanation), is groff(7).

The end of the groff(1) page attempts to present groff's ~59 man pages
in an organized way so that users can find material of interest.

Regards,
Branden