16.1. Objective 1: Use and Manage Local System DocumentationEach Linux system is configured by default with extensive documentation from developers, authors, and Linux community members. With these documentation projects combined, your Linux distribution offers a comprehensive body of knowledge to enhance your skills as a sysadmin. 16.1.1. Text Files and PagingAt a fundamental level, documents stored electronically may be encoded in a variety of formats. For example, most word processors use proprietary file formats to store characters, text formatting, and printing control languages. While these relatively modern applications can be found on your Linux system, most of the documents and configuration files for both the operating system and system tools are in plain text. In the context of Linux systems, plain text means files or streams of both printable characters and control characters. Each is represented using a standard encoding scheme, such as the American Standard Code for Information Interchange (ASCII) or one of its relatives. Text files are most conveniently viewed using a paging program. 16.1.1.1. Paging programsA paging program displays contents of a text file one "page" at a time. Paging programs have the advantage of speed and simplicity over text editors (such as vi) because only pieces of the text files are loaded into a buffer at a time, instead of the entire file. In addition, since paging programs cannot edit file contents directly, unless you tell them to invoke an editor, there isn't a chance of accidentally changing a file. The two paging applications commonly used on Linux are more and less. The more tool is named because it gives you "one more screen." Humorously, the less command is so known because "less is more." more is the older of the two Unix paging systems and has limited capabilities, though more has been beefed up on Linux systems compared to their original Unix versions. The standard Unix more simply presents you with the text document one screen at a time, progressing forward through the screens with the spacebar. This functionality is shadowed by less's ability to move both forward and backward through a file, either line by line or a full screen at a time utilizing cursor keys and page up and page down keys, as well as standard vi movement keystrokes such as j, k, G, and so on. While both more and less on Linux have the ability for multidirectional movement and advanced searching capability, less has more movement options and supports more keyboard functions. As a sysadmin, you will have the most exposure to these programs while reviewing manpages and system documentation. 16.1.2. ManpagesTraditional computer manuals covered everything from physical maintenance to programming libraries. While the books were convenient, many users didn't always want to dig through printed documentation or carry it around. So, as space became available, the man (manual) command was created to put the books on the system, allowing users immediate access to the information they needed in a searchable, quick-reference format. There is a manpage for most commands on your system. There are also manpages for important files, library functions, shells, languages, devices, and other features. man is to your system what a dictionary is to your written language. That is, nearly everything is defined in detail, but you probably need to know in advance just what you're looking for.
16.1.2.1. Manual sectionsManpages are grouped into sections, and there are times when you should know the appropriate section in which to search for an item. For example, if you were interested in the mkfifo C-language function rather than the command, you must tell the man program to search the section on library functions (in this case, section 3, Linux Programmer's Manual): $ man 3 mkfifo An alternative would be to have the man program search all manual sections : $ man -a mkfifo The first example returns the mkfifo(3) manpage regarding the library function. The second returns pages for both the command and the function. In this case, the pages are delivered separately; terminating the pager on the first manpage with Ctrl-C causes the second to be displayed. Manual sections are detailed in Table 16-1.
Tip: Some systems might also have sections 9, n, and others, but only sections 1 through 8 are defined by the FHS. The order in which man searches the sections for manpages is controlled by the MANSECT environment variable. MANSECT contains a colon-separated list of section numbers. If it is not set, man (as of Version 1.5k) behaves as if it were set to 1:8:2:3:4:5:6:7:9:tcl:n:l:p:o. 16.1.2.2. Manpage formatMost manpages are presented in a concise format with information grouped under well-known standard headings such as those shown in Table 16-2. Other manpage headings depend on the context of the individual manpage.
16.1.2.3. man mechanicsSystem manpages are stored in /usr/share/man and elsewhere. At any time, the manual pages available to the man command are contained within directories configured in your man configuration file, /etc/man.config. This file contains directives to the man, telling it where to search for pages (the MANPATH directive), the paging program to use (PAGER), and many others. This file essentially controls how man works on your system. To observe this, use the debug (-d) option to man to watch as it constructs a manpath (a directory search list) and prepares to display your selection: $ man -d mkfifo 16.1.3. Information in /usr/share/docManpages are particularly useful when you know what you're looking for, or at least have some good leads on how to find it. However, they are not tutorial in nature, nor do they often describe overall concepts. Fortunately, individuals in the Linux world not only contribute their programming skills, but many also generate excellent tutorial documents to assist others with features, procedures, or common problems. Many of these documents end up as HOWTO guides, FAQs (lists of Frequently Asked Questions), README files, or even exhaustive user manuals. These documents are often part of the source distribution of a particular program and, while valuable, don't fit elsewhere on the Linux system and are deposited in /usr/share/doc. Most of these files are ASCII text, which can be viewed with a pager, such as less, or with your favorite text editor. Some documents may be written in HTML for use with your web browser. Some text files may also be compressed with the gzip program and thus have the .gz extension. Tip: /usr/share/doc is not required by the FHS, so its contents and layout are distribution-specific. 16.1.4. Info PagesThe Free Software Foundation (http://www.fsf.org) has moved much of the documentation for the GNU project to a documentation format called info. Info pages are part of a system called Texinfo, which uses a single source file to display information on screen and on paper. Texinfo is hypertext and creates a browserlike interface on a terminal or terminal window (Emacs users will recognize the menu system as the editor's online help). For GNU software, Texinfo is the definitive documentation mechanism. Texinfo can be viewed by running the info command. For example, the texinfo document on mkfifo can be displayed using the following command: $ info mkfifo The result will be a display similar to the example in Figure 16-1. Figure 16-1. Info display in a terminal windowBasic navigation commands for the info system are listed in Table 16-3.
Tip: Many Linux distributions also include the info viewer pinfo, which works much like the text-based web browser lynx. Manpages and other types of system documentation are packaged and installed by default with most Linux distributions. For example, this means that both the manpage and executable program for wc are contained in the coreutils (or textutils on older distributions) package. Other documentation, such as Linux Documentation Project (LDP) guides and HOWTOs, may be contained in standalone packages, depending on the distribution. |