= Proposal topic =
Man pages Packaging Guideline
= Overview =
I'm man-pages and man package maintainer and I want to start to create some rules to man-pages to package guildelines. Man-pages are the most common documentation so it could be useful to have some rules for them too. There is no restriction or nothing like a standard which would help to package maintainers somehow unified man-pages documentation.
I do a brief overview of the current state and the results are in table on https://fedoraproject.org/wiki/User:Varekova/man-pages/missing-man-pages I test packages from fc12 installation DVD(2400rpms). Rpms contain 110 binaries/scripts in /bin (12 of them have no man-page) - that is 11%. From 326 binaries/scripts in /sbin 50 have no man-page (it is 15%) So that means only 62 scripts/binaries from /bin/sbin have no man-page.
My suggestion is to have policy like "The binaries and scripts which are in /bin and /sbin directories should have man page which describes their behaviour." Which explicitly say which binaries/scripts should have the man-page and which are not restricted by it.
I discuss this topic on FPC, and the result was to put this request to FESCO. (https://www.redhat.com/archives/fedora-packaging/2009-December/msg00004.html)
I'm not sure whether the policy should not be less/more strict, but if some other data are helpful, I can add them.
= Problem space = The problem is absence of rules for man-pages and the non-consistence which rise from it
= Solution Overview = I suggest to have some policy like "The binaries and scripts which are in /bin and /sbin directories should have man page which describes their behaviour." (could be add to packaging guidelines/rpmlint)
= Active Ingredients =
This problem would have impact of package maintainers - but in the present form there is not so much affected packages. (62 missing man-pages)
= Owners =
Hello, I saw the result on #fedora-meeting: FESCo meeting 20091211
"* man pages guidelines (jds2001, 17:08:00) * AGREED: add to packaging guidelines SHOULD: your package should contain man pages for binaries/scripts. If it doesn't, work with upstream to add them where they make sense. (jds2001, 17:22:29)"
but I don't see any notice in packaging guidelines yet. Could I help somehow to get it to Packaging Guidelines (ping sb. to add it there with the link to the FESCO meeting result?). Thanks.
Yes, this still needs to be written up.
I fully agree with the proposal. And this could be extended to all specific Fedora programs, eg. system-config-* I just hope the new man pages will respect the man pages maintainer guidelines (man man-pages).
If a maintainer is ready to write a man page draft, I'll be ready to help him for formatting it as I'll probably translate it in french ;-)
ping
Added here: https://fedoraproject.org/wiki/Packaging:Guidelines#Man_pages
and to the ReviewGuidelines. Sorry it's taken a while to get written up.
Log in to comment on this ticket.