[Nut-upsdev] Embedding man pages in driver source code

[Charles Lepple]

On Thu, Sep 3, 2009 at 12:37 PM, Arnaud Quette<aquette.dev at gmail.com> wrote:
>
> 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.

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