next up previous contents
Next: groff 處理手冊 Up: 使用者手冊 Previous: 使用者手冊   Contents

撰寫手冊

  1. Makefile 假造目標項目 all 為 makefile 的第一個目標項目,all 列出所有要產生的檔案為相依性項目。如果不指定 all 目標項目,make 就會產生 makefile 中的第一個目標項目。
  2. 在 makefile2 增加假造目標項目 all,建立多個目標檔案。例如:產生二進位執行檔 main 和使用手冊文件 main.1。
    [dywang@dyw219 make1]$ vim makefile2 
    [dywang@dyw219 make1]$ grep ^all makefile2
    all: main main.1
    
  3. 大部分使用手冊的設計都有如下樣式:
    1. Header
    2. Name
    3. Synopsis
    4. Description
    5. Options
    6. Files
    7. See also
    8. Bugs
  4. 編輯簡單 main 應用程式使用手冊之原始碼 main.1。
    [dywang@dyw219 make1]$ vim main.1
    [dywang@dyw219 make1]$ cat main.1
    .TH MAIN 1
    .SH NAME
    Main \- A simple demonstration application that does very little.
    .SH SYNOPSIS
    .B main
    [\-option ...]
    .SH DESCRIPTION
    .PP
    \fImain\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
    main 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
    main is Copyright (c) 2019 .....
    .SH BUGS
    There probably are some, but we don't know what they are yet.
    .SH AUTHORS
    ABC123
    
  5. man 手冊格式巨集都以(.)開頭,而且都很簡短。執行 man 7 man 可查詢格式。
    [root@dyw219 ~]# 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@dyw219 ~]# 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 ...
    
    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)
    



De-Yu Wang 2019-08-23