* undocumented man pages @ 2015-03-07 14:57 Stéphane Aulery [not found] ` <20150307145716.GA24297-GANU6spQydw@public.gmane.org> 0 siblings, 1 reply; 5+ messages in thread From: Stéphane Aulery @ 2015-03-07 14:57 UTC (permalink / raw) To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
[parent not found: <20150307145716.GA24297-GANU6spQydw@public.gmane.org>]
* Re: undocumented man pages [not found] ` <20150307145716.GA24297-GANU6spQydw@public.gmane.org> @ 2015-03-08 8:08 ` Michael Kerrisk (man-pages) [not found] ` <54FC0369.3010705-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 0 siblings, 1 reply; 5+ messages in thread From: Michael Kerrisk (man-pages) @ 2015-03-08 8:08 UTC (permalink / raw) To: Stéphane Aulery Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
[parent not found: <54FC0369.3010705-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]
* Re: undocumented man pages [not found] ` <54FC0369.3010705-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> @ 2015-03-08 11:12 ` Stéphane Aulery [not found] ` <20150308111240.GA1839-GANU6spQydw@public.gmane.org> 0 siblings, 1 reply; 5+ messages in thread From: Stéphane Aulery @ 2015-03-08 11:12 UTC (permalink / raw) To: Michael Kerrisk (man-pages); +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
[parent not found: <20150308111240.GA1839-GANU6spQydw@public.gmane.org>]
* Re: undocumented man pages [not found] ` <20150308111240.GA1839-GANU6spQydw@public.gmane.org> @ 2015-03-09 7:06 ` Michael Kerrisk (man-pages) [not found] ` <CAKgNAkhvGtPMwq1kdf-ZJZ=FNGQqLjHuyakgbaUqLbdhAueL-A-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org> 0 siblings, 1 reply; 5+ messages in thread From: Michael Kerrisk (man-pages) @ 2015-03-09 7:06 UTC (permalink / raw) To: Stéphane Aulery; +Cc: linux-man 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
[parent not found: <CAKgNAkhvGtPMwq1kdf-ZJZ=FNGQqLjHuyakgbaUqLbdhAueL-A-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>]
* Re: undocumented man pages [not found] ` <CAKgNAkhvGtPMwq1kdf-ZJZ=FNGQqLjHuyakgbaUqLbdhAueL-A-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org> @ 2015-03-09 8:10 ` Stéphane Aulery 0 siblings, 0 replies; 5+ messages in thread From: Stéphane Aulery @ 2015-03-09 8:10 UTC (permalink / raw) To: Michael Kerrisk (man-pages); +Cc: linux-man 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2015-03-09 8:10 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2015-03-07 14:57 undocumented man pages Stéphane Aulery [not found] ` <20150307145716.GA24297-GANU6spQydw@public.gmane.org> 2015-03-08 8:08 ` Michael Kerrisk (man-pages) [not found] ` <54FC0369.3010705-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 2015-03-08 11:12 ` Stéphane Aulery [not found] ` <20150308111240.GA1839-GANU6spQydw@public.gmane.org> 2015-03-09 7:06 ` Michael Kerrisk (man-pages) [not found] ` <CAKgNAkhvGtPMwq1kdf-ZJZ=FNGQqLjHuyakgbaUqLbdhAueL-A-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org> 2015-03-09 8:10 ` Stéphane Aulery
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.