Feature changed by: Matthias Eckermann (mge1512) Feature #305336, revision 61 Title: Ship man page for every executable openSUSE-11.2: Rejected by Andreas Jaeger (a_jaeger) reject date: 2009-08-11 15:41:47 reject reason: This is a task that should be done in cooperation with the upstream projects. Priority Requester: Mandatory - openSUSE-11.4: Evaluation by product manager + openSUSE-11.4: Rejected by Matthias Eckermann (mge1512) + reject date: 2011-03-26 09:25:38 + reject reason: closing here, opening new Priority Requester: Important Info Provider: (Novell) - Info Provider: (Novell) Requested by: Matthias Eckermann (mge1512) Product Manager: (Novell) Product Manager: (Novell) Project Manager: (Novell) Engineering Manager: (Novell) Partner organization: openSUSE.org Description: 1. Even graphical applications need docs outside the application itself. The need to run the application, to know what does it does, is not good. 2. You need a standard documentation format; where standard = expected for people needing that documentation. Who are, often, not knowing the distro well (so the format can't be distro-specific). And the format must be the same for all binaries/packages. One can't rely on the fact it will always be easy and intuitive to find that some application is part KDE (for example) and one can get the documentation in konqueror when typing 'help:/application'. 3. To view the documentation must be as easy as possible and with as minimal resources as possible. This is why online documentation is not so good (you need a running Internet net connection), documentation in a web browser as well (you need X and graphical desktop). HTML is questionable as it (as a format) allows so many extensions that it is needed to expect that such documentation will not be readable in text browsers after some time. 4. Many parts are shared between openSUSE and the enterprise products. And, in the enterprise world, we need to be much more standard conforming. Including the documentation. A UNIX admin will use the 'man' command for getting info about the binary. 'info' system is here as well, for many years. But 'man' is still more usual. Imagine a server room with hundreds/thousands of servers of several UN*X clones - 'man' works everywhere, and Linux is expected to be "on par" also with respect to those capabilities. These four points stay behind the idea of man pages needed and provided for everything. Relations: - How to Create Manpages with DocBook (url: http://en.opensuse.org/Manual_Pages/How_to_Create_Manpages_with_DocBook) - At http://en.opensuse.org/Manual_Pages/Missing a list of all packages with missing man pages can be found (url: http://en.opensuse.org/Manual_Pages/Missing) Use Case: User / Administrator should find a dedicated man page for every executable in openSUSE and SUSE Linux Enterprise systems. Discussion: #2: Stefan Behlert (sbehlert) (2008-10-22 15:00:11) I agree with the intention, but shouldn't it be rather 'documentation for each executable'? Newer stuff uses mostly info-pages, afaiks #3: Matthias Eckermann (mge1512) (2008-11-10 14:31:15) (reply to #2) It is valid to have a pointer to the info pages in the man-pages, sure. But man-pages are the UNIX proposed way of doing documentation. #9: Thomas Schraitle (thomas-schraitle) (2009-02-20 09:54:09) IMHO DocBook would be very suitable for this task as nobody has to learn the awkward syntax of groff/troff/... For example, I've submitted a DocBook file to the scout author and he generates the manpage with the DocBook stylesheets automatically. If you think, a manpage is not enough, each DocBook file can be easily transformed into (X)HTML, PDF, or almost any other output formats. IHMO it saves time if you want to support more formats than just manpage. The whole process is documented here: http://en.opensuse.org/Manual_Pages/How_to_Create_Manpages_with_DocBook #10: Jan Engelhardt (jengelh) (2009-02-21 20:31:14) (reply to #9) Manpages are very suitable for this task as nobody has to learn the awkward DocBook syntax. If done right, manpages are just another markup language and there are just a few elements one needs to know. (You can even count them in your hands: .TH, .SH, .SS, .PP, .TP, .nf/.fi, \fB, \fI, \fP, and sometimes . IP. They almost map to HTML's title, h1, h2, p, (no direct eqv), pre, b, i, /b|/i, and ol|ul, respectively.) #11: Praveen Kunjapur (stilo_vingyou) (2009-04-09 21:38:39) Knowledge is power. #13: Thorsten Kukuk (kukuk) (2009-08-17 22:17:33) We have a huge amount of orphaned packages, there is no chance to do any additional work on this feature. #21: Juergen Weigert (jnweiger) (2009-09-07 17:36:35) No. I cannot even estimate what the docimpact might be. Someone please collect a list of executables, and describe what kind of work is expected on them. Then we can make estimates. From the above comments #13 to #18 I cannot extract useful information. #22: Thorsten Kukuk (kukuk) (2009-09-10 09:53:11) It is still not clear to me what PM is expecting. For adding all the manual pages to every single RPM we don't have the resources, meanwhile the strategy and resource situation changed dramatically. And touching all RPMs would mean, that an online update is nearly impossible, customers have to download nearly every installed RPM. Else I can only repeat my comment #15 #34: Thomas Schraitle (thomas-schraitle) (2009-09-10 14:29:21) I don't think some issues in this entry are really covered yet -- apart from any future decision: 1) Writing manpages for all executables is illusionary. This task has to be and can only be handled by the corresponding upstream projects. Maybe you can convince the project maintainers to improve their documentation in this regard or support them with trainees or the like. But it's a longterm goal, not something done between two months. 2) Firefox is an executable. Does it need a manpage? I would say no, it has other documentation. What qualifies an executable to get a manpage? Where do you draw the line? 3) Writing a manpage is one thing, maintaining it is another. As experience shows, sometimes you have significant changes between one version and the other. Which should be covered in the manpage, of course. Again, this can not be done inhouse, it is a task which can only be written by the upstream projects accordingly. 4) As already written in comment #21, no list is/was collected. 5) As outlined, IHMO documentation departement is the wrong addressee. #35: Matthias Eckermann (mge1512) (2009-09-10 14:53:27) (reply to #34)

I don't think some issues in this entry are really covered yet -- apart from any future decision: Be sure that this has been discussed already in depth, e.g. by the PM Team within SUSE/Novell. Writing manpages for all executables is illusionary. This task has to be and can only be handled by the corresponding upstream projects. Man pages do exist for most binaries in the open source community, many also independendly of the respective projects. The Debian community has done a great job here, and it could be useful to join the forces of openSUSE community with Debian here. ... Maybe you can convince the project maintainers to improve their documentation in this regard or support them with trainees or the like. But it's a longterm goal, not something done between two months. That's why the feature already exists for one year, ... Firefox is an executable. Does it need a manpage? I would say no, it has other documentation. What qualifies an executable to get a manpage? Where do you draw the line? In the Enterprise world every binary needs a man page. Including Firefox and all Gnome and KDE applications. One reason for that: no administrator wants to have binaries around, where (s)he cannot say, what it is used for. This might also be a matter of "compliance". I agree however that this is different for openSUSE and the community. Writing a manpage is one thing, maintaining it is another. As experience shows, sometimes you have significant changes between one version and the other. Which should be covered in the manpage, of course. Again, this can not be done inhouse, it is a task which can only be written by the upstream projects accordingly. Agreed. As already written in comment #21, no list is/was collected. This is wrong. In the package "man-pages-supplement" a script exists, to list all binaries without a man-page already. Thus the analysis itself is not difficult. The doing is the challenge. Indeed.

#37: Pavol Rusnak (prusnak) (2009-09-10 14:54:24) (reply to #34) 2. EVERY executable, the title of the feature says it all. Even if the manpage only contains "Firefox is a web browser" it is better than nothing. 4. Wrong, list is attached as external reference - http://en.opensuse.org/Manual_Pages/Missing (I collected it in February 2009, so it is a little bit outdated). 5. I don't think this could be done in one departement, because this is huge amount of work. We could start adopting already written manpages from Debian, but still a longterm issue. #38: Thomas Schraitle (thomas-schraitle) (2009-09-10 15:32:43) (reply to #37)

4. Wrong, list is attached as external reference - http://en.opensuse.org/Manual_Pages/Missing (I collected it in February 2009, so it is a little bit outdated). Thanks Pavol, for the reminder. The list is one part and we know what's missing. That's good. However, what we don't know is the effort/amount of work to make it. It can be a very short one, or something that is really complicated and you need special knowledge. Maybe some could be autogenerated.

-- openSUSE Feature: https://features.opensuse.org/305336