Feature changed by: Thomas Schraitle (thomas-schraitle) Feature #305336, revision 24 Title: Ship man page for every executable openSUSE-11.2: Evaluation 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 -- openSUSE Feature: https://features.opensuse.org/305336