Linux - 手册基础知识介绍，并动手制作手册

Linux - 手册基础知识介绍，并动手制作手册

场景

Linux用户在工作时，经常需要使用各种各样的命令，而命令有各种option与argument。如果我们对一个命令不熟悉，我们可以查找其手册来了解命令的用法。我们来查看下手册如何使用，执行man man,

MAN(1)                                                        Manual pager utils                                                        MAN(1)

NAME
       man - an interface to the system reference manuals

SYNOPSIS
       man [man options] [[section] page ...] ...
       man -k [apropos options] regexp ...
       man -K [man options] [section] term ...
       man -f [whatis options] page ...
       man -l [man options] file ...
       man -w|-W [man options] page ...

DESCRIPTION
       man  is the system's manual pager.  Each page argument given to man is normally the name of a program, utility or function.  The manual
       page associated with each of these arguments is then found and displayed.  A section, if provided, will direct man to look only in that
       section  of the manual.  The default action is to search in all of the available sections following a pre-defined order (see DEFAULTS),
       and to show only the first page found, even if page exists in several sections.

       The table below shows the section numbers of the manual followed by the types of pages they contain.

       1   Executable programs or shell commands
       2   System calls (functions provided by the kernel)
       3   Library calls (functions within program libraries)
       4   Special files (usually found in /dev)
       5   File formats and conventions, e.g. /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]

       A manual page consists of several sections.

       Conventional section names include NAME, SYNOPSIS, CONFIGURATION, DESCRIPTION, OPTIONS, EXIT STATUS, RETURN VALUE, ERRORS, ENVIRONMENT,
       FILES, VERSIONS, CONFORMING TO, NOTES, BUGS, EXAMPLE, AUTHORS, and SEE ALSO.

       The following conventions apply to the SYNOPSIS section and can be used as a guide in other sections.
... snippet ommitted ...

可以看到，手册分为8部分

• 1 用户命令或程序
• 2 系统调用
• 3 库调用
• 4 特殊文件
• 5 文件格式与配置文件
• 6 游戏
• 7 概览，传统与杂项
• 8 系统管理命令

比如我们想查看用户命令 rsync如何使用，执行man rsync或man 1 rsync，

rsync(1)                                                                                                                              rsync(1)

NAME
       rsync - a fast, versatile, remote (and local) file-copying tool

SYNOPSIS
       Local:  rsync [OPTION...] SRC... [DEST]

       Access via remote shell:
         Pull: rsync [OPTION...] [USER@]HOST:SRC... [DEST]
         Push: rsync [OPTION...] SRC... [USER@]HOST:DEST

       Access via rsync daemon:
         Pull: rsync [OPTION...] [USER@]HOST::SRC... [DEST]
               rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
         Push: rsync [OPTION...] SRC... [USER@]HOST::DEST
               rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST

       Usages with just one SRC arg and no DEST arg will list the source files instead of copying.

DESCRIPTION
... snippet ommitted ...

我们可以看到，第一行的rsync(1)带了一个(1)，这个说的是该手册是用户命令或程序（rsync）的手册。

查看read系统调用，我们可以执行man 2 read，

READ(2)                                                    Linux Programmer's Manual                                                   READ(2)

NAME
       read - read from a file descriptor

SYNOPSIS
       #include <unistd.h>

       ssize_t read(int fd, void *buf, size_t count);

DESCRIPTION
... snippet ommitted ...

通过查看手册，我们能找到命令的使用方法。

彩蛋：动手制作手册文件

我们在编写内部Linux工具后，如何更高效地给用户普及使用方法？其中一个方法就是同时编写一个手册，供用户执行man <命令>查询使用方法。

那，如何编写手册供用户使用呢？执行man man-pages查看编写方法，

MAN-PAGES(7)                                               Linux Programmer's Manual                                              MAN-PAGES(7)

NAME
       man-pages - conventions for writing Linux man pages

SYNOPSIS
       man [section] title

DESCRIPTION
       This page describes the conventions that should be employed when writing man pages for the Linux man-pages project, which documents the
       user-space API provided by the Linux kernel and the GNU C library.  The project thus provides most of the pages in Section 2,  many  of
       the  pages  that appear in Sections 3, 4, and 7, and a few of the pages that appear in Sections 1, 5, and 8 of the man pages on a Linux
       system.  The conventions described on this page may also be useful for authors writing man pages for other projects.

   Sections of the manual pages
       The manual Sections are traditionally defined as follows:

       1 User commands (Programs)
                 Those commands that can be executed by the user from within a shell.

       2 System calls
                 Those functions which wrap operations performed by the kernel.

       3 Library calls
                 All library functions excluding the system call wrappers (Most of the libc functions).

       4 Special files (devices)
                 Files found in /dev which allow to access to devices through the kernel.

       5 File formats and configuration files
                 Describes various human-readable file formats and configuration files.

       6 Games   Games and funny little programs available on the system.

       7 Overview, conventions, and miscellaneous
                 Overviews or descriptions of various topics, conventions and protocols, character set standards, the standard filesystem layout, and miscellaneous other things.

       8 System management commands
                 Commands like mount(8), many of which only root can execute.
... snippet ommitted ...

根据上面的指导，我们尝试编写了一个手册文件。

这里我们借用一个工具，它可以使得编写好的文本内容，自动生成特定格式的手册文件，自动化制作流程。
先安装txt2man

thesre@HP-Z420-Workstation:/tmp/thesre$ sudo apt install txt2man

然后将txt2man -h输出的帮助信息，制作成一个man文件（请注意，它有一定的格式），

thesre@HP-Z420-Workstation:/tmp/thesre$ txt2man -h 2>&1 | txt2man > txt2man.1
thesre@HP-Z420-Workstation:/tmp/thesre$ head txt2man.1
.\" Text automatically generated by txt2man
.TH untitled  "30 June 2021" "" ""
.SH NAME
\fBtxt2man \fP- convert flat ASCII text to man page format
.SH SYNOPSIS
.nf
.fam C
\fBtxt2man\fP [\fB-hpTX\fP] [\fB-t\fP \fImytitle\fP] [\fB-P\fP \fIpname\fP] [\fB-r\fP \fIrel\fP] [\fB-s\fP \fIsect\fP]
        [\fB-v\fP \fIvol\fP] [\fB-I\fP \fItxt\fP] [\fB-B\fP \fItxt\fP] [\fB-d\fP \fIdate\fP] [\fIifile\fP]
.fam T

然后将其打包，并尝试使用man命令查看（太棒了，成功！），

thesre@HP-Z420-Workstation:/tmp/thesre$ gzip txt2man.1
thesre@HP-Z420-Workstation:/tmp/thesre$ man ./txt2man.1.gz

内容

untitled(30 June 2021)                                                                                                  untitled(30 June 2021)

NAME
       txt2man - convert flat ASCII text to man page format

SYNOPSIS
       txt2man [-hpTX] [-t mytitle] [-P pname] [-r rel] [-s sect]
               [-v vol] [-I txt] [-B txt] [-d date] [ifile]

DESCRIPTION
       txt2man  converts  the input text into nroff/troff standard man(7) macros used to format Unix manual pages. Nice pages can be generated
       specially for commands (section 1 or 8) or for C functions reference (sections 2, 3), with the ability to recognize and format  command
       and function names, flags, types and arguments.
... snippet ommitted ...

最后将该文件拷贝到手册文件夹中，并将该文件夹设置到MANPATH中，就可以通过man命令查看该手册了。

thesre@HP-Z420-Workstation:/tmp/thesre$ mkdir man/man1 -p
thesre@HP-Z420-Workstation:/tmp/thesre$ mv ./txt2man.1.gz man/man1
thesre@HP-Z420-Workstation:/tmp/thesre$ export MANPATH=/tmp/thesre/man
thesre@HP-Z420-Workstation:/tmp/thesre$ man txt2man

内容

untitled(30 June 2021)                                                                                                  untitled(30 June 2021)

NAME
       txt2man - convert flat ASCII text to man page format

SYNOPSIS
       txt2man [-hpTX] [-t mytitle] [-P pname] [-r rel] [-s sect]
               [-v vol] [-I txt] [-B txt] [-d date] [ifile]

DESCRIPTION
       txt2man  converts  the input text into nroff/troff standard man(7) macros used to format Unix manual pages. Nice pages can be generated
       specially for commands (section 1 or 8) or for C functions reference (sections 2, 3), with the ability to recognize and format  command
       and function names, flags, types and arguments.

       txt2man  is  also  able to recognize and format sections, paragraphs, lists (standard, numbered, description, nested), cross references
       and literal display blocks.
... snippet ommitted ...

总结

大家要注意的是，rsync -h与man rsync出来的帮助信息，来源是不同的。前者是命令自身提供的，后者是由系统管理员（在安装系统时或特意定制）放到MANPATH路径下的手册文件提供的。

参考资料

https://man7.org/linux/man-pages/man7/man-pages.7.html
https://man7.org/linux/man-pages/man1/man.1.html
https://www.linuxjournal.com/content/creating-custom-man-pages