Help

Using the manual pages

man<commando> prints out manual of the commando.

It looks for pages in the directories shown by echo $MANPATH

Q quits man (Don't use Ctrl Z since this stops it but leaves it in memory)

H brings up help for man

Ctrl Y scrolls up

man -k<command> shows sections of the manual page

man 1<command> shows the manual page in the user command section

The numbers are:

1

User (or shell) commands

2

System

3

c functions

4

File formats device files

5

Config files

6

Games

7

Miscellaneous

8

System administration

9

Kernel

After emerge xman on the console type xman a small window appears where you have to press the Manual Page button, then an ugly window appears where you select search to find the page.

Man pages on the web

Instead of installing a program as xman to read the locally stored man pages, simply browse the web for man <command>

Advantage: Nice browser environment, also man pages not installed can be read

Disadvantage: Might be out of date and not synchronized with your installation

Info pages

As man there are are also info pages.

info<command>

Using documentation from the packages

In /usr/share/doc documentation about installed packages can be found.

/usr/src/linux/Documentation contains the Linux kernel documentation

A good way is looking what has been installed with the package.

Gentoo records this in /var/db/pkg

Gui tools as porthole show this nicely.

Gentoo has the doc useflag that controls if documentation is installed or not. There are also ebuilds that do not install the documentation at all.

Therefore check in /usr/portage/distfiles and extract it somewhere or if there is no dist file fetch it:

ebuild /usr/portage/sys-apps/sandbox/sandbox-1.2.18.1-r2.ebuild fetch

There is also automatically generated documentation from the source as using doxygen. Install doxygen. Go to the directory containing doxyfile and then type doxygen to create the documentation.

Writing your own man pages

Writing your own man pages can be done with every text editor. The filename is the topic followed by a dot an the section number <mymanpage>.1. A special syntax is used to format the page man 7 man explains it or just open a man page with a regular editor and learn from it. troff escape sequences that start with \ are used to format fonts

man troff or

man 7 groff

\- means print the - character
\fB means change to font B = bold

Avoid making empty lines, since this will create warnings later on. Then the page can be compressed to gz archive <mymanpage>.1.gz or left as it is. Then the page is copied in Gentoo in the corresponding section folder as: (/usr/share/man/man1)

Alternatively man pages can be created automatically from what they return from --help or -h after installing help2man using a command as:

help2man<path to>/<the program> -o <the program>.1

or with suppressing link to info pages help2man -N gencfs.py -o gencfs.1

or include stuff going to stderr

help2man --no-discard-stderr -N ./<name of program> -o <name of program>.1

Automatic generation is the best way, since not much to do, little maintenance of the man page, guaranteed consistency. For details see: http://www.gnu.org/software/help2man/. Finally test it man gencfs.1

The package man comes with man2html see man man2html how to convert a man page into html.

man2html does html but not xhtml.

man2html <name of man page>.1 > <name of man page>.html

Caution

Instead of the man package, man-db might be installed.


Linurs startpage