From Fedora Project Wiki
No edit summary
m (internal link cleaning)
 
(4 intermediate revisions by one other user not shown)
Line 1: Line 1:
I'm man-pages and man package maintainer and I want to start to somehow add some rules to man-pages to package guildelines (they are the most common documentation so it could be nice to have some rules for them too).
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.


== Statistic for fc11/fc12 ==
* At first I want to find out the number of binaries from directories /bin, /sbin, /usr/sbin and /usr/bin which have no man-page.
* At first I want to find out the number of binaries from directories /bin, /sbin, /usr/sbin and /usr/bin which have no man-page.
From this numbers there could be generated some recommendations like: all binaries in ... directories should have man page.
From this numbers there could be generated some recommendations like: all binaries in ... directories should have man page.
Line 6: Line 7:
Statistic about man-pages (generated from '''fc12''' installation DVD content - 2400 rpms ) :
Statistic about man-pages (generated from '''fc12''' installation DVD content - 2400 rpms ) :
{|
{|
!directory !! number of binaries !! number of missing man-pages !! percentage of missing man pages
!directory !! number of missing man-pages !! number of binaries/scripts !! percentage of missing man pages
|-
|-
| /bin      ||    110            || 12                          ||  11%         
| /bin      ||    12            || 110                          ||  11%         
|-
|-
| /sbin    ||    326            || 50                          ||  15%
| /sbin    ||    50            || 326                          ||  15%
|-
|-
| /usr/sbin ||    431           || 125                         ||  29%
| /usr/sbin ||    125           || 431                         ||  29%
|-  
|-  
| /usr/bin  ||    2814           || 1270                         ||  45%
| /usr/bin  ||    1270           || 2814                         ||  45%
|}
|}
Statistic about man-pages (generated from '''fc11''' installation DVD content - 2252 rpms ) :
Statistic about man-pages (generated from '''fc11''' installation DVD content - 2252 rpms ) :
{|
{|
!directory !! number of binaries !! number of missing man-pages !! percentage of missing man pages
!directory !! number of missing man-pages !! number of binaries/scripts !! percentage of missing man pages
|-
|-
| /bin      ||    108            || 14                          ||  13%         
| /bin      ||    14            || 108                          ||  13%         
|-
|-
| /sbin    ||                   ||                             ||  %
| /sbin    ||   55            || 324                          ||  17%
|-
|-
| /usr/sbin ||                   ||                             ||  %
| /usr/sbin ||   141            || 447                          ||  32%
|-  
|-  
| /usr/bin  ||                   ||                             ||  %
| /usr/bin  ||   1326          || 3149                        ||  42%
|}
|}


* for me '''/bin''' and '''/sbin''' are good candidates for directories in which the binaries and scripts should have man page.
== Proposal ==
* For now(fc12) there have only 62 binaries/scripts in '''/bin''' and '''/sbin''' which have no man page. It about 14 percentage of all binaries/scripts. Since fedora 11 the number lower a bit. It see, for me to be good reasons to have some guidelines like:


'''''"The binaries and scripts which are in /bin and /sbin directories should have man page which describes their behaviour."'''''




* there could be done some other activities - add test for missing man-pages to rpmlint, add there some tool which will check options man-page declare and options which the tool accept or some spellchecker. There could be also do a test which check whether the man-pages are in good path.
== Other ideas ==
* there could be done some other activities - add test for missing man-pages to rpmlint, add there some tool which will check options man-page declare and options which the tool accept or some spell checker. There could be also do a test which check whether the man-pages are in good path.


Links: https://fedoraproject.org/wiki/MAN_pages_which_exists_in_other_places(draft)
== Links ==
MAN pages which exists in other places(draft) - [[MAN_pages_which_exists_in_other_places(draft)]]

Latest revision as of 09:27, 18 September 2016

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.

Statistic for fc11/fc12

  • At first I want to find out the number of binaries from directories /bin, /sbin, /usr/sbin and /usr/bin which have no man-page.

From this numbers there could be generated some recommendations like: all binaries in ... directories should have man page.

Statistic about man-pages (generated from fc12 installation DVD content - 2400 rpms ) :

directory number of missing man-pages number of binaries/scripts percentage of missing man pages
/bin 12 110 11%
/sbin 50 326 15%
/usr/sbin 125 431 29%
/usr/bin 1270 2814 45%

Statistic about man-pages (generated from fc11 installation DVD content - 2252 rpms ) :

directory number of missing man-pages number of binaries/scripts percentage of missing man pages
/bin 14 108 13%
/sbin 55 324 17%
/usr/sbin 141 447 32%
/usr/bin 1326 3149 42%

Proposal

  • For now(fc12) there have only 62 binaries/scripts in /bin and /sbin which have no man page. It about 14 percentage of all binaries/scripts. Since fedora 11 the number lower a bit. It see, for me to be good reasons to have some guidelines like:

"The binaries and scripts which are in /bin and /sbin directories should have man page which describes their behaviour."


Other ideas

  • there could be done some other activities - add test for missing man-pages to rpmlint, add there some tool which will check options man-page declare and options which the tool accept or some spell checker. There could be also do a test which check whether the man-pages are in good path.

Links

MAN pages which exists in other places(draft) - MAN_pages_which_exists_in_other_places(draft)