2011/4/18 Thomas Goirand <[email protected]>: > On 04/18/2011 05:44 AM, Soren Hansen wrote: >> 2011/4/17 Thomas Goirand <[email protected]>: >>> In my Debian packaging, I've written few man pages, because it's >>> forbidden in Debian to package things in /usr/bin or /usr/sbin without >>> them. >> I think "forbidden" is a bit of an exaggeration. It says "should" and >> that missing man pages should be considered bugs. > > "lintian -Ii" warns about it, so I fix it... As simple as that! :) > Also, for myself, I found difficult to know which binary accepts what > option, and I would have appreciate such documentation as well.
I completely acknowledge the need for man pages. >> This is actually why I'm generally against stub man pages. They make >> it less obvious that there's work to do, but meh. > Nobody ever wrote we are going to leave things this way, I know, I know. I'm just saying that a complete lack of man pages more clearly says "hey, there's something that needs to be adressed here" than a stub man page does. A stub man page only really serves to silence lintian. >> other binary [...] takes half a bajillion flags. > Which is what I am worried about. At some point, we got to document that. I know. I'm just explaining how nova-manage is different from every executable, and so why it has different needs in terms of documentation. >> We use python-gflags for our flag parsing and stuff, and gflags2man >> can convert the flags descriptions to man pages, but it doesn't really >> work for us, because we have a lot of conditional imports and stuff. >> Anyway, the point is that there are existing tools that can mostly >> generate man pages for us (automatically, so they'll be guaranteed to >> be up-to-date), but there's some plumbing missing. > Ok, that's exactly what I wanted to know, thanks. I'll have a look in > about a week of time (after a short break this week). I have this week off, too. -- Soren Hansen Ubuntu Developer http://www.ubuntu.com/ OpenStack Developer http://www.openstack.org/ _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : [email protected] Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
