next up previous contents
Next: 實機練習題 Up: 開發工具 - make 與 Previous: 函式庫管理   Contents

撰寫使用者手冊

  • 大部分使用手冊的設計都有如下樣式：
    1. Header
    2. Name
    3. Synopsis
    4. Description
    5. Options
    6. Files
    7. See also
    8. Bugs
  • 簡單的範本：應用程式使用手冊之原始碼 myapp.1。 
    .TH MYAPP 1
.SH NAME
Myapp \- A simple demonstration application that does very little.
.SH SYNOPSIS
.B myapp
[\-option ...]
.SH DESCRIPTION
.PP
\fImyapp\fP is a complete application that does nothing useful.
.PP
It was written for demonstration purposes.
.SH OPTIONS
.PP
It doesn't have any, but let's pretend, to make this template
complete:
.TP
.BI \-option
If there was an option, it would not be -option.
.SH RESOURCES
.PP
myapp uses almost no resources.
.SH DIAGNOSTICS
The program shouldn't output anything, so if you find it doing so
there's probably something wrong. The return value is zero.
.SH SEE ALSO
The only other program we know with this this little functionality is
the ubiquitous hello world application.
.SH COPYRIGHT
myapp is Copyright (c) 2003 Wrox Press.
This program is free software; you can redistribute it and/or modify
it 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.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA.
.SH BUGS
There probably are some, but we don't know what they are yet.
.SH AUTHORS
Neil Matthew and Rick Stones
    1. 巨集都以(.)開頭，而且都很簡短。
    2. 上例第一行的 1 表示使用手冊歸屬於第一類(使用者可以操作的指令或可執行檔)。
    3. 巨集格式可以 man 7 man 查詢
      [root@dywOffice ~]# man -f man
man                  (1)  - format and display the on-line manual pages
man.config [man]     (5)  - configuration data for man
man                  (7)  - macros to format man pages
[root@dywOffice ~]# man 7 man | cat -

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

NAME
       man - macros to format man pages

SYNOPSIS
       groff -Tascii -man file ...
       groff -Tps -man file ...
       man [section] title

DESCRIPTION

PREAMBLE
       The first command in a man page should be
              .TH title section date source manual,

SECTIONS
       Sections are started with .SH followed by the  heading  name.
              .SH NAME
              chess \- the game of chess
FONTS
       The commands to select the type face are:
       .B  Bold
       .BI Bold alternating with italics 
       .BR Bold  alternating  with  Roman
       .I  Italics
       .IB Italics alternating with bold
       .IR Italics alternating with Roman
       .RB Roman alternating with bold
       .RI Roman alternating with italics
       .SB Small alternating with bold
       .SM Small (useful for acronyms)

OTHER MACROS AND STRINGS
    Normal Paragraphs
       .LP      Same as .PP (begin a new paragraph).
       .P       Same as .PP (begin a new paragraph).
       .PP      Begin a new paragraph and reset prevailing indent.
   Relative Margin Indent
       .RS i    Start relative margin indent: 
                moves the left margin i to the right.
       .RE      End relative margin indent and restores 
                the previous value  of the prevailing indent.
   Indented Paragraph Macros
       .HP i    Begin  paragraph  with a hanging indent.
       .IP x i  Indented paragraph with optional hanging tag x.
       .TP i    Begin  paragraph  with  hanging  tag.
   Hypertext Link Macros
   Miscellaneous Macros
       .DT      Reset tabs to default tab values (every 0.5 inches)..
       .PD d    Set  inter-paragraph vertical distance to d (if omitted,
                d=0.4v).
       .SS t    Subheading t (like .SH, but used for a subsection).
   Predefined Strings

SAFE SUBSET
       Font changes (ft and the \f escape sequence) should only have the 
       values 1, 2, 3, 4, R, I, B, P, or CW.
NOTES

FILES
       /usr/share/groff/[*/]tmac/tmac.an
       /usr/man/whatis
BUGS

AUTHORS

SEE ALSO
       apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7),
       groff_man(7), groff_www(7), whatis(1)

Linux                             2004-07-27                     MAN(7)

  • UNIX 使用手冊是藉由 nroff 工具，格式處理後所形成，在 Linux 系統上也有個類似的 GNU 專案 groff。
  • 利用指令 groff 處理使用手冊的原始碼。
    1. 指令 groff 
      $ groff [-Tm] file
-Tascii：產生 ASCII 文字。
-Tps：產生 PostScript。
-man：告訴 groff 輸入一個使用手冊。
    2. 將使用手冊 myapp.1 以 ASCII 文字產生： 
      [dywang@dywHome2 chapter09]$ groff -Tascii -man myapp.1
MYAPP(1)                                                              MYAPP(1)



NAME
       Myapp - A simple demonstration application that does very little.


SYNOPSIS
       myapp [-option ...]


DESCRIPTION
       myapp is a complete application that does nothing useful.


       It was written for demonstration purposes.


OPTIONS
       It doesn't have any, but lets pretend, to make this template complete:


       -option
              If there was an option, it would not be -option.


RESOURCES
       myapp uses almost no resources.


DIAGNOSTICS
       The  program  shouldn't  output  anything,  so  if you find it doing so
       there's probably something wrong. The return value is zero.


SEE ALSO
       The only other program we know with this this little  functionality  is
       the ubiquitous hello world application.


COPYRIGHT
       myapp is Copyright (c) 2003 Wrox Press.

       This program is free software; you can redistribute it and/or modify it
       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.

       This program is distributed in the hope that it  will  be  useful,  but
       WITHOUT  ANY  WARRANTY;  without  even  the  implied  warranty  of MER-
       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  General
       Public License for more details.

       You should have received a copy of the GNU General Public License along
       with this program; if not, write to the Free Software Foundation, Inc.,
       675 Mass Ave, Cambridge, MA 02139, USA.


BUGS
       There probably are some, but we don't know what they are yet.


AUTHORS
       Neil Matthew and Rick Stones


ACKNOWLEDGEMENT
       Thanks to Wrox press for publishing this book.



                                                                      MYAPP(1)

  • 使用 man 命令查詢使用手冊
    1. 先以指令 bzip2 將使用手冊 myapp.1 壓縮； 
      [dywang@dywHome2 chapter09]$ bzip2 -z myapp.1
[dywang@dywHome2 chapter09]$ ls myapp.*
myapp.1.bz2  myapp.spec
    2. 將壓縮之使用手冊 myapp.1.bz2 放到 /usr/share/man/man1 目錄下。 
      [dywang@dywHome2 chapter09] cp myapp.1.bz2 /usr/share/man/man1/
練習題
  1. UNIX 使用手冊處理工具為何？
    Sol. nroff
  2. Linux 使用手冊處理工具為何？
    Sol. groff
  3. 請說明 .TH MYAPP 1 在 Linux 應用程式使用手冊之原始碼中之意義及結果。
    Sol. 指令名稱顯示在 man page 的開頭第一行；1 代表使用手冊歸屬於第一類；顯示結果 MYAPP(1)
  4. 請說明 .SH NAME 在 Linux 應用程式使用手冊之原始碼中之意義及結果。
    Sol. 段落的抬頭為 NAME；顯示結果 NAME
  5. 請說明 .B myapp [\-option ...] 在 Linux 應用程式使用手冊之原始碼中之意義及結果。
    Sol. 字型 myapp [-option ...] 為粗體字；\-為跳脫特殊字元 -
  6. 請說明 .PP \fImyapp\fP 在 Linux 應用程式使用手冊之原始碼中之意義及結果。
    Sol. 開始新的一行且內縮；顯示 myapp；\f 為字型改變指令；字型改變為有下線 I，後再改變回無下線之正常字體 P
  7. 請說明 .TP .BI \-option 在 Linux 應用程式使用手冊之原始碼中之意義及結果。
    Sol. 開始新的一行且外凸為標籤；顯示 -option 字型為粗斜體
  8. 如何以指令 groff，將使用手冊 myapp.1 以 ASCII 文字產生？
    Sol. groff -Tascii -man myapp.1
  9. 要讓系統可以使用 man 命令查詢使用手冊 myapp.1，必須做那兩個動作？
    Sol. 1.壓縮 bzip2 -z myapp.1 2.複製 cp myapp.1.bz2 /usr/share/man/man1/

next up previous contents
Next: 實機練習題 Up: 開發工具 - make 與 Previous: 函式庫管理   Contents
2017-06-14