Re: undocumented man pages

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

On 8 March 2015 at 12:12, Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org> wrote:
> Hello Michael,
>
> Le dimanche 08 mars 2015 à 09:08:09, Michael Kerrisk (man-pages) a écrit :
>>
>> On 03/07/2015 03:57 PM, Stéphane Aulery wrote:
>> >
>> > 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.

>> 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?

> 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.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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