Petr Vaněk <arkamar_at_atlas.cz> writes:
> I was always wondering, do you synchronize man pages just by
> hand or is
> there some automation involved?
By hand. i generate a diff of what's changed, and then manually
convert that to mdoc(7). How long that takes varies between
releases, due to various factors.
The HTML source is mostly presentational markup, whereas mdoc(7)
is semantic markup (in contrast to man(7), as used for the Linux
man pages, which is mostly a presentational markup language). It's
often not possible to algorithmically determine what semantic
markup is required for a given presentational tag: for instance,
is a given '<em>' tag indicating an argument (= 'Ar' in mdoc), or
a program (possibly 'Xr', possibly something else), 'mere'
emphasis (= 'Em'), or something else?
i personally find mdoc(7) far more pleasant to work with than
man(7) - i probably wouldn't have done the port if use of the
latter had been a requirement - and the fact that it's semantic
means it's possible to do things like use apropos(1) to search for
pages containing particular terms in particular contexts
(e.g. uses of a specific environment variable).
> Anyway, I plan to package s6-*man-pages for gentoo.
Wonderful, thank you! i would suggest they should go in the
'app-doc' category (but of course i'll defer to the Gentoo devs on
this).
Alexis.
Received on Mon Dec 04 2023 - 13:26:52 CET