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.
I used info found on fedora's wiki and other sources to make the man page but not all sections are filled yet.
Section Files:
Should the man page pay attention to any files needed by livecd-iso-to-disk, which ones?
Section Environment:
I haven't tested this yet but, is it possible to run livecd-iso-to-disk when SELinux is on ? If not, should I mention it in this section?
Section Diagnostics:
Should it contain the error messages that livecd-iso-to-disk can throw at users?
If all goes right, I would also like to start the man page for livecd-creator.
[1] http://www.schweikhardt.net/man_page_howto.html
Thoughts, tips?
Best regards,
On Thu, 2008-06-05 at 08:50 +0100, Pedro Silva wrote:
I started the man page for the livecd-iso-to-disk, I used this guide[1] to do it.
Awesome!
Since this is my first man page ever, shout if I made some terribly mistake.
It looks pretty good to me. For sections which don't have anything to put, the general way to work is just to leave them out.
Section Files:
Should the man page pay attention to any files needed by livecd-iso-to-disk, which ones?
Not really... the idea is to make it as self-contained as possible
Section Environment:
I haven't tested this yet but, is it possible to run livecd-iso-to-disk when SELinux is on ? If not, should I mention it in this section?
Yep, it works without any problems at all. So this section can probably go away.
Section Diagnostics:
Should it contain the error messages that livecd-iso-to-disk can throw at users?
This probably also isn't that relevant... in fact, I'm not even finding any man pages with it in a quick check, so I'm not sure where it got made up for in the referenced page
Jeremy
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.
Sex, 2008-06-06 às 10:11 +0100, Daniel P. Berrange escreveu:
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.
Daniel, thanks for input.
I'm happy to jump format as long as I land in a format I can use and is accepted by other Fedora projects.
The HOWTO that I used was the first hit in google with "how to make a man page linux". After reading your message, I searched for this kind of info in fedora's wiki but I don't think there is any page about a "standard" way of doing man pages for fedora.
If there are no objections, I'll make livecd-tool's man pages using POD markup language.
Jeremy, your input about the sections will also be taken into account. :)
Best regards,
On Sat, 2008-06-07 at 08:45 +0100, Pedro Silva wrote:
If there are no objections, I'll make livecd-tool's man pages using POD markup language.
Either/or works fine for me.
Jeremy, your input about the sections will also be taken into account. :)
Sounds good; I look forward to adding them to the tree :-)
Jeremy
livecd@lists.fedoraproject.org