10.4 Documentation (Topic 1.8)

10.4.1 Objective 1: Use and Manage Local System Documentation

10.4.1.1 Text and paging

• In the context of Linux systems, plain text means files or streams of both printable characters and control characters, using a standard encoding scheme such as ASCII.

• Differentiating text from nontext isn't obvious, but the file command examines a file given as its argument and offers a response that indicates the file type.

• A pager is a program intended to offer a quick and simple interface for viewing text files, one screen at a time.

• more is a popular pager available on most Unix systems.

• less is a full-featured text pager, which emulates more and offers significant advantages. Common less commands are listed in Table 10-6.

Table 10-6. Common less Commands

less Command	Description
Space	Scroll forward one screen.
D	Scroll forward one-half screen.
Return	Scroll forward one line.
B	Scroll backward one screen.
U	Scroll backward one-half screen.
Y	Scroll backward one line.
g	Go to the beginning of the text (could be slow with large amounts of text).
G	Go to the end of the text (could be slow with large amounts of text).
/pattern	Search forward for pattern, which can be a regular expression.
?pattern	Search backward for pattern, which can be a regular expression.
H	Display a help screen.
:n	Display next file from command line (two-character command).
:p	Display previous file from command line (two-character command).

• A pager such as less is used by the man facility.

10.4.1.2 The man facility

• A manpage exists for most commands and is viewed using man:

  man [section] command

  Format and display manpages from the manual section based on the topic of command using a pager.

• Manpages are usually found in the /usr/man directory, but they can also be found elsewhere in the filesystem. The manpage location can be found in /etc/man.config, along with the paging program to use and other information about the manpages.

10.4.1.3 /usr/doc

• Many documents for Linux systems are available in /usr/doc . Included here are package-related documents, FAQs, HOWTOs, and so on.

10.4.1.4 The info facility

• The Free Software Foundation provides the info documentation format.

• GNU software comes with info documentation.

• The documentation is viewed with the info command, which displays a full-screen editor-like paging system. Common info commands are listed in Table 10-7.

Table 10-7. Common info Commands

info Command	Description
Tab	Move among hypertext links.
Enter	Follow hypertext links.
d	Return to the top (directory node) of the menu.
?	List all info commands.
p and n	Move to previous and next pages, respectively.
u	Move up one level in the Texinfo hierarchy.
q	Terminate the system.
h	Give a primer for first-time users.
/string	Enter a string.
/pattern	Search forward for pattern, which can be a regular expression.

10.4.2 Objective 2: Find Linux Documentationon the Internet

10.4.2.1 Linux Documentation Project

• A loosely knit team of writers, proofreaders, and editors who work together to create the definitive set of documentation for Linux. The Linux Documentation Project can be found online at http://www.linuxdoc.org/.

• The LDP has a wide range of documents, from complete books to personal accounts of problem-solving techniques.

10.4.2.2 Other sources

• Many Usenet newsgroups, such as comp.os.linux, comp.os.linux.advocacy, comp.os.linux.development, and others, are dedicated to Linux.

• Mailing lists offered by many Linux groups serve to keep members informed through email distribution of information.

10.4.3 Objective 3: Write System Documentation

• System manpages are an excellent place to create local documentation.

• Raw man files are usually processed using nroff for display purposes. You can use this format or simply create a text file and store it in the appropriate cat directory.

• Local manpages will probably go in /usr/local/man.