On 01/12/2011 02:40:00 AM, Matthias Andree wrote:
> Am 11.01.2011 12:20, schrieb David Sommerseth:
> >
> > Hi folks!
> >
> > This is a little cry for help from us playing with the OpenVPN
> code.
> >
> > We have a quite good man page today with a lot of information. But
> > maintaining it and to make sure it is up-to-date with all the
> features
> > OpenVPN supports is often not high up on the priority list.
Don't accept a patch unless the documentation is also patched?
In
> > addition, the current format (one single file, in pure man page
> format)
> > is getting harder and harder to maintain as well.
> >
> > So, we're hoping some people with some English skills is interested
> to
> > help out improving this situation. What we immediately would like
> to
> > see is something along these lines:
> >
> > * Move the man page to a better format than the pure man page
> format.
> > Are there some good tools/formats like ascii2man or DocBookXML
> which
> > could help easing the maintenance of our documentation?
>
> Docbook XML for sure is a lot more verbose than asciidoc or roff. I
> would tend
> to avoid Docbook, the toolchains are lacking a bit -- still :-(
> although xmlto +
> fop can yield reasonable PDF results.
This is a matter of taste. I'd turn that on it's head and say
that Docbook is a lot more clear than roff. How hard is stuff
like:
<section>
<title>Overview</title>
...
</section>
With an editor like emacs or lyx it's not even much more typing
and you get built-in validation, etc.
I'm not sure I understand the tool criticism. There's pdf and
html and all the other basic outputs. You can use the
xinclude mechanism to produce different documents from
components broken into files. So there can be a man page,
a reference book, a "pocket reference" with just a table
of arguments, etc, some content of which is shared and
some of which is unique to each document. If you
like you've all of xml and xslt
and so forth to manipulate the documents dynamically allowing
you to, say, suck an example configuration straight out of
the documentation into a text file to be distributed in
an examples directory to be installed with openvpn.
This way you don't maintain the same example in two places.
>
> However, we should make sure that there still is something that works
> with "man".
Docbook should do man. I've never actually done it but
here's a whole series of tags that
support all the man-like formatting at the top of the man page
what with marking each argument etc.
Frankly, that's where you'll see the ugly verbosity. Plain old
paragraphs and so forth are plainless. But once the top of the
man page is done once you pretty much don't have to make changes
or if you do then you've an example to work from.
Karl <k...@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
