[Freeipmi-devel] Some improvement ideas

[Arnaud Quette]

Hi Al and the list,

Here is 2 things that I'd like to share with you, and that could make your developer / maintainer life easier, and your users happier.
I won't go into details, but there are also clear QA advantages in automation, and usage of standard transformation tools.

1) Documentation

For both user and developers docs, manpages, website, you should consider AsciiDoc:
http://www.methods.co.nz/asciidoc/

AsciiDoc use a simple, yet powerful, plain text formating, equivalent to Wikis RST.
It allows to handle everything from Makefiles, and generate HTML, PDF, groff, epub, ODS, ... from .txt
AsciiDoc was recommended to me 2 years ago by ESR (Eric S Raymond, part of the NUT team), and it's really a Holy Grail!

Here is what I did for NUT:
http://old.networkupstools.org/
http://www.networkupstools.org/

Have a closer look at the Documentation sections.
All this done with the .txt files here: http://anonscm.debian.org/viewvc/nut/trunk/docs/

If you're interested, I can help bootstrapping things...


2) Maintainability

you should consider automatic generation for the ChangeLog, using SVN commit messages.

This is what we have in NUT:
...
# Automatically generate the ChangeLog from SVN logs:
MAINTAINERCLEAN_FILES = ChangeLog
ChangeLog: tools/svn2cl.authors
    svn2cl --group-by-day --include-rev --authors=$< --revision 'HEAD:2332' --output=$@ || \
        echo "svn2cl failed to generate the ChangeLog. See http://trac.networkupstools.org/projects/nut/timeline" > $@
...

Here is a sample output: http://www.networkupstools.org/source/2.6/ChangeLog


well, I should be done for this evening, but expect me to get back soon ;-)

cheers,
Arnaud
-- 
Linux / Unix Expert R&D - Eaton - http://powerquality.eaton.com
Network UPS Tools (NUT) Project Leader - http://www.networkupstools.org/
Debian Developer - http://www.debian.org
Free Software Developer - http://arnaud.quette.free.fr/