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.
See below for nsd-checkconf.8 as an example.
Jan
.Dd August 25, 2015
.Dt NSD-CHECKZONE 8
.Os
.Sh NAME
.Nm nsd-checkzone
.Nd check syntax of NSD zone files
.Sh SYNOPSIS
.Nm
.Op Fl h
.Ar zonename
.Ar zonefile
.Sh DESCRIPTION
.Nm
reads a DNS zone file and checks it for errors.
It prints errors to stderr.
This is used to check files before feeding them to the
.Xr nsd 8
daemon.
The arguments are as follows:
.Pp
.Bl -tag -width "zonefile" -compact
.It Fl h
Print usage help and exit.
.It Ar zonename
The name of the zone to check.
.It Ar zonefile
The zone file to read.
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
.Dl # nsd-checkzone example.com zones/example.com.zone.signed
.Sh SEE ALSO
.Xr nsd 8 ,
.Xr nsd-checkconf 8
.Sh AUTHORS
.An The NSD team Aq Mt nsd-team@nlnetlabs.nl
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.
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.
i disagree. restructuredtext lacks the semantic markup that mdoc features and what jan was originally proposing. if providing man(7) for legacy systems is necessary, mandoc is a far lighter build depend than sphinx.
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.
I agree that editing in roff/man is about as fun as writing sendmail.cf
> 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.
I agree that editing in roff/man is about as fun as writing sendmail.cf
Well, that was the point. We also had a documentation in texinfo format,
which is ok if you use emacs that autoupdates the references :), but for
the rest of people with inferior editors the sphinx-build is currently
the best option.
That looks much better. Although to add more options to this,
I find the xml more readable (it converts with 'xmlto man')
Do you? Remind me to check for a crazy look in your eyes next time we
meet
Anyway I understand that mdoc might have more formatting options, but
the question is whether they are really needed for nsd manpages and also
whether the comfort of the authors have some priority over the tricks
you can do with the format.
JFTR for the rST you can also have something they call an "option list":
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.
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.
I find the xml more readable (it converts with 'xmlto man')
Do you? Remind me to check for a crazy look in your eyes next time we
meet
Anyway I understand that mdoc might have more formatting options, but
the question is whether they are really needed for nsd manpages and also
whether the comfort of the authors have some priority over the tricks
you can do with the format.
JFTR for the rST you can also have something they call an "option list":
which works nicely if you don't need an optional parameters to the
options.
Cheers,
I can't speak to man pages but XML is certainly more easy to program alternative interface because you can use the DOM interface or an XSLT to translate it.
So for something like putting man pages online, XML source to the man pages would probably be better than man2html.
I am simply proposing to rewrite the manpages
form one markup langunage to another markup language,
which I believe is superior, for reasons better articulated elsewhere.
I am willing to do the work.
And now xmlt2whatever and docbook and all that hell comes.
Please don't.
I am simply proposing to rewrite the manpages
form one markup langunage to another markup language,
which I believe is superior, for reasons better articulated elsewhere.
I am willing to do the work.
And now xmlt2whatever and docbook and all that hell comes.
Please don't.
Jan
Fair enough, my thoughts just are that if a change is going to be made, all the options should be looked at to determine what is the best.
Obviously I'm a fan of XML, I find it to be a beautiful concept, I'd do my zone files in XML if I could
mdocml has a pretty good HTML backend, which gives better HTML than most
things I have seen so far. The quality of XML transformations varies a
lot, depending on who wrote it and how much they cared.
So for something like putting man pages online, XML source to the
man pages would probably be better than man2html.
mdocml has a pretty good HTML backend, which gives better HTML than
most things I have seen so far. The quality of XML transformations
varies a lot, depending on who wrote it and how much they cared.
The man pages are online already on nlnetlabs.nl (preformatted troff
output).
Semantic markup is nice for search capabilities, but I am unsure if
this is in use.
Portability and compatibility are very important for NSD. And also
'lean and mean' minimal dependencies.
For those reasons I see no compelling argument right now to change the
format. Even if there are many choices...
