On Wed, 7 Sep 2022 00:13:18 +0200 Alejandro Colomar <alx.manpages@xxxxxxxxx> wrote to <groff@xxxxxxx>: > If someone wants to send it as a patch, I'm open to discussing it. > I remember having some concerns when I read the page, but I don't > remember now about them. I'd be happy to discuss it with a patch > sent to linux-man@. As requested, attached page is quoted below in line. --jikl [snip] .Dd May 17, 2021 .Dt MAN-INTRO 1 .\"Os [OPERATING_SYSTEM] [version/release] .Sh NAME .Nm man-intro .Sh DESCRIPTION Most of the software installed on the system you are using is documented with .Em "man pages" and are displayed with the .Ic man command. The word .Dq man here refers to .Dq manual , as in a reference manual. This page introduces how the manual is organized, how it works, and offers some advice on how to use it. .Pp To view a man page, you type .Pp .D1 Ic man Fa name .Pp where .Fa name is the thing you want to know about. .Pp References to the manual and what it documents are often denoted with the name followed by a section number, e.g., .Pp .D1 Xr ls 1 .Pp refers to the .Em ls command, as documented in section 1. There are other sections for other kinds of things, described later. .Pp You may have noticed that the system also seems to have a .Dq help command. Likely that's because you're using the .Xr bash 1 shell to enter your commands. Bash includes what's known as .Dq built-in commands \(em commands supplied by bash itself \(em of which .Dq help is one. The bash help feature documents bash built-in commands. For instance, .Pp .D1 Ic help Li help .Pp describes the bash .Dq help command, and .Pp .D1 Ic help Li cd .Pp describes the bash .Dq cd command. .Pp A built-in commands in the shell sometimes may also exist as a utility. It may be instructive to compare the descriptions of .Xr time 1 in .Bd -literal -offset indent .Ic help Li time .Ic man Li time .Ed . .Sh "man Page Conventions" Most man pages follow a standard structure beginning with NAME, SYNOPSIS, and DESCRIPTION. The man page for a command defines the possible options, error messages, and exit status. For a function, it defines the arguments, along with the meaning of any return code and possible errors. Commands and functions may both be influenced by environment variables and/or configuration files. Near the end is a SEE ALSO section of related topics in the manual. .Pp A template in .Xr groff_mdoc 7 provides more detail. As you grow familiar with the manual, you'll find the conventional headings to be useful milestones. . .Sh The\ man\ Utility All man pages on your system offers are formatted uniformly. The .Xr man 1 utility sends the requested page through a system that formats it and presents it for viewing. That system consists of several interchangeable parts that vary across operating systems. The two most important parts are the .Em formatter , and the .Em pager , described next. If you invoke .Pp .D1 Ic man Li man .Pp you will see the man utility has many options, and also environment variables that control how .Xr man 1 behaves, and aspects of the formatter and pager. You won't often have reason to alter them, but you might, and, if you do, it's useful to know they're there. . .Sh Formatter The .Em formatter is the program that reads the man-page file and produces human-readable output, complete with paragraphs, boldface, italics, and underscores. The formatter is usually capable of producing a variety of output formats, depending on how the output will be viewed. In addition to viewing them in a terminal, for instance, the formatter may be able to produce PDF or HTML files. Some systems opt to include in the base system a limited version of the formatter that can be amplified from the packaging system. .Pp The most common formatter is GNU groff, an implementation of the AT&T .Xr troff 1 typesetting system. In addition to man pages, groff is used to produce a variety of other kinds of documents, from presentations to books. Another formatter sometimes used is .Xr mandoc 1 Ns , which is not a typesetting system but rather is specialized for man page formats. . .Sh Pager The output of the .Em formatter is normally sent to the .Em pager , so called because it .Dq pages the output in a terminal, allowing the user to scroll the text up and down, instead of having it all run off the top of the screen. The most commonly used pager is GNU .Xr less 1 Ns , a play on the name of an older utility, .Xr more 1 Ns , that let the user see .Dq more text (the next .Dq page ) by pressing the space bar. To get the most out of your manual, it's very helpful to get to know your pager. A quick sketch follows, but see .Xr less 1 for the whole enchilada. . .Sh "Introducing GNU less" GNU .Xr less 1 has a minimalist user interface, to reserve the most possible space for the text it's displaying. Many commands are a single keystroke. In case you get stuck, remember the 2 most important keys: .Pp .Bl -tag -offset indent -width nnnnn -compact .It h to access the help .It q to quit the help .It q to quit .Xr less 1 and exit back to the command prompt .El .Pp Forget trying ^C to quit; .Ql q is your friend. .Pp Use the arrow keys to move up and down through the .Dq page . The space bar will scroll a screenful of text at a time, and the enter key will move one line at a time. Some other up/down keys are: .Pp .Bl -tag -offset indent -width nnnnn -compact .It G go to end of document .It f down one screenful (toward the end) .It d down one \(12 screenful .It j down one line .It k up one line .It u up one \(12 screenful .It b up one screenful (toward the beginning) .It g go to beginning of document .El .Pp .Pp Once you can move up and down, the next most important feature of .Xr less 1 is the ability to search the text using regular expressions. To start a search, press the .Ql / key. In response, less puts a .Ql / in the lower left corner as a prompt. Type the string to search for. For example, the sequence: .Bd -literal -offset indent / ^FILE <enter> .Ed .Pp searches for the FILE section, where the word .Dq FILE appears at the beginning of a line. (The .Ql ^ character anchors the search at the left edge.) Similarly, to search for environment variables that affect execution, .Pp .Bd -literal -offset indent / ^ENV <enter> .Ed .Pp Of course, you can search for any string, not only headings. If the 1st occurrence isn't what you're looking for, you can repeat the search backwards or forwards from where you are with .Pp .Bl -tag -offset indent -width nnnnn -compact .It n to repeat the last search down, toward the end .It N to repeat the last search up, toward the beginning .El .Pp The less utility has dozens of options that can be set on the command line, and changed while it's running, from the keyboard. A helpful one to know about affects whether searches are case-sensitive. To toggle case-sensitivity, type .Ql - indicating an option change, followed by .Ql i , meaning .Em "ignore case" . .Pp The options that .Xr man 1 passes to .Xr less 1 when it starts is controlled by the configuration for .Xr man 1 . Specifically, the .Ev MANPAGER environment variable controls which pager to use, and with what options. . .Sh "Cross References" The weakest part of user interface to the manual is its lack of support for hyperlinks. There is no way to search documents by index term, or jump to a section from a table of contents, nor any way to jump back and forth between related documents. Most of the time if you're reading the page for .Ql X and want to jump to .Ql Y , the simplest way is just to type .Ql q to exit .Xr less 1 and type .Ic man Ar Y Ns . Occasionally, it can be handy to type .Ql \&! to start a subprocess, and type .Ic man Ar Y at the prompt. That way, when you press .Ql q to exit .Ar Y , you're returned to the parent process, namely .Xr less 1 , still reading .Ar X . . .Sh "Organization of the Manual" .Pp The whole manual covers much more than just command-line utilities. It is divided into numbered sections encompassing everything from programming interfaces to file formats: .Pp .Bl -enum -offset indent -compact .It General Commands .It System Calls .It Library Functions .It Kernel Interfaces .It File Formats .It Games .It Miscellaneous Information .It System Management Utilities .It Kernel Internal Functions .El .Pp If the man page you're reading doesn't seem related to what you're looking for, check the section number shown in the top left corner. If that's not the section you meant to search, you can be more specific by typing .Pp .D1 Ic man Ar section Ar name or .D1 Ic man Fl s Ar section Ar name .Pp For instance, there is a .Xr printf 1 and .Xr printf 3 . .Xr printf 1 is utility , and .Xr printf 3 is the famous C function. To distinguish, you can use .Pp .D1 Ic man Li 1 printf or .D1 Ic man Li 3 printf .Pp If you don't know what .Em name you need, you can search by keyword with the .Fl k option or .Xr apropos 1 , e.g., .Pp .D1 Ic man Fl s Li 1 Fl k Li html .Pp As a new user, you'll spend most of your time with section 1. If you're administering a system, you'll use section 8. If you're programming with C, you'll use sections 2 and 3. Most configuration files are documented in section 5. . .Sh "Read on, MacDuff" Exhaustive as it is \(em it's not uncommon for system to have 3000 man pages installed \(em the manual can sometimes be daunting. The reader is expected to bring the knowledge required to understand the subject. For example, consider this line from the first paragraph of the description of .Xr stat 1 , .Bd -ragged -offset indent If no argument is given, .Ic stat displays information about the file descriptor for standard input. .Ed .Pp To understand that sentence, the reader must know that .Dq argument is not .Dq quarrel , what a .Dq "file descriptor" is, and what .Dq "standard input" means. Without that knowledge, the sentence is incomprehensible. The manual doesn't explain those terms, though, because to do so would make it wordy and redundant. They are basic terminology used throughout the manual. Once mastered, any explanation of them would only get in the way of the particular information contained in the .Xr stat 1 page. .Pp Remember, the manual is a .Em reference manual, not a tutorial or a user guide. If you find yourself struggling to understand a man page, you might want to seek out instructional material. Then, with some grasp of the .Dq "lay of the land" , you can return to the manual better equipped to understand it. . .Sh BUGS The manual is meant to document, completely and correctly, what the user must do to make the thing do what is says it does. There is a name for any discrepancy between what the manual says and what the thing actually does: a bug. It may be an error in the documentation or in the program, but it's definitely an error. If you think you've found one, most free software projects welcome accurate problem reports in the form, .Dq "the manual says X but the software does Y" . . .Sh "SEE ALSO" .Bd -unfilled .Xr less 1 .Xr man 1 .Xr groff 1 .Ed \" LocalWords: Dd groff mandoc Ns enchilada nnnnn screenful ENV Ar \" LocalWords: MANPAGER enum Ic Fl printf Li html MacDuff stat [pins]
Attachment:
man-intro.1
Description: Binary data
