next up previous contents
Next: 實機練習題 Up: 開發工具 - makefile 其他功能 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: 開發工具 - makefile 其他功能 Previous: 函式庫管理   Contents
2017-06-14