doc/rfc*

[David W. Hankins]

On Fri, Sep 08, 2006 at 10:42:02AM +1000, Glenn Satchell wrote:
> What about an online, searchable, HTML version of the man pages,
> perhaps a format similar to the BIND9 ARM?

For starters, we need the README in a markup format, so it can be
converted to HTML for the webpages...right now that's a manual
by-hand process, so stuff gets lost all the time in the
translation.

The RELNOTES is going to eventually transform to BIND's CHANGES
format, for the bulk of its contents, at some point (for fewer
different processes/procedures for us).  The summaries of new
features, and other "relase notey" things, will move to the
README I think.

And we totally need the manpages up on the web.  Since they're
already in nroff, that shouldn't be hard, we just haven't gotten
around to it yet.

> Obviously the best way would be some sort of automated generation from
> the source document format - I assume that is docbook or something
> similar, rather than hand written nroff?

The BIND9 ARM has undergone changes recently, and I admit I was
intending on not paying close attention to the final format until
it settled, so I've forgotten all about it.  I do believe it is
docbook, but I'm not positive.

The references document I'm drawing attention to was done in
"xml2rfc", because that's what was handiest and easiest...the
XML bibliography resources make that sort of collection of
documents painfully simple; all I had to do was reference
them by name and xml2rfc pulls all the relevant info off a
fine website (note that doc/Makefile is not in the 'build all'
path, we do this manually with changes and commit the resulting
files).

> If you're looking for some
> help, then I might be able to put my hand up to help.

We totally accept patches.  And now that 3.1.0a1 is in a
publically released form, and contains some of those patches
I've been telling people we accept, I hope that carries more
weight than it did before.

The nice thing about documentation patches is we usually don't
have to do a lot of review to incorporate them.  With source
patches, if we find problems (or fail to resist our urges to
"just improve it a little" - a common failing of mine) we have
to involve a second person at ISC to review our changes.  I can
commit documentation to branches without any process, so, much
easier.


A DHCP ARM like thing would be good, especially if it mimicked the
BIND ARM as closely as possible in terms of layout and format.

-- 
ISC Training!  October 16-20, 2006, in the San Francisco Bay Area,
covering topics from DNS to DHCP.  Email training at isc.org.
-- 
David W. Hankins	"If you don't do it right the first time,
Software Engineer		you'll just have to do it again."
Internet Systems Consortium, Inc.	-- Jack T. Hankins