--- title: 'Help Resources' source: 'https://academia.sh/en/courses/introduction-to-linux/help-resources' course: 'Introduction to Linux' language: en updated: '2026-08-17T18:09:56+00:00' license: 'CC BY-SA 4.0' --- # Help Resources Manual page section numbers, page structure, and synopsis notation; help for builtins and determining a command's type. The previous lesson used the `mkdir -p` option and explained what it does in the text. That is not a sustainable way to learn: dozens of options across hundreds of commands cannot be memorized. The system does not require it. Every command's documentation is installed along with the command itself, and the documentation follows a consistent structure. This lesson introduces that structure; for the rest of the course, some options will be left for the reader to look up rather than explained in the text. ## Manual Pages A **manual page** is the reference document for a command, file format, or system call. It is displayed with the `man` command: ``` $ man 1 ls | sed -n '1,13p' LS(1) User Commands LS(1) NAME ls - list directory contents SYNOPSIS ls [OPTION]... [FILE]... DESCRIPTION List information about the FILEs (the current directory by default). Sort entries alphabetically if none of -cftuvSUX nor --sort is speci- fied. ``` Only the page's first lines are taken in this example; typing `man ls` directly opens the page in a pager program, navigated with the arrow keys and exited with `q`. Searching inside the pager is done with `/`. Manual pages carry standard subheadings. The most commonly used, in order: - **NAME** — the command's name and a one-line description - **SYNOPSIS** — the usage summary - **DESCRIPTION** — detailed behavior and the option list - **EXIT STATUS** — which exit code is returned under which condition - **FILES** — the files the command reads or writes - **SEE ALSO** — related pages To quickly confirm a command's behavior, NAME and SYNOPSIS are read in that order; for detail, DESCRIPTION. When investigating the cause of an error, the EXIT STATUS and FILES sections often answer directly. ## Reading the Usage Synopsis The SYNOPSIS line uses a notation, and that notation is the same across every manual page: | Notation | Meaning | |---|---| | `plain text` | Written exactly as shown | | `[...]` | Contents in brackets are optional | | `...` | The preceding item can repeat | | `a\|b` | One of the alternatives | | `UPPERCASE` | A placeholder to be replaced with a value | Accordingly, the line `ls [OPTION]... [FILE]...` says: `ls` takes zero or more options and zero or more filenames; neither is required. `ls` can run with no arguments at all; this is consistent with the phrase "the current directory by default" in DESCRIPTION. For comparison, another command's synopsis: ``` $ mkdir --help | head -9 Usage: mkdir [OPTION]... DIRECTORY... Create the DIRECTORY(ies), if they do not already exist. Mandatory arguments to long options are mandatory for short options too. -m, --mode=MODE set file mode (as in chmod), not a=rwx - umask -p, --parents no error if existing, make parent directories as needed, with their file modes unaffected by any -m option. -v, --verbose print a message for each created directory -Z set SELinux security context of each created directory ``` `DIRECTORY...` is not in brackets: at least one directory name is required. The two separate functions of the `-p` option used in the previous lesson are both written here — creating missing parent directories and not erroring on an existing one. The `--help` option does not substitute for the manual page; on most commands it gives only the option list. On the other hand, it is always fast and is the only source on systems where manual pages are not installed. ## Section Numbers The manual is not a single set but is divided into numbered **sections**. The same name can appear in more than one section and describe different things. | Section | Contents | |---|---| | 1 | User commands | | 2 | System calls | | 3 | Library functions | | 4 | Special files and devices | | 5 | File formats and configuration files | | 6 | Games | | 7 | Miscellaneous: conventions, notations, concepts | | 8 | System administration commands | What the section division is for can be shown with a single name: ``` $ whatis passwd passwd (1) - change user password passwd (1ssl) - OpenSSL application commands passwd (5) - the password file ``` `passwd` is both a command and a file format. The entries in the list depend on the packages installed on the system; a page for software that is not installed does not appear. Suffixed section names like `1ssl` in the middle line come from a piece of software keeping its own pages in a separate subsection. `man passwd` shows only the first one found — section 1. To see the file format, the section is given explicitly: ``` $ man 5 passwd | sed -n '1,10p' PASSWD(5) File Formats and Configuration PASSWD(5) NAME passwd - the password file DESCRIPTION /etc/passwd contains one line for each user account, with seven fields delimited by colons (":"). These fields are: o login name ``` The `PASSWD(5)` notation in the page header repeats which section you are in, on every line. Documentation carries notations like `printf(3)` or `open(2)`; the number in parentheses is the section number, and it identifies which `printf` is meant — a shell command or a library function. This section's definition of the user account file will be used directly in the Users and Permissions topic. ## Searching When the Name Is Unknown The manual is useful once a command's name is known. If the name is not known, the descriptions are searched: ``` $ man -k 'list directory' | head -3 dir (1) - list directory contents ls (1) - list directory contents vdir (1) - list directory contents ``` `man -k` (equivalent to `apropos`) searches the NAME lines of every manual page. `man -f` (equivalent to `whatis`) searches for an exact name match. Both look at a prebuilt index; if the index hasn't been built, the result comes back empty. The search scans only the one-line descriptions, not entire pages. This is why the result set is narrow, and the search term should be kept general. ## Documentation for Builtins The previous lesson showed that builtins are not separate programs. This has a consequence for documentation: builtins have no separate manual page, because there is no separate program. Their documentation is in the shell's own page and in the shell's `help` builtin. ``` $ help type | sed -n '1,6p' type: type [-afptP] name [name ...] Display information about command type. For each NAME, indicate how it would be interpreted if used as a command name. ``` To choose the right source, the name's type is determined first: ``` $ type -t ls cd if file builtin keyword ``` The `-t` option prints only the type. The three answers correspond to three separate help sources: `man` for `file`, `help` for `builtin`, the shell's manual page for `keyword`. `if` is not a command but a **keyword** belonging to the shell's grammar; control structures are the subject of the Shell Programming course. ## The Limits of Documentation Manual pages are reference documents, not tutorials. They enumerate a command's every option completely but mostly do not say when to use which one. The documentation also belongs to the version on that system: if an option is not in the manual, it genuinely is not on that system — its existing on another system changes nothing. These two limits determine what the manual is used for. The manual answers "what does this command do"; it usually does not answer "which command do I use for this job." The second question is this course's subject. ## Summary - Manual pages carry standard subheadings such as NAME, SYNOPSIS, DESCRIPTION, EXIT STATUS, FILES, and SEE ALSO. - In a usage synopsis, brackets show optionality, ellipsis shows repeatability, and uppercase names show placeholders. - The manual is divided into numbered sections; the same name describes different things in different sections, and the `name(section)` notation states which one is meant. - `man -k` searches description lines; it is the way to find a command whose name is unknown. - Builtins have no separate manual page; they are documented with `help`, and the right source is determined with `type -t`. ## Next Step The `type` command performs a specific search to find what a name resolves to, and in the previous lesson, that same search failed when a command gave a "not found" error. The next lesson unpacks the rule behind that search: which directories the shell searches for an executable, in what order, how that order is changed, and why the current directory is not added to that list.