undocumented man pages

undocumented man pages

[Stéphane Aulery]

Hello Michael,

Bug reports about the missing pages are frequent but unnecessary. The web page
"missing_pages.html" of the site is very clear about this but unfortunately
"invisible" to end users.

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.

Regards,

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

Re: undocumented man pages

[Michael Kerrisk (man-pages)]

Hello Stéphane,

On 03/07/2015 03:57 PM, Stéphane Aulery wrote:
> Hello Michael,
> 
> Bug reports about the missing pages are frequent but unnecessary. The web page
> "missing_pages.html" of the site is very clear about this but unfortunately
> "invisible" to end users.
> 
> 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.

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

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

Re: undocumented man pages

[Stéphane Aulery]

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.

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

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

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

Re: undocumented man pages

[Michael Kerrisk (man-pages)]

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

Re: undocumented man pages

[Stéphane Aulery]

Le lundi 09 mars 2015 à 08:06:30, Michael Kerrisk (man-pages) a écrit :
> On 8 March 2015 at 12:12, Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org> wrote:
> >
> > 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?

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

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