[nsd-users] nsd manpages

[Jan Stary]

On Aug 25 18:19:35, tim at kariliq.nl wrote:
> Jan Stary (2015-08-25 17:27 +0200):
> > Currently, the NSD manpages are written in the legacy man(7) language.
> > I propose to rewrite them into the markup of the mdoc(7) language.
> > 
> > Both languages are sets of roff macros, supported for decades
> > by mostly groff (on linuxes) and mandoc (on the BSD's).
> > The main difference is that mdoc(7) does _semantic_ markup,
> > so the macros mean e.g. "this is a command line option"
> > as opposed to e.g. "make it italics and put brackets around it".
> > See http://mdocml.bsd.lv/ about the whole story.
> 
> The only disadvantage of mdoc, however, is that some systems still don't
> support it. I believe Solaris is one of them. So, for portability, you'd
> have to be able to provide man pages in both mdoc and man format.

mdoc is a language. To support it, you need a formatter.
Both the standard formatters, groff and mandoc,
are available on Solaris.

See a recent debate about mandoc on Solaris:
http://lists.opencsw.org/pipermail/buildfarm/2015-March/002424.html

On Aug 26 10:27:15, ondrej at sury.org wrote:
> I believe a better option would be to rewrite the man pages (and
> documentation) into sphinx-build + build manpages (and documentation) at
> the "make dist" step, so they are included in the final distribution
> tarball.
> 
> The reStructuredText is much more readable (and editable) than man(7) or
> mdoc(7) format.

Tha man(7) and mdoc(7) languages are decades-old standards,
supported nearly everywhere.

> An example man page for kdig:
> https://gitlab.labs.nic.cz/labs/knot/raw/master/doc/man_kdig.rst

Perhaps I didn't get the main point accross:
mdoc(7) provides _semantic_markup_; so you say things like

	.Op Ar name

meaning "the utility takes an optional argument named 'name'",
as opposed to "typeset a pair of brackets around 'name'".
I don't see that in e.g.

	**-x** *address*


On Aug 26 09:33:59, paul at nohats.ca wrote:
> I find the xml more readable (it converts with 'xmlto man')

Oh please.


On Aug 26 15:41:57, ondrej at sury.org wrote:
> Anyway I understand that mdoc might have more formatting options, but
> the question is whether they are really needed for nsd manpages

What I am proposing has nothing to do with "more formatting options".


	Jan