<br><div class="gmail_quote">2009/9/7 Charles Lepple <span dir="ltr"><<a href="mailto:clepple@gmail.com">clepple@gmail.com</a>></span><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div><div></div><div class="h5">On Mon, Sep 7, 2009 at 4:09 AM, Arnaud Quette<<a href="mailto:aquette.dev@gmail.com">aquette.dev@gmail.com</a>> wrote:<br>
><br>
><br>
> 2009/9/4 Charles Lepple <<a href="mailto:clepple@gmail.com">clepple@gmail.com</a>><br>
>><br>
>> On Thu, Sep 3, 2009 at 12:37 PM, Arnaud Quette<<a href="mailto:aquette.dev@gmail.com">aquette.dev@gmail.com</a>><br>
>> wrote:<br>
>> ><br>
>> > 2009/9/2 Charles Lepple <<a href="mailto:clepple@gmail.com">clepple@gmail.com</a>><br>
>> >><br>
>> >> With the AsciiDoc conversion underway, I am wondering if we should<br>
>> >> keep the AsciiDoc for the driver man pages in a specially-formatted<br>
>> >> comment in the driver (taking a cue from the comments specifying USB<br>
>> >> information).<br>
>> >><br>
>> >> I have been doing something similar with the tripplite_usb driver for<br>
>> >> a while - it contains Perl-style POD (Plain Old Documentation) in a C<br>
>> >> comment, and the man page can be mechanically generated from that.<br>
>> >><br>
>> >> This way, the documentation is closer to the actual driver source<br>
>> >> code, and if someone changes a driver, they only need to send a single<br>
>> >> patch.<br>
>> ><br>
>> > well, I have a mixed feeling about that.<br>
>> > IMO, having the doc and the code is a good thing.<br>
>> > but in practice, looking at tripplite_usb shows that the header is kinda<br>
>> > bloated.<br>
>><br>
>> Bear in mind that much of each driver man page is boilerplate text, so<br>
>> that could be reduced a bit with AsciiDoc macros. I also included<br>
>> snippets of the protocol left over from the serial tripplite driver,<br>
>> which contributes to the comment bloat.<br>
><br>
> well, there might also be some consolidation with information from<br>
> upsdrv_info and the vartable (can be obtained through driver "-help" call).<br>
><br>
> don't know if that can be considered though.<br>
<br>
</div></div>Could you provide an example of how you would use that for the man page?<br></blockquote><div> <br>in fact looking at the example shows that it's currently not possible.<br>ex with "usbhid-ups -L"<br>
...<br>VALUE offdelay "Set shutdown delay, in seconds (default=20)"<br>...<br>converts in the manpage to:<br>...<br>offdelay=num<br> Set the timer before the UPS is turned off after the kill power command is sent (via the -k switch).<br>
<br> 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.<br>...<br><br>the manpage clearly wins the verbosity round.<br><br>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...<br>
<br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div><div class="h5">
>> > moreover, it doesn't guarantee that the one who patch the code will<br>
>> > remember<br>
>> > to modify the inline doc (vs modifying an external one like the<br>
>> > manpage).<br>
>> > finally, having a single patch for 1 or 2 files doesn't make much<br>
>> > difference.<br>
>> ><br>
>> >> We probably don't need to do this for the client/server binaries like<br>
>> >> upsc and upsmon, but it's a possibility.<br>
>> >><br>
>> >> Thoughts?<br>
>> ><br>
>> > while I clearly see the advantage of moving manpages to AsciiDoc (allow<br>
>> > to<br>
>> > generate html... output), I still don't much see the one of embedding it<br>
>> > with the code.<br>
>> ><br>
>> > perhaps you, as the one who has practiced it, can shed my light.<br>
>> > I'd also like to hear from Arjen.<br>
>><br>
>> Well, it was just a thought. My primary motivation with the<br>
>> tripplite_usb man page was to not have to write in NROFF directly, and<br>
>> the fact that POD has well-defined start and end markers was a happy<br>
>> coincidence. We would have to reinvent a little of that for the<br>
>> AsciiDoc stuff.<br>
><br>
> as said above, part of the extraction process, we may want to consolidate<br>
> info using some calls to the drivers to obtain authors, params, ...<br>
><br>
> a perl or python scrip in tools can do the job.<br>
> can you propose the foundation (how to include the text in the driver so<br>
> that it can be extracted, consolidation with the existing data, ...) and<br>
> possibly an example with skel?<br>
<br>
</div></div>I will think about it, but I should probably start converting some of<br>
the man pages first, so that I have a better idea of what can be<br>
consolidated. We will need the nroff source converted at some point,<br>
whether or not it ends up in separate files or embedded in the source<br>
code.<br></blockquote></div><br>yep, something can emerge during the conversion.<br>like including the protocols.txt content...<br><br>cheers,<br>Arnaud<br>-- <br>Linux / Unix Expert R&D - Eaton - <a href="http://www.eaton.com/mgeops">http://www.eaton.com/mgeops</a><br>
Network UPS Tools (NUT) Project Leader - <a href="http://www.networkupstools.org/">http://www.networkupstools.org/</a><br>Debian Developer - <a href="http://www.debian.org">http://www.debian.org</a><br>Free Software Developer - <a href="http://arnaud.quette.free.fr/">http://arnaud.quette.free.fr/</a><br>
<br>