"onf" <o...@disroot.org> writes:
Speaking of which, I noticed just recently that all of groff's
manpages
don't use all caps for subheadings (.SH)... which is about the
first
time I've seen manpage subheadings that weren't in all caps.
In my mdoc(7) ports of documentation in the skaware ecosystem
(e.g. s6-man-pages, https://git.sr.ht/~flexibeast/s6-man-pages),
i've used sentence case with Ss, the mdoc(7) equivalent of SH.
It's not that documentation isn't important, merely that it's
not so
incredibly important to spend several hours on such a minor
task. This
also becomes a problem in that manpages aren't maintained as
well as
the
software because few people understand the syntax.
By which i presume you mean, the man(7) language rather than the
mdoc(7) language; more on this below.
i certainly agree that, for people not regularly creating new man
pages from scratch, having to learn roff and a macro library
probably feels like unnecessary work.
I can imagine manpages would be much more usable if
cross-references
and subheadings etc. weren't just a matter of formatting, but
actually
meant something to the viewer.
This is one of the reasons i'm an advocate for people using
mdoc(7) for man pages - as is done on the *BSDs - rather than
man(7). Where man(7) is primarily presentational markup, mdoc(7)
is primarily _semantic_ markup. This allows the use of the macros
as search keys for apropos(1); the example i usually provide is:
$ apropos Ev=PATH
to get a list of man pages which mention the PATH environment
variable.
Although there are indeed more mdoc(7) macros to keep in mind
compared to man(7), i find them easier to remember than the
association-by-convention required for man(7) formatting
macros. Ev, 'Environment variable', is one example; others include
'Ss' ('Subsection header'), 'Xr' ('Cross-reference'), 'Fn'
('Function name') and 'Fa' ('Function argument').
Porting the documentation for s6 was the first time i'd ever
created man pages. Initially i assumed man pages _had_ to be
written in man(7), and as someone who was long ago sold on the
benefits of separating semantics from presentation, i found the
idea of having to memorise associations between particular
intended semantics and particular presentational markup to be
.... discouraging. i don't know how i stumbled across mdoc(7), but
once i did, and discovered that it could be used for man pages on
Linux via groff, i focused on learning and using mdoc(7).
To try to demystify it for others, i wrote this quickstart guide:
https://github.com/flexibeast/guides/blob/master/mdoc-quickstart.md
Alexis.
