On Thu, Sep 3, 2009 at 12:37 PM, Arnaud Quette<[email protected]> wrote: > > 2009/9/2 Charles Lepple <[email protected]> >> >> 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.
Bear in mind that much of each driver man page is boilerplate text, so that could be reduced a bit with AsciiDoc macros. I also included snippets of the protocol left over from the serial tripplite driver, which contributes to the comment bloat. > 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. Well, it was just a thought. My primary motivation with the tripplite_usb man page was to not have to write in NROFF directly, and the fact that POD has well-defined start and end markers was a happy coincidence. We would have to reinvent a little of that for the AsciiDoc stuff. -- - Charles Lepple _______________________________________________ Nut-upsdev mailing list [email protected] http://lists.alioth.debian.org/mailman/listinfo/nut-upsdev
