Mailinglist Archive: opensuse-features (226 mails)

< Previous Next >
[openFATE 305336] Ship man page for every executable
  • From: fate_noreply@xxxxxxx
  • Date: Wed, 4 Feb 2009 15:17:00 +0100 (CET)
  • Message-id: <feature-305336-22@xxxxxxxxxxxxxx>
Feature changed by: Matthias Eckermann (mge1512)
Feature #305336, revision 22
- Title: [NONCODE] Ship man page for every executable
+ 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:
- 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.



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

< Previous Next >
This Thread