On Thu, Jun 05, 2008 at 08:50:00AM +0100, Pedro Silva wrote:
Hi!
I started the man page for the livecd-iso-to-disk, I used this guide[1] to do it.
Since this is my first man page ever, shout if I made some terribly mistake.
???[1] http://www.schweikhardt.net/man_page_howto.html
Thoughts, tips?
Personally I always recommend avoiding NROFF as your master format when writing man pages since it is seriously unpleasant to read as an author. I don't know what Jeremy's thoughts are on the topic, but even though this is python code, you might like to consider writing it using POD (Perl's native documentation format) which is a easily readable plain text markup you can embed in shell/python/perl/etc source files, or just have in a standalone text file. You can process this using pod2man to generate the NROFF formatted man page, as well as also having access to pod2html to produce online HTML version, or pod2text for a completely plain text version.
This is what I used for all the python virtualization tools such as virt-install, virt-clone, virt-manager. You can see an examples of the 'master' POD format
http://hg.et.redhat.com/virt/applications/virtinst--devel?f=72d52276a33e;fil...
and the generated man page
http://hg.et.redhat.com/virt/applications/virtinst--devel?f=1ceb93283682;fil...
Regards, Daniel.