Feature proposal: New, Standard Documentation System

[Richard W.M. Jones]

On Thu, Nov 27, 2008 at 11:06:19AM +0100, Thorsten Leemhuis wrote:
> On 27.11.2008 10:32, Richard W.M. Jones wrote:
>> Debian forces all programs to come with a man page.  If one is
>> missing, this is considered a bug and packagers have to write one.
>>
>> http://www.debian.org/doc/debian-policy/ch-docs.html
>
> My 2 cent: It would be way better for everyone to get those man pages  
> upstream.

I should clarify three points.

+1 to the suggestion that man pages should go upstream.  They should
be treated just like any other patch.  We should encourage Debian to
do the same, but if they don't we take Debian's man pages and push
them upstream ourselves.

My second point is that it's a really useful feature of Debian that
_any_ command, any many configuration files and other files, are
documented using 'man'.  I find it a big negative against Fedora that
things aren't so consistently documented.

And lastly I'm not suggesting that beginners should have to type 'man
foo'.  Once everything is available as a man page, it should be
relatively easy to present those in the UI through some suitable
mechanism, whether that is groff->HTML conversion or whatever.

Rich.

-- 
Richard Jones, Emerging Technologies, Red Hat  http://et.redhat.com/~rjones
virt-df lists disk usage of guests without needing to install any
software inside the virtual machine.  Supports Linux and Windows.
http://et.redhat.com/~rjones/virt-df/