1. Context 7 License Of This Document 1.108.1 2 8 1.108.1 Use and manage local system documentation Weight 4 Linux Professional Institute Certification — 102 1 Context Topic 108 Documentation [8] 1.108.1 Use and manage local system documentation [4] 1.108.2 Find Linux documentation on the Internet [3] 1.108.5 Notify users on system-related issues [1] Geoffrey Robertson ge@ffrey.com Nick Urbanik nicku@nicku.org This document Licensed under GPL—see section 7 2 Objective 2005 July Outline Use and Manage Local System Documentation Candidates should be able to use and administer the man facility and the material in /usr/share/doc/. This objective includes finding relevant man pages, searching man page sections, finding commands and man pages related to them, and configuring access to man sources and the man system. It also includes using system documentation stored in /usr/share/doc/ and determining what documentation to keep in /usr/share/doc/. Use and Manage Local System Documentation Contents 1 2 3 Context Objective whatis and apropos 3.1 whatis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 apropos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Building whatis/appropos database . . . . . . . . . . . . . . . . . . . man 4.1 man options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 man — configuring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 man section numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GNU info 5.1 Navigation in info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /usr/share/doc 2 MANPATH — an environment variable that specifies a search path for man pages 2 man — the program that accesses man pages 2 2 3 3 4 4 4 5 6 6 7 apropos — searches descriptions of man pages, returning all matches; same as man -k whatis — returns descriptions of matching man page; same as man -f 4 3 whatis and apropos 3.1 whatis Using whatis 5 • whatis searches the manual page names and displays the manual page descriptions of any name matched. 6 3.2 apropos 1.108.1 3 4. man 1.108.1 4 • $ whatis nmap ← nmap (1) - Network exploration tool and security scanner • (in Debian and Ubuntu but not Red Hat/Fedora) Interpret each name as a regular expression. $ whatis -r ^ifc ← ifconfig (8) - configure a network interface • Is equivalent to $ man -f ← • This may have been asked in previous exams • Nick’s silly mnemonic: What the -f... is. . . -r, --regex 4 man Using man $ man man ← man(1) NAME man - format and display the on-line manual pages manpath - determine user’s search path for man pages SYNOPSIS man [-acdfFhkKtwW] [--path] [-m system] [-p string] [-C config_file] [-M pathlist] [-P pager] [-S section_list] [section] name ... DESCRIPTION man formats and displays the on-line manual pages. m 3.2 apropos Using apropos Each manual page has a short description available within it. apropos searches the descriptions for instances of keyword. $ apropos nmap ← mmap (2) munmap (2) nmap (1) Tk_MapWindow (3tk) ... map or unmap files or devices into memory map or unmap files or devices into memory Network exploration tool and security scanner map or unmap a window 4.1 man options Using man -k Equivalent to apropos -f Equivalent to whatis -K Search for the specified string in all man pages. Warning: this is probably very slow! It helps to specify a section. (Just to give a rough idea, on my machine this takes about a minute per 500 man pages.) -a Show all matching man pages from all sections; for example, man -a passwd shows the man pages both for passwd(1) and passwd(5). • Is equivalent to $ man -k ← • This may have been asked in previous exams • Nick’s silly mnemonic: apropos -kan produce many lines of output 4.2 man — configuring Configuring how man finds manpages • The configuration file for man is: – Red Hat/Fedora sytems: /etc/man.config – Ubuntu: /etc/manpath.config • can override the search paths specified in the configuration files using the MANPATH environment variable 3.3 Building whatis/appropos database Database for whatis and appropos • Both textttwhatis and appropos use a common simple text file database • Built by a nightly cron job script in /etc/cron.daily • Red Hat/Fedora runs a shell script /usr/sbin/makewhatis • Ubuntu runs a program /usr/bin/mandb 4.3 man section numbers 1.108.1 5 5. GNU info ?string Search for string backwards N repeat previous search backwards 1.108.1 6 – MANPATH is a colon-separated list of directories to search • You can see the existing search path with $ man --path ← or: $ manpath ← /usr/local/man:/usr/local/share/man:/usr/share/man:/usr/X11R6/man ESC-u Undo (toggle) search highlighting. 4.3 man section numbers The Manual Section Numbers 1. Executable programs or shell commands 2. System calls (functions provided by the kernel) 3. Library calls (functions within system libraries) 4. Special files (usually found in /dev) 5. File formats and conventions eg /etc/passwd 6. Games 7. Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7) 8. System administration commands (usually only for root) 9. Kernel routines [Non standard] Navigating in man (really less) The man program actually calls many other programs, displaying the result, by default, with the less program: $ man -d man 2>&1 | tail -n 1 ← (cd /usr/share/man/en && (echo ".pl 11i"; /usr/bin/gunzip -c ’/usr/share/man/en/man1/man.1.gz’) | /usr/bin/gtbl | /usr/bin/nroff -c -legacy ISO-8859-1 -mandoc 2>/dev/null | /usr/bin/less -is) h Show detailed help on using the less program q Quit g Go to beginning of man page G Go to end of man page /string Search for string. n repeat previous search forwards 5 GNU info Node: Top, Next: Getting Started, Up: (dir) GNU info File: info.info, Info: An Introduction ********************* The GNU Project distributes most of its on-line manuals in the "Info format", which you read using an "Info reader". You are probably using an Info reader to read this now. There are two primary Info readers: ‘info’, a stand-alone program designed just to read Info files, and the ‘info’ package in GNU Emacs, a general-purpose editor. At present, only the Emacs reader supports using a mouse. If you are new to the Info reader and want to learn how to use it, type the command ‘h’ now. It brings you to a programmed instruction sequence. To read about expert-level Info commands, type ‘n’ twice. This brings you to ‘Info for Experts’, skipping over the ‘Getting Started’ chapter. * Menu: Getting started using an Info reader. * Getting Started:: Info commands for experts. * Expert Info:: * Creating an Info File:: How to make your own Info file. An index of topics, commands, and variables. * Index:: -zz-Info: (info.info.gz)Top, 29 lines -Top---------------------------Welcome to Info version 4.8. Type ? for help, m for menu item. 5.1 Navigation in info GNU info Navigation Tab Move among hyperlinks Enter Follow hyperlinks d Return to the top 6. /usr/share/doc ? List these info commands n Move to the "next" node of this node. 1.108.1 7 7. License Of This Document 1.108.1 8 See the file doc/INSTALL for build, installation and postinstall configuration steps. Refer to the acl(5) manual page for general access control list information and references to other related manual pages. The extended attributes and access control list project for the ext2 and ext3 filesystems is located at: http://acl.bestbits.at/ For more information and details on how to contribute to the XFS project see the web pages at: http://oss.sgi.com/projects/xfs/ /usr/share/doc/ $ firefox /usr/share/doc/xfig/html/index.html ← . . . or open this file URL: macutils-2.0b3 Maelstrom-3.0.6 MagicPoint-1.11b mailman-2.1.5 make-3.80 MAKEDEV-3.19 man-pages-1.67 man-pages-cs-0.16 man-pages-da-0.1.1 man-pages-de-0.4 man-pages-es-1.28 man-pages-fr-0.9.7 file:///usr/share/doc/xfig/html/index.html p Move to the "previous" node of this node. u Move "up" from this node. q Quit Info altogether. h Show a primer for first time users. /string Search for string. 6 /usr/share/doc /usr/share/doc/ General information about packages and programs. $ ls /usr/share/doc/ ← a2ps-4.13b a52dec-0.7.4 aalib-1.4.0 abiword-2.4.1 abook-0.5.4 ac-archive-0.5.39 acl-2.2.23 adjtimex-1.20 aiksaurus-1.2.1 alchemist-1.0.36 alchemist-devel-1.0.36 alsa-lib-1.0.9rf /usr/share/doc/ $ ls /usr/share/doc/acl-2.2.23 ← CHANGES.gz LICENSE PORTING README /usr/share/doc/ $ head /usr/share/doc/acl-2.2.23/README ← Access control list package README __________________________________ 7 License Of This Document License Of This Document Copyright c 2005, 2003 Geoffrey Robertson and Nick Urbanik . Permission is granted to make and distribute verbatim copies or modified versions of this document provided that this copyright notice and this permission notice are preserved on all copies under the terms of the GNU General Public License as published by the Free Software Foundation—either version 2 of the License or (at your option) any later version.