Skip to main content

By clicking Submit, you agree to the developerWorks terms of use.

The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

  • Close [x]

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

By clicking Submit, you agree to the developerWorks terms of use.

All information submitted is secure.

  • Close [x]

developerWorks Community:

  • Close [x]

LPI exam 102 prep, Topic 108: Linux documentation

Junior Level Administration (LPIC-1) topic 108

Ian Shields, Senior Programmer, IBM developerWorks
Ian Shields
Ian Shields works on a multitude of Linux projects for the developerWorks Linux zone. He is a Senior Programmer at IBM at the Research Triangle Park, NC. He joined IBM in Canberra, Australia, as a Systems Engineer in 1973, and has since worked on communications systems and pervasive computing in Montreal, Canada, and RTP, NC. He has several patents and has published several papers. His undergraduate degree is in pure mathematics and philosophy from the Australian National University. He has an M.S. and Ph.D. in computer science from North Carolina State University. Learn more about Ian in Ian's profile on developerWorks Community.
(An IBM developerWorks Contributing Author)

Summary:  In this tutorial, Ian Shields continues preparing you to take the Linux Professional Institute® Junior Level Administration (LPIC-1) Exam 102. In this fourth in a series of nine tutorials, Ian introduces you to Linux® documentation. By the end of this tutorial, you will know how to use and manage local documentation, find documentation on the Internet, and use automated logon messages to notify users of system events.

View more content in this series

Date:  20 Sep 2006
Level:  Intermediate PDF:  A4 and Letter (478 KB | 21 pages)Get Adobe® Reader®

Activity:  20411 views
Comments:  

Local documentation

This section covers material for topic 1.108.1 for the Junior Level Administration (LPIC-1) exam 102. The topic has a weight of 4.

In this section, learn how to:

  • Find relevant man pages
  • Search man page sections
  • Find commands and man pages related to them
  • Configure access to man sources and the man system
  • Prepare man pages for printouts
  • Use the system documentation stored in /usr/share/doc/ and determine what documentation to keep in /usr/share/doc/

Find man pages

The primary (and traditional) source of documentation is the manual pages, which you can access using the man command. Ideally, you can look up the man page for any command, configuration file, or library routine. In practice, Linux is free software, and some pages haven't been written or are showing their age. Nonetheless, man pages are the first place to look when you need help. Figure 1 illustrates the manual page for the man command itself. Use the command man man to display this information.


Figure 1. Man page for the man command
Man page for man command

Figure 1 shows some typical items in man pages:

  1. A heading with the name of the command followed by its section number in parentheses
  2. The name of the command and any related commands that are described on the same man page
  3. A synopsis of the options and parameters applicable to the command
  4. A short description of the command
  5. Detailed information on each of the options

You may find other sections on usage, how to report bugs, author information, and a list of any related commands. For example, the man page for man tells us that related commands (and their manual sections) are:

apropos(1), whatis(1), less(1), groff(1), and man.conf(5).

Man pages are displayed using a pager, which is usually the less command on Linux systems. You can set this using the $PAGER environment variable, or by using the -P or --pager option, along with another pager name, on the man command. The pager will receive its input on stdin, so something like an editor that expects a file to manipulate does not work as a pager.

There are eight common manual page sections. Manual pages are usually installed when you install a package, so if you do not have a package installed, you probably won't have a manual page for it. Similarly, some of your manual sections may be empty or nearly empty. The common manual sections, with some example contents are:

  1. User commands (env, ls, echo, mkdir, tty)
  2. System calls or kernel functions (link, sethostname, mkdir)
  3. Library routines (acosh, asctime, btree, locale, XML::Parser)
  4. Device-related information (isdn_audio, mouse, tty, zero)
  5. File format descriptions (keymaps, motd, wvdial.conf)
  6. Games (note that many games are now graphical and have graphical help outside the man page system)
  7. Miscellaneous (arp, boot, regex, unix utf8)
  8. System administration (debugfs, fdisk, fsck, mount, renice, rpm)

Other man page sections that you might find include 9 for Linux kernel documentation, n for new documentation, o for old documentation, and l for local documentation.

Some entries appear in multiple sections. Our examples show mkdir in sections 1 and 2, and tty in sections 1 and 4.

The info command

In addition to the standard manual pages, the Free Software Foundation has created a number of info files that are processed with the info program. These provide extensive navigation facilities including the ability to jump to other sections. Try man info or info info for more information. Not all commands are documented with info, so you will find yourself using both man and info if you become an info user. You can also start at the top of the info tree by using info without parameters as shown in Listing 1.


Listing 1. The info command
File: dir,      Node: Top       This is the top of the INFO tree

  This (the Directory node) gives a menu of major topics.
  Typing "q" exits, "?" lists all Info commands, "d" returns here,
  "h" gives a primer for first-timers,
  "mEmacs<Return>" visits the Emacs manual, etc.

  In Emacs, you can click mouse button 2 on a menu item or cross reference
  to select it.

* Menu:

Utilities
* Bash: (bash).                     The GNU Bourne-Again SHell.
* Enscript: (enscript).             GNU Enscript
* Gzip: (gzip).                 The gzip command for compressing files.
* ZSH: (zsh).                     The Z Shell Manual.

Libraries
* AA-lib: (aalib).              An ASCII-art graphics library
* History: (history).       The GNU history library API
* Libxmi: (libxmi).           The GNU libxmi 2-D rasterization library.
* Readline: (readline).       The GNU readline library API


Texinfo documentation system
* Info: (info).                 Documentation browsing system.
-----Info: (dir)Top, 2104 lines --Top-------------------------------------------
Welcome to Info version 4.6. Type ? for help, m for menu item.

        

Graphical man page interfaces

In addition to the standard man command, which uses a terminal window and a pager, your system may also have one or more graphical interfaces to manual pages, such as xman (from the XFree86 Project) and yelp (the Gnome help browser).

When you start xman, you will see a small window with three buttons. Click the Manual Page button to open a larger window where you can navigate through manual pages or search for information. Figure 2 shows an example of both windows.


Figure 2. Using xman
Using xman

The yelp browser usually looks somewhat different from system to system. Figure 3 shows an example on Ubuntu 6.06. You can access either the man pages or the info pages using the Command Line Help item at the bottom of the display.


Figure 3. Using yelp on Ubuntu
Using yelp on Ubuntu

Search man pages

If you know that a topic occurs in a particular section, you can specify the section. For example, man 4 tty or man 2 mkdir. An alternative is to use the -a option to display all applicable manual sections. If you specify -a, you will be prompted after quitting the page for each section. You may skip the next page, view it, or quit altogether.

As you saw earlier, some topics exist in more than one section. If you don't want to search through each section, you can use the -aw options of man to get a list of all available man pages for a topic. Listing 2 shows an example for printf. If you were writing a portable shell script, you might be interested in man 1p printf to learn about the POSIX version of the printf command. On the other hand, if you were writing a C or C++ program, you would be more interested in man 3 printf, which would show you the documentation for the printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, and vsnprintf library functions.


Listing 2. Available man pages for printf
ian@lyrebird:~> man -aw printf
/usr/share/man/man1/printf.1.gz
/usr/share/man/man1p/printf.1p.gz
/usr/share/man/man3/printf.3.gz

The man command pages output onto your display using a paging program. On most Linux systems, this is likely to be the less program. Another choice might be the older more program.

The less pager has several commands that help you search for strings within the displayed output. These are similar to vi editing commands. Use man less to find out more about / (search forwards), ? (search backwards), and n (repeat last search), among many other commands.

The info command comes from the makers of emacs, so the searching commands are more like emacs commands. For example, ctrl-s searches forwards and ctrl-r searches backwards using an incremental search. You can also move around with the arrow keys, follow links (indicated with a star) using the Enter key, and quit using q. Use the --vi-keys option with info if you'd prefer similar key bindings to those used for man.


Find commands

Two important commands related to man are whatis and apropos. The whatis command searches man pages for the name you give and displays the name information from the appropriate manual pages. The apropos command does a keyword search of manual pages and lists ones containing your keyword. Listing 3 illustrates these commands.


Listing 3. Whatis and apropos examples
[ian@lyrebird ian]$ whatis man
man                  (1)  - format and display the on-line manual pages
man                  (7)  - macros to format man pages
man [manpath]        (1)  - format and display the on-line manual pages
man.conf [man]       (5)  - configuration data for man
[ian@lyrebird ian]$ whatis mkdir
mkdir                (1)  - make directories
mkdir                (2)  - create a directory
[ian@lyrebird ian]$ apropos mkdir
mkdir                (1)  - make directories
mkdir                (2)  - create a directory
mkdirhier            (1x)  - makes a directory hierarchy

By the way, if you cannot find the manual page for man.conf, try running man man.config instead, which works on some systems.

The apropos command can produce a lot of output, so you may need to use more complex regular expressions rather than simple keywords. Alternatively, you may wish to filter the output through grep or another filter to reduce the output to something more of interest. As a practical example, you can use the e2label to display or change the label on an ext2 or ext3 filesystem, but you have to use another command to change the label on a ReiserFS filesystem. Suppose you run mount to display the mounted ResiserFS filesystems as shown in Listing 4.


Listing 4. Mounted ReiserFS filesystems
ian@lyrebird:~> mount -t reiserfs
LABEL=SLES9 on / type reiserfs (rw,acl,user_xattr)

Now you'd like to know what partition corresponds to the label SLES9, but you can't remember the command. Using apropos label might get you a couple of dozen responses, which isn't too bad to sift through. But wait. This command must have something to do with a filesystem of a volume. So you try the regular expressions shown in Listing 5.


Listing 5. Using apropos with regular expressions
ian@lyrebird:~> apropos "label.*file"
e2label (8)          - Change the label on an ext2/ext3 filesystem
ntfslabel (8)        - display/change the label on an ntfs file system
ian@lyrebird:~> apropos "label.*volume"
label.*volume: nothing appropriate.

Not exactly what you were looking for. You could try reversing the order of the terms in the regular expressions, or you could try filtering through grep or egrep as shown in Listing 6.


Listing 6. Filtering the output of apropos
ian@lyrebird:~> apropos label | grep -E "file|volume"
e2label (8)          - Change the label on an ext2/ext3 filesystem
mlabel (1)           - make an MSDOS volume label
ntfslabel (8)        - display/change the label on an ntfs file system
findfs (8)           - Find a filesystem by label or UUID

And there's the command that we need, findfs. Using it as shown in Listing 7 shows that the filesystem is on /dev/hda10 on this particular system.


Listing 7. Finding the device for a mounted filesystem label
ian@lyrebird:~> /sbin/findfs LABEL=SLES9
/dev/hda10

Note that non-root users will usually have to give the full path to the findfs command.

As you can find out in the man page for the man command, you can also use man -k instead of apropos and man -f instead of whatis. Since these call the apropos or whatis command under the covers, there is probably little point in so doing.


Configuration

Manual pages may be in many locations on your system. You can determine the current search path using the manpath command. If the MANPATH environment variable is set, this will be used for searching for manual pages; otherwise, a path will be built automatically using information from a configuration file that we'll discuss in a moment. If the MANPATH environment variable is set, the manpath command will issue a warning message to this effect before displaying the path.


Listing 8. Displaying your MANPATH
[ian@echidna ian]$ manpath
/usr/local/share/man:/usr/share/man:/usr/X11R6/man:/usr/local/man

ian@lyrebird:~> manpath
manpath: warning: $MANPATH set, ignoring /etc/manpath.config
/usr/local/man:/usr/share/man:/usr/X11R6/man:/opt/gnome/share/man

Depending on your system, configuration information for the man system is stored in /etc/man.config or /etc/manpath.confg. Older systems use /etc/man.conf. A current man.config file contains a list of directories (MANPATHs) that will be searched for manual pages, such as those shown in Listing 9.


Listing 9. MANPATH entries from /etc/man.config
MANPATH /usr/share/man
MANPATH /usr/man
MANPATH /usr/local/share/man
MANPATH /usr/local/man
MANPATH /usr/X11R6/man

In a manpath.config file, these entries will be MANDATORY_MANPATH entries, rather than MANPATH entries.

Besides these entries, you will also find entries giving a mapping between paths where executables may be found, and paths where the corresponding man pages might be, as shown in Listing 10.


Listing 10. MANPATH_MAP entries from /etc/man.config
MANPATH_MAP     /bin                    /usr/share/man
MANPATH_MAP     /sbin                   /usr/share/man
MANPATH_MAP     /usr/bin                /usr/share/man
MANPATH_MAP     /usr/sbin               /usr/share/man
MANPATH_MAP     /usr/local/bin          /usr/local/share/man

The man command uses a complicated method for searching for man pages, and setting these values will result in less wasted effort when searching for pages.

Another entry in the configuration file defines the search order for manual pages. Recall that the default is to display the first page found, so this ordering is important. Look near the bottom of man.config for a MANSECT line, or near the bottom of manpath.config for a SECTION line. Examine the configuration file on your system to see what other things can be configured.

You may have noticed that the apropos and whatis commands ran quickly. This is because they do not actually search the individual manual pages. Rather, they use a database created by the makewhatis command. This is usually run by the system either daily or weekly as a cron job.


Listing 11. Running makewhatis
[root@echidna root]# makewhatis

The command completes normally without any output message, but the whatis database is refreshed. This is usually stored in a location such as /var/cache/man/whatis. Note that some SUSE systems do not use the whatis database and therefore do not have a makewhatis command.


Printing man pages

If you wish to print the page, specify the -t option to format the page for printing using the groff or troff program. This will format the page for the default printer and send the output to stdout. Listing 12 shows how to format the man page for the ls command and save the output in a file, ls.ps. Figure 4 shows the formatted output.


Listing 12. Formatting the ls manpage for printing
ian@pinguino:~$ man -t ls > ls.ps


Figure 4. Formatted ls man page
Formatted ls man page

If you need to format the page for a different device type, use the -T options with a device type, such as dvi or ps. See the man page for man for additional information.


/usr/share/doc/

In addition to the manual pages and info pages that you have already seen, your Linux system probably includes a lot more documentation. The customary place to store this is in /usr/share/doc, or /usr/doc on older systems. This additional documentation may be in any of several formats, such as text, PDF, PostScript, or HTML.

Searching through this documentation can often reveal gems that aren't available as man pages or info pages, such as tutorials or additional technical documentation. As Listing 13 shows, there can be a large number of files in /usr/share/doc, so you have plenty of reading resources.


Listing 13. Files in /usr/share/doc
ian@pinguino:~$ find /usr/share/doc -type f | wc -l
10144

Figure 5 shows an example of the HTML help for the Texinfo system that is used for the info command that you saw earlier.


Figure 5. Texinfo HTML help from /usr/share/doc
Texinfo HTML help from /usr/share/doc

Sometimes, a man page will direct you to another source for documentation. For example, the man page for the pngtopnm command is shown in Listing 14. It directs you to a local copy in HTML format at /usr/share/doc/packages/netpbm/doc/pngtopnm.html, or to an online version if you do not have the local copy.


Listing 14. Pointer man page for pngtopnm
pngtopnm(1)          Netpbm pointer man pages         pngtopnm(1)



pngtopnm  is part of the Netpbm package.  Netpbm documentation is
kept in HTML format.

Please refer to
 <http://netpbm.sourceforge.net/doc//pngtopnm.html>.

If that doesn't work,  also  try  <http://netpbm.sourceforge.net>
and emailing Bryan Henderson, bryanh@giraffe-data.com.

Local copy of the page is here:
 /usr/share/doc/packages/netpbm/doc/pngtopnm.html

Other command help

Finally, if you can't find help for a command, try running the command with the --help, --h, or --? option. This may provide the command's help, or it may tell you how to get the help you need. Listing 15 shows an example for the kdesu command, which is usually present on systems with a KDE desktop.


Listing 15. Getting help for kdesu command
ian@lyrebird:~> man kdesu
No manual entry for kdesu
ian@lyrebird:~> kdesu --help
Usage: kdesu [Qt-options] [KDE-options] command

Runs a program with elevated privileges.

Generic options:
  --help                    Show help about options
  --help-qt                 Show Qt specific options
  --help-kde                Show KDE specific options
  --help-all                Show all options
  --author                  Show author information
  -v, --version             Show version information
  --license                 Show license information
  --                        End of options

Arguments:
  command                   Specifies the command to run.

Options:
  -c <command>              Specifies the command to run. []

The next section covers online resources for help with Linux.

2 of 6 | Previous | Next

Comments



static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Linux, Open source
ArticleID=161154
TutorialTitle=LPI exam 102 prep, Topic 108: Linux documentation
publish-date=09202006
author1-email=ishields@us.ibm.com
author1-email-cc=