Feature changed by: Thorsten Kukuk (kukuk) Feature #305336, revision 41 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 Requested by: Matthias Eckermann (mge1512) 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 -- openSUSE Feature: https://features.opensuse.org/305336