<br><div class="gmail_quote">2009/9/2 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;">
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></blockquote><div><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 bloated.<br>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).<br>
finally, having a single patch for 1 or 2 files doesn't make much difference.<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;">
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>
<font color="#888888"></font></blockquote><div><br>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.<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>cheers,<br>Arnaud<br></div></div>-- <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>