[Fedora-livecd-list] livecd-iso-to-disk man page

[Daniel P. Berrange]

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;file=man/en/virt-clone.pod

and the generated man page

http://hg.et.redhat.com/virt/applications/virtinst--devel?f=1ceb93283682;file=man/en/virt-clone.1

Regards,
Daniel.
-- 
|: Red Hat, Engineering, London   -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org  -o-  http://virt-manager.org  -o-  http://ovirt.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-  F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|