Provided by:
manpages-zh_1.5.2-1_all 
NAME ()
mdoc.samples -- -mdoc BSD
SYNOPSIS ()
man mdoc.samples
DESCRIPTION ()
BSD (manual page), -mdoc , (domain-base) , troff(1) . -man(7) ,
(page layout), . -mdoc , (page structure domain) , , (displays)
. . , , . , . , , BSD . , , , , , , .
. .
UNIX , man page, , . (: , man page...)
GETTING STARTED
:
1. TROFF
.
.
.
.
2.
.
3. .
4. .
....
.
5.
.
.
.
().
.
.
Errno's ().
.
.
.
(Flags).
().
.
.
.
.
.
.
.
6.
AT&T .
BSD .
FreeBSD .
UNIX .
/ (Enclosure/Quoting)
/.
/.
/.
/.
/.
.
No-Op .
.
.
.
()
Trade Names ().
.
7.
.
.
(Keeps).
.
(, Symbolic).
.
8.
9.
10. GROFF, TROFF NROFF
11. BUGS
TROFF
-mdoc . , -mdoc troff(1) ; , , . , .
Macro Usage
troff(1) , '.' () , . , . troff(1) . '.' () , , '.'
() '\&' . '\&' , .
, troff(1) , . -mdoc , , . ( Extensions). ( ).
-mdoc , (). , , . , , '.' () . ; '.Op', ,
'Fl' 'Ar', :
[-s bytes] .Op Fl s Ar bytes
, '\&' :
[Fl s Ar bytes] .Op \&Fl s \&Ar bytes
'Fl' 'Ar' . mdoc(7) , , . '' , -mdoc , , ,
.
Passing Space Characters in an Argument
. , , . , '.Fn' , . ANSI C , . , int foo.
. : , AT&T troff , , , . groff , , :
Cd ( SYNOPSIS)
Bl ()
Em
Fn (, )
It
Li
Sy Symbolic text
%B
%J
%O
%R ()
%T
'\ ' , '\'. , , . Troff , . , :
fetch(char *str) '.Fn fetch char\ *str'
fetch(char *str) '.Fn fetch "char *str"'
'\' , '.Fn' , :
fetch(char, *str)
, BUGS .
Trailing Blank Space Characters
Troff , . , '\&' . , 'string\ \&'.
Escaping Special Characters
, '\n', '\e' '\' (e.g. '\en') .
THE ANATOMY OF A MAN PAGE
, /usr/share/misc/mdoc.template. /usr/share/examples/mdoc .
A manual page template
.\"
.Dd , Month day, year
.Os [/]
.Dt [][]
.Sh NAME
.Nm name
.Nd one line description of name
.Sh SYNOPSIS
.Sh DESCRIPTION
.\" .
.\" , .
.\" .Sh RETURN VALUES
.\" 1, 6, 7, 8.
.\" .Sh ENVIRONMENT
.\" .Sh FILES
.\" .Sh EXAMPLES
.\" 1, 6, 7, 8
.\" (shell)
.\" .Sh DIAGNOSTICS
.\" .
.\" .Sh ERRORS
.\" .Sh SEE ALSO
.\" .Sh CONFORMING TO
.\" .Sh HISTORY
.\" .Sh AUTHORS
.\" .Sh BUGS
(.Dd, .Os, .Dt) ; , , (()) (). . TITLE MACROS .
(section header) (.Sh); NAME, SYNOPSIS DESCRIPTION . ( )
. ; .
TITLE MACROS
, , , , . , , . , , .
.Dt # []
, troff , . () 1, ..., 8, , . :
AMD UNIX Ancestral Manual Documents
SMM UNIX System Manager's Manual
URM UNIX Reference Manual
PRM UNIX Programmer's Manual
URM 1, 6, and 7; SMM 8; PRM 2, 3, 4, and 5.
.Os # , BSD FreeBSD ATT. , 4.3, 4.3+Tahoe, V.3, V.4.
. , :
.Os BSD 4.3
.Os FreeBSD 2.2
.Os CS Department
, '.Os' BSD ( /usr/share/tmac/mdoc/doc-common ). . , '.Os' ,
.
.Dd , (month day, year)
:
January 25, 1989
What's in a name...
, , . , , . -mdoc . , -mdoc UNIX . , ; .
, troff(1) ; troff :
.Va argument1 argument2 ... argument9
'.Va' , . , UNIX ; SYNOPSIS :
filter [-flag] infile outfile
filter , -flag , . -mdoc , infile outfile . :
.Nm filter
.Op Fl flag
.Ar infile outfile
, , . , infile outfile operands file arguments. :
make [-eiknqrstv] [-D variable] [-d flags] [-f makefile]
[-I directory] [-j max_jobs] [variable=value] [target ...]
make makefile, , -f, target. , . -mdoc . 'Ar' , target
variable. make :
.Nm make
.Op Fl eiknqrstv
.Op Fl D Ar variable
.Op Fl d Ar flags
.Op Fl f Ar makefile
.Op Fl I Ar directory
.Op Fl j Ar max_jobs
.Op Ar variable=value
.Bk -words
.Op Ar target ...
.Ek
Keeps '.Bk' '.Ek' .
General Syntax
, : '.Ar', '.Fl', '.Nm', '.Pa' ; '.Fn' '.Xr' ; '.Op' '.Fn'
. , . :
.Li sptr, ptr),
:
sptr, ptr),
, . :
.Li sptr , ptr ) ,
:
sptr, ptr),
, .
'\&'. . Troff , , :
{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
troff . '\&' . , '.Ad'.
MANUAL DOMAIN
Address Macro
: addr1[,addr2[,addr3]].
Usage: .Ad address ...
.Ad addr1 addr1
.Ad addr1 . addr1.
.Ad addr1 , file2
addr1, file2
.Ad f1 , f2 , f3 :
f1, f2, f3:
.Ad addr ) ) ,
addr)),
'.Ad' . '.Ad' () .
Author Name
The '.An' , . .
Usage: .An author_name ...
.An Joe Author
Joe Author
.An Joe Author ,
Joe Author,
.An Joe Author Aq nobody@FreeBSD.ORG
Joe Author <nobody@FreeBSD.ORG>
.An Joe Author ) ) ,
Joe Author)),
'.An' () , '.An' .
Argument Macro
'.Ar' .
Usage: .Ar argument ...
.Ar file ...
.Ar file1 file1
.Ar file1 . file1.
.Ar file1 file2
file1 file2
.Ar f1 f2 f3 :
f1 f2 f3:
.Ar file ) ) ,
file)),
'.Ar' , 'file ...'. '.Ar' () .
() Configuration Declaration
'.Cd' config(8) (). ().
device le0 at scode? : '.Cd device le0 at scode?'.
Command Modifier
'.Fl' () , '.Cm' (dash). , . , . Flags.
Defined Variables
'.Dv' .
Usage: .Dv defined_variable ...
.Dv MAXHOSTNAMELEN
MAXHOSTNAMELEN
.Dv TIOCGPGRP )
TIOCGPGRP)
'.Dv' . '.Dv' () .
Errno's ()
'.Er' errno , .(: ) '.Er' '.Bq' , .
Usage: .Er ERRNOTYPE ...
.Er ENOENT
ENOENT
.Er ENOENT ) ;
ENOENT);
.Bq Er ENOTDIR
[ENOTDIR]
'.Er' . '.Er' () .
Environment Variables
'.Ev' .
Usage: .Ev argument ...
.Ev DISPLAY
DISPLAY
.Ev PATH . PATH.
.Ev PRINTER ) ) ,
PRINTER)),
'.Ev' . '.Ev' () .
Function Argument
'.Fa' SYNOPSIS , SYNOPSIS , '.Fn' , '.Fo' '.Fc' . '.Fa' .
Usage: .Fa function_argument ...
.Fa d_namlen ) ) ,
d_namlen)),
.Fa iov_len iov_len
'.Fa' . '.Fa' () .
Function Declaration
'.Fd' SYNOPSIS . '.Fd' , .
Usage: .Fd include_file (or defined variable)
SYNOPSIS , , , '.Fd' . , .
Flags
'.Fl' . '-', , , '.Cm' ( command modifier) , .
Usage: .Fl argument ...
.Fl -
.Fl cfv -cfv
.Fl cfv . -cfv.
.Fl s v t -s -v -t
.Fl - , --,
.Fl xyz ) , -xyz),
'.Fl' , , stdin/stdout. '.Fl' , . '.Fl' () .
() Functions (library routines)
.Fn ANSI C .
Usage: .Fn [type] function [[type] parameters ...
.Fn getchar getchar()
.Fn strlen ) , strlen()),
.Fn "int align" "const * char *sptrs", int align(const * char *sptrs),
'.Fn' . '.Fn' () , '.Fn' ().
(), '.Fo' (function open) '.Fc' (function close) '.Fa' (function
argument) , , :
.Fo "int res_mkquery"
.Fa "int op"
.Fa "char *dname"
.Fa "int class"
.Fa "int type"
.Fa "char *data"
.Fa "int datalen"
.Fa "struct rrec *newrr"
.Fa "char *buf"
.Fa "int buflen"
.Fc
:
int res_mkquery(int op, char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr, char *buf, int buflen)
'.Fo' '.Fc' () . SYNOPSIS , . SYNOPSIS , , .
. '.Fn' troff , . .
Function Type
SYNOPSIS . , SYNOPSIS , (kernel normal form) ( , ).
Usage: .Ft type ...
.Ft struct stat struct stat
'.Ft' .
Interactive Commands
'.Ic' .
Usage: .Ic argument ...
.Ic :wq :wq
.Ic do while {...} do while {...}
.Ic setenv , unsetenv
setenv, unsetenv
'.Ic' . '.Ic' () .
Name Macro
'.Nm' . , . , '.Nm' , . : , NAME '.Nm' ,
SYNOPSIS '.Fn' . , csh(1) 'while' , '.Ic' . '.Ic' '.Nm', , .
Usage: .Nm argument ...
.Nm mdoc.sample
mdoc.sample
.Nm \-mdoc -mdoc.
.Nm foo ) ) ,
foo)),
.Nm mdoc.samples
'.Nm' () .
Options
'.Op' , . '.Oc' '.Oo' .
Usage: .Op options ...
.Op []
.Op Fl k [-k]
.Op Fl k ) . [-k]).
.Op Fl k Ar kookfile [-k kookfile]
.Op Fl k Ar kookfile ,
[-k kookfile],
.Op Ar objfil Op Ar corfil
[objfil [corfil]]
.Op Fl c Ar objfil Op Ar corfil ,
[-c objfil [corfil]],
.Op word1 word2 [word1 word2]
'.Oc' '.Oo' :
.Oo
.Op Fl k Ar kilobytes
.Op Fl i Ar interval
.Op Fl c Ar count
.Oc
: [[-k kilobytes] [-i interval] [-c count]]
'.Op', '.Oc' '.Oo' () .
Pathnames
'.Pa' .
Usage: .Pa pathname
.Pa /usr/share /usr/share
.Pa /tmp/fooXXXXX ) .
/tmp/fooXXXXX).
'.Pa' () .
Variables
:
Usage: .Va variable ...
.Va count count
.Va settimer,
settimer,
.Va int *prt ) :
int *prt):
.Va char s ] ) ) ,
char s])),
'.Va' . '.Va' () .
Manual Page Cross References
'.Xr' , , , (). .
Usage: .Xr man_page [1,...,8]
.Xr mdoc mdoc
.Xr mdoc , mdoc,
.Xr mdoc 7 mdoc(7)
.Xr mdoc 7 ) ) ,
mdoc(7))),
'.Xr' () . '.Xr' .
GENERAL TEXT DOMAIN
AT&T
Usage: .At [v6 | v7 | 32v | V.1 | V.4] ...
.At AT&T UNIX
.At v6 . Version 6 AT&T UNIX.
'.At' () , () . .
BSD
Usage: .Bx [Version/release] ...
.Bx BSD
.Bx 4.3 .
4.3BSD.
'.Bx' () .
FreeBSD
Usage: .Fx Version.release ...
.Fx 2.2 . FreeBSD 2.2.
'.Fx' () , () . .
UNIX
Usage: .Ux ...
.Ux UNIX
'.Ux' () .
Enclosure and Quoting Macros
. , . '' '.' 'q' , (quoting), . (open)
(close) , 'o' 'c' . , .
Quote Close Open Function Result
.Aq .Ac .Ao Angle Bracket Enclosure <string>
.Bq .Bc .Bo Bracket Enclosure [string]
.Dq .Dc .Do Double Quote ``string''
.Ec .Eo Enclose String (in XX) XXstringXX
.Pq .Pc .Po Parenthesis Enclosure (string)
.Ql Quoted Literal `st' or string
.Qq .Qc .Qo Straight Double Quote "string"
.Sq .Sc .So Single Quote `string'
, () . , , . , . .
.Ec, .Eo .
.Ql troff nroff . nroff , . troff , . This is to make
short strings more visible where the font change to literal
(constant width) is less noticeable. () , .
.Pf () , .
.Pf ( Fa name2
(name2.
'.Ns' () .
:
.Aq <>
.Aq Ar ctype.h ) , <ctype.h>),
.Bq []
.Bq Em Greek , French .
[Greek, French].
.Dq ``''
.Dq string abc . ``string abc''.
.Dq '^[A-Z]' ``'^[A-Z]'''
.Ql man mdoc 'man mdoc'
.Qq ""
.Qq string ) , "string"),
.Qq string Ns ), "string),"
.Sq ''
.Sq string 'string'
, '.Op' . . '.Xo' '.Xc' , , , -mdoc .
No-Op or Normal Text Macro
'.No' , , , .
Space Macro
'.Ns' . , :
.Op Fl I Ns Ar directory
[-Idirectory]
: '.Ns' '.No' , . '.Ns' () .
Section Cross References
'.Sx' . () .
.Sx FILES FILES
References and Citations
The following macros make a modest attempt to handle references. At
best, the macros make it convenient to manually drop in a subset of refer
style references. . , .
.Rs . , , .
.Re . .
.%A , .
.%B .
.%C /.
.%D .
.%J .
.%N .
.%O .
.%P .
.%R .
.%T .
.%V .
'%' () , trade name macro , ( ). trade name troff/ditroff
.
Return Values
'.Rv' RETURN VALUES .
Usage: .Rv [-std function]
'.Rv -std atexit' :
.Rv -std atexit
-std .
Trade Names ()
trade name , .
Usage: .Tn symbol ...
.Tn DEC
DEC
.Tn ASCII
ASCII
'.Tn' () .
Extended Arguments
'.Xo' '.Xc' . , . '.Op'.
'.Xo' , :
.Sm off
.It Xo Sy I Ar operation
.No \en Ar count No \en
.Xc
.Sm on
Ioperation\ncount\n
:
.Sm off
.It Cm S No / Ar old_pattern Xo
.No / Ar new_pattern
.No / Op Cm g
.Xc
.Sm on
S/old_pattern/new_pattern/[g]
'.Xo' : .
.It Xo
.Ic .ifndef
.Oo \&! Oc Ns Ar variable
.Op Ar operator variable ...
.Xc
.ifndef [!]variable [operator variable ...]
'.It' (list-item) '.Xo' . , list-item . . ; , , .
, '.Xo' '.Xc' . '.Xo' '.It' , . , '.Ns' (no space macro)
. BSD 900 (1500) , '.Xo' .
PAGE STRUCTURE DOMAIN
Section Headers
'.Sh' . . '.Sh' . () , .
.Sh NAME
'.Sh NAME' . , , . NAME . '.Nm' , . '.Nd',
, , . , .
.Sh SYNOPSIS
SYNOPSIS . , '.Nm', '.Cd', '.Fn', ( '.Fo', '.Fc',
'.Fd', '.Ft' ). '.Fn' , '.Nm' 1, 5, 6, 7, 8 . '.Nm',
'.Fd' '.Cd' . , :
cat [-benstuv] [-] file ...
.Nm cat
.Op Fl benstuv
.Op Fl
.Ar
: '.Op', '.Fl', '.Ar' '|', :
.Op Fl a | Fl b
. Troff | . PREDEFINED STRINGS, | .
.Sh DESCRIPTION
DESCRIPTION , , . , '.Bl' , '.It' '.El' (
Lists and Columns ).
'.Sh' , , . .
.Sh ENVIRONMENT
ENVIRONMENT , , , .
.Sh EXAMPLES
, EXAMPLES .
.Sh FILES
, '.Pa' FILES .
.Sh SEE ALSO
, SEE ALSO . '.Xr' . SEE ALSO , , , :
ls(1), ps(1), group(5), passwd(5).
refer(1) .
.Sh CONFORMING TO
, , IEEE Std 1003.2 (``POSIX.2'') ANSI X3.159-1989
(``ANSI C89''), . , HISTORY .
.Sh HISTORY
.
.Sh AUTHORS
, .
.Sh DIAGNOSTICS
.
.Sh ERRORS
, (), . '.Er' errno.
.Sh BUGS ...
'.Sh' , , :
.Sh PAGE STRUCTURE DOMAIN
Paragraphs and Line Spacing.
.Pp '.Pp' , . '.Sh' '.Ss' , '.Bl' . ( '.Bl' ,
-compact ).
Keeps
. '.Bk' ( begin-keep) '.Ek' ( end-keep ) . '.Bk' -words, .
make ( What's in a name), keep nroff . ( , troff , ,
. , -line ) .
, '.D1', '.Dl', , , '.Bd' (begin-display) '.Ed' (end-display) .
.D1 (D-one) . () , .
-ldghfstru
: .Dl -ldghfstru.
.Dl (D-ell) literal. '.Dl' . () . (), . .
% ls -ldg /usr/local/bin
.Dl % ls -ldg /usr/local/bin.
.Bd . '.Bd' '.Ed' . . '.Bd' :
.Bd display-type [-offset offset_value] [-compact]
, . '.Bd'.
-ragged , () .
-filled () . ( , ).
-literal , , , table .
-file file_name -file . , table 8 , troff/-mdoc .
-offset string -offset , .
left , '.Bd' .
center . , .
indent table . '.D1' , . 6n,
2/3 ().
indent-two .
right . , troff .
.Ed End-display. .
Font Modes
:
.Em '.Em' . (italic).
Usage: .Em argument ...
.Em does not does not
.Em exceed 1024 .
exceed 1024.
.Em vide infra ) ) ,
vide infra)),
'.Em' () . '.Em' .
.Li '.Li' , , , .
Usage: .Li argument ...
.Li \en \n
.Li M1 M2 M3 ;
M1 M2 M3;
.Li cntrl-D ) ,
cntrl-D),
.Li 1024 ...
1024 ...
'.Li' () .
.Sy symbolic , , (bold) .
Usage: .Sy symbol ...
.Sy Important Notice
Important Notice
'.Sy' () . '.Sy' .
.Bf . '.Bf' '.Ef' . . '.Bf' :
.Bf font-mode
: '.Bf'.
Em | -emphasis '.Em' .
Li | -literal '.Li' .
Sy | -symbolic '.Sy' .
.Ef .
Tagged Lists and Columns
'.Bl' . '.It' , '.El' . . , .
, , , ( ) (tag style) (-tag). , (overhanging) (-ohang).
TeX , . '.Bl' :
-bullet
-item
-enum
. '.Bl' , '.It' . , "
.Bl -enum -compact
.It
Item one goes here.
.It
And item two here.
.It
Lastly item three goes here.
.El
:
1. Item one goes here.
2. And item two here.
3. Lastly item three goes here.
:
.Bl -bullet -compact
.It
Bullet one goes here.
.It
Bullet two here.
.El
:
+o Bullet one goes here.
+o Bullet two here.
-tag
-diag
-hang
-ohang
-inset
'.It' , , inset , (hanged) , (overhanged) , tagged.
'-ohang' . '.It' (inset), (hang), , .
:
Tag The tagged list (also called a tagged paragraph) is the most
common type of list used in the Berkeley manuals.
Diag Diag lists create section four diagnostic lists and are
similar to inset lists except callable macros are ignored.
Hang Hanged labels are a matter of taste.
Ohang Overhanging labels are nice when space is constrained.
Inset Inset labels are useful for controlling blocks of paragraphs
and are valuable for converting -mdoc manuals to other formats.
:
.Bl -inset -offset indent
.It Em Tag
The tagged list (also called a tagged paragraph) is the
most common type of list used in the Berkeley manuals.
.It Em Diag
Diag lists create section four diagnostic lists
and are similar to inset lists except callable
macros are ignored.
.It Em Hang
Hanged labels are a matter of taste.
.It Em Ohang
Overhanging labels are nice when space is constrained.
.It Em Inset
Inset labels are useful for controlling blocks of
paragraphs and are valuable for converting
.Nm -mdoc
manuals to other formats.
.El
:
Hanged labels appear similar to tagged lists when the label is
smaller than the label width.
Longer hanged list labels blend in to the paragraph unlike tagged
paragraph labels.
:
.Bl -hang -offset indent
.It Em Hanged
labels appear similar to tagged lists when the
label is smaller than the label width.
.It Em Longer hanged list labels
blend in to the paragraph unlike
tagged paragraph labels.
.El
.
SL sleep time of the process (seconds blocked)
PAGEIN number of disk I/O's resulting from references by the
process to pages not loaded in core.
UID numerical user-id of process owner
PPID numerical id of parent of process process priority (non-
positive when in non-interruptible wait)
:
.Bl -tag -width "PAGEIN" -compact -offset indent
.It SL
sleep time of the process (seconds blocked)
.It PAGEIN
number of disk
.Tn I/O Ns 's
resulting from references
by the process to pages not loaded in core.
.It UID
numerical user-id of process owner
.It PPID
numerical id of parent of process process priority
(non-positive when in non-interruptible wait)
.El
:
-width Fl (flag) . . '.Fl' , 5/6 .
-width 24n 24 , . , 'n'
-width ENAMETOOLONG
.
-width "int mkfifo"
, .
, '.It' , . '.It' , , . , , .
PREDEFINED STRINGS
, troff '\*(xx' , xx ; '\*x', x . .
String Nroff Troff
<= <= <=
>= >= >=
Rq '' ''
Lq `` ``
ua ^ ^
aa ' '
ga ` `
q " "
Pi pi pi
Ne != !=
Le <= <=
Ge >= >=
Lt < >
Gt > <
Pm +- +-
If infinity infinity
Na NaN NaN
Ba | |
: 'q' '\*q', .
DIAGNOSTICS
-mdoc , , . (?) troff , . -mdoc troff ditroff , -mdoc
, <> <> 'Ar', <> <> 'aR' <> <> 'C1'. , troff , , , (meta-
character) . '\&' . .
, . , , , , , . , : '.Db' (debug)
. '.Pp' , , , '.Db' .
Usage: .Db [on | off]
, debug ( 'aC' '\&aC' ):
.Db on
.Op Fl aC Ar file )
.Db off
:
DEBUGGING ON
DEBUG(argv) MACRO: `.Op' Line #: 2
Argc: 1 Argv: `Fl' Length: 2
Space: `' Class: Executable
Argc: 2 Argv: `aC' Length: 2
Space: `' Class: Executable
Argc: 3 Argv: `Ar' Length: 2
Space: `' Class: Executable
Argc: 4 Argv: `file' Length: 4
Space: ` ' Class: String
Argc: 5 Argv: `)' Length: 1
Space: ` ' Class: Closing Punctuation or suffix
MACRO REQUEST: .Op Fl aC Ar file )
DEBUGGING OFF
, '.Op' . ( ), . , . , ('Fl') . , (, ). ,
. , aC . , , , . . , 'aC' :
.Db on
.Em An escaped \&aC
.Db off
DEBUGGING ON
DEBUG(fargv) MACRO: `.Em' Line #: 2
Argc: 1 Argv: `An' Length: 2
Space: ` ' Class: String
Argc: 2 Argv: `escaped' Length: 7
Space: ` ' Class: String
Argc: 3 Argv: `aC' Length: 2
Space: ` ' Class: String
MACRO REQUEST: .Em An escaped &aC
DEBUGGING OFF
'\&aC' 2, '\&' , '\&aC' , .
, .
GROFF, TROFF AND NROFF
The -mdoc groff .
, , , nroff . , groff ( -Tascii ) . nroff'd (hardcopy).
'cR' /usr/src/share/tmac/doc-nroff () , .
FILES
/usr/share/tmac/tmac.doc
/usr/share/misc/mdoc.template
/usr/share/examples/mdoc/*
SEE ALSO
man(1), troff(1), mdoc(7)
BUGS
, DESCRIPTION ( ).
.
3f (header routine) .
'.Nm' NAME .
'.Fn' . , , .
nroff , ( ) ().
, .
[]
<xuming@users.sourceforge.net>
[]
2003/05/13
Linuxman
http://cmpp.linuxforum.net