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

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

Hi Engelbert,

At 2023-08-14T10:41:58+0200, engelbert gruber wrote:
> On man 7 man (AFAIR) is a list of safe statements .sp asf

Yes.  The man(7) page from the Linux man-pages project does have a list
of "safe" formatter requests.  Long story short, the current Linux
man-pages maintainer would like to withdraw the page and has invited me
to submit (the equivalent of) a merge request to do so.[1]  mandoc
maintainer Ingo Schwarze and I take a pretty different approach to the
problem; we agree that minimal use of formatter requests, and sticking
to the existing sets of package macros (plus a few escape sequences) is
the most reliable route to portable man page rendering.

That "minimal" approach also means that people writing man(7) documents
or tools to generate them have to master much less material.

> which I tried to limit the writer output man 7 groff_man I learned
> only recent

In my opinion that man page became a more helpful resource with the
release of groff 1.22.4 in December 2018, and in groff 1.23.0 (released
5 July) there is a new groff_man_style(7) page that is written for
newcomers, and presumes as little knowledge of typesetting and *roff
programs as possible.  In full disclosure, much of it is my own work.

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

> Along the line of the discussion we had with the latex writer … target
> the structure or use only the type setting (line drawing)
> 
> Structure it was/is

If I'm understanding you correctly, I agree with the choice.  You want
to convert ReStructured Text into high-level structural markup as much
as the target language allows, and get involved with fiddly details of
typesetting as little as possible.

Regards,
Branden

[1] "I want to kill that page"

https://lore.kernel.org/linux-man/fe3...@ke.../T/#m124e9719a24560c8ed5526e7464d4a4c311008a7