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

[email protected]:/tmp/thesre$ sudo apt install txt2man
           

然後将

txt2man -h

輸出的幫助資訊，制作成一個man檔案（請注意，它有一定的格式），

[email protected]:/tmp/thesre$ txt2man -h 2>&1 | txt2man > txt2man.1
[email protected]:/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指令檢視（太棒了，成功！），

[email protected]:/tmp/thesre$ gzip txt2man.1
[email protected]:/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指令檢視該手冊了。

[email protected]:/tmp/thesre$ mkdir man/man1 -p
[email protected]:/tmp/thesre$ mv ./txt2man.1.gz man/man1
[email protected]:/tmp/thesre$ export MANPATH=/tmp/thesre/man
[email protected]:/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