Open Stack

2011/4/18 Thomas Goirand <thomas at goirand.fr>:
> On 04/18/2011 05:44 AM, Soren Hansen wrote:
>> 2011/4/17 Thomas Goirand <thomas at goirand.fr>:
>>> 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/