Re: undocumented man pages

Le lundi 09 mars 2015 à 08:06:30, Michael Kerrisk (man-pages) a écrit :

On 8 March 2015 at 12:12, Stéphane Aulery [off-list ref] wrote:

quoted

Le dimanche 08 mars 2015 à 09:08:09, Michael Kerrisk (man-pages) a écrit :

quoted

On 03/07/2015 03:57 PM, Stéphane Aulery wrote:

quoted

What do you think about to add a "undocumented" page for each section (as
undocumented.3) and create each missing pages with a reference to the
appropriate "undocumented" page. Thus we can also encourage users to become
contributors and avoid unnecessary reports.

My problem with this idea is that my simple test when wondering if
a man page exists for an API is to look in the appropriate man?/
directory for a file with the right name. With the scheme above, I then
need to look inside the file to see if it is a link to undocumented.x.
That would be a small inconvenience.

How is obtained the list of missing pages? Another solution would be to
provide a script that generates the missing pages with the redirection.

I worked from scripts shown at
https://www.kernel.org/doc/man-pages/missing_pages.html
but manual work on top of that was also needed.

quoted

quoted

Yes, the reports about missing pages are a minor irritation, but I'm
a little doubtful that such an "undocumented" page would encourage much
contribution. (I could be wrong, that's just my guess.)

I too could be wrong. I'm probably too optimistic. I feel that if the
user sees clearly that the page is not yet written and needs of its
contribution, it is better information for him and a better chance for
us.

Maybe. So, here's another idea. Since I don't really want to pollute
the Git repo with a lot of useless links, another possibility would be
a release-time script that generates the "undocumented" pages from
plain test file lists (e.g., one function name per line). Those lists
could live in the Git repo, and then be used to autogenerate a page
such as undocumented(3) (which does *not* list  a lot of the
undocumented functions, and has no links). Thoughts?

I was thinking about that too. If I can help for anything, I will.

quoted

PS: Thank you for patches, you are very responsive !

Not always, unfortunately. Things get dropped too often. You should
ping when I don't respond to patches in a week or two.

Okay. Next days/weeks, I will need your advices about a bunch of bug reports.
I will not send all to you in one shot !

Cheers,

-- 
Stéphane Aulery
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html