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

[Arnaud Quette]

2009/9/7 Charles Lepple <clepple at gmail.com>

> On Mon, Sep 7, 2009 at 4:09 AM, Arnaud Quette<aquette.dev at gmail.com>
> wrote:
> >
> >
> > 2009/9/4 Charles Lepple <clepple at gmail.com>
> >>
> >> 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.
> >
> > well, there might also be some consolidation with information from
> > upsdrv_info and the vartable (can be obtained through driver "-help"
> call).
> >
> > don't know if that can be considered though.
>
> Could you provide an example of how you would use that for the man page?
>

in fact looking at the example shows that it's currently not possible.
ex with "usbhid-ups -L"
...
VALUE offdelay "Set shutdown delay, in seconds (default=20)"
...
converts in the manpage to:
...
offdelay=num
    Set the timer before the UPS is turned off after the kill power command
is sent (via the -k switch).

    The default value is 20 (in seconds). Usually this must be lower than
ondelay, but the driver will not warn you upon startup if it isn’t.
...

the manpage clearly wins the verbosity round.

I was also thinking about adding an option ("-I" or "-d" => driver-info) to
display the content of upsdrv_info. This seems still applicable for AUTHOR,
NAME, DESCRIPTION and possibly some more...

>> > 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.
> >
> > as said above, part of the extraction process, we may want to consolidate
> > info using some calls to the drivers to obtain authors, params, ...
> >
> > a perl or python scrip in tools can do the job.
> > can you propose the foundation (how to include the text in the driver so
> > that it can be extracted, consolidation with the existing data, ...) and
> > possibly an example with skel?
>
> I will think about it, but I should probably start converting some of
> the man pages first, so that I have a better idea of what can be
> consolidated. We will need the nroff source converted at some point,
> whether or not it ends up in separate files or embedded in the source
> code.
>

yep, something can emerge during the conversion.
like including the protocols.txt content...

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/20090907/c4744e1d/attachment.htm>