Nut upsdev - Sep 2009 - Embedding man pages in driver source code

With the AsciiDoc conversion underway, I am wondering if we should
keep the AsciiDoc for the driver man pages in a specially-formatted
comment in the driver (taking a cue from the comments specifying USB
information).

I have been doing something similar with the tripplite_usb driver for
a while - it contains Perl-style POD (Plain Old Documentation) in a C
comment, and the man page can be mechanically generated from that.

This way, the documentation is closer to the actual driver source
code, and if someone changes a driver, they only need to send a single
patch.

We probably don't need to do this for the client/server binaries like
upsc and upsmon, but it's a possibility.

Thoughts?

-- 
- Charles Lepple

2009/9/2 Charles Lepple <clepple at gmail.com>
> With the AsciiDoc conversion underway, I am wondering if we should
> keep the AsciiDoc for the driver man pages in a specially-formatted
> comment in the driver (taking a cue from the comments specifying USB
> information).
>
> I have been doing something similar with the tripplite_usb driver for
> a while - it contains Perl-style POD (Plain Old Documentation) in a C
> comment, and the man page can be mechanically generated from that.
>
> This way, the documentation is closer to the actual driver source
> code, and if someone changes a driver, they only need to send a single
> patch.
>
well, I have a mixed feeling about that.
IMO, having the doc and the code is a good thing.
but in practice, looking at tripplite_usb shows that the header is kinda
bloated.
moreover, it doesn't guarantee that the one who patch the code will remember
to modify the inline doc (vs modifying an external one like the manpage).
finally, having a single patch for 1 or 2 files doesn't make much
difference.

We probably don't need to do this for the client/server binaries
like
> upsc and upsmon, but it's a possibility.
>
> Thoughts?
>
while I clearly see the advantage of moving manpages to AsciiDoc (allow to
generate html... output), I still don't much see the one of embedding it
with the code.

perhaps you, as the one who has practiced it, can shed my light.
I'd also like to hear from Arjen.

cheers,
Arnaud
-- 
Linux / Unix Expert R&D - Eaton - http://www.eaton.com/mgeops
Network UPS Tools (NUT) Project Leader - http://www.networkupstools.org/
Debian Developer - http://www.debian.org
Free Software Developer - http://arnaud.quette.free.fr/
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.alioth.debian.org/pipermail/nut-upsdev/attachments/20090903/8c8e9c75/attachment-0001.htm>