On Wednesday, July 2, 2003, at 6:03 AM, Brad Hards wrote:
As an intial example of the
quality that we can expect, see the attached docbook source, and
generated
man page. Note that the content isn't meant to reflect final content -
this
is just an indication of formatting quality.
I presume the lack of the description section is a case of "not
reflect[ing] final content".
Is the list of values for "-T" generated by running Ethereal or
Tethereal or editcap with the appropriate flag (some flavor of "-G",
presumably) and massaging the output? If so, note that there's a
missing blank line between "o tzsp - Tazmen sniffer protocol" and the
next paragraph.
Of course, changing to Docbook implies that whoever does the updates
needs to
understand docbook.
Or needs a tool to edit it; the sample had enough tags in it that
something more than a pure text editor might be more pleasant to use.
Assuming that I can convert the current documentation over to docbook,
how do
the developers feel about needing docbook experience and toolchain
instead of
POD?
I can probably get the appropriate tools running on some machine at
home, and can probably pick up the DocBook knowledge I'd need. I can't
speak for the other developers, but most contributions don't affect the
man pages; those that do, unfortunately, don't include man page updates
- I don't know whether using DocBook would make it more likely that
they would, less likely that they would, or make no difference.
I've thought in the past that DocBook would be a good idea; note,
though, that the man pages are currently generated using a tool that
should, I think, be present on any system with Perl, *and* that they're
generated as part of the build process for the regular distribution
tarballs; going to DocBook might either require that we ship template
man-format man pages and generate the man page from that template, or
require people building Ethereal from source, even if they're just
compiling a release tarball, to have DocBook tools installed.
