MDOC.SAMPLES(7) Miscellaneous Information Manual MDOC.SAMPLES(7) 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 .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 .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 ) , ), .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 , ( ) (). , . [] [] 2003/05/13 Linuxman http://cmpp.linuxforum.net man man https://github.com/man-pages-zh/manpages-zh Linux 6.7.4-arch1-1 December 30, 1993 Linux 6.7.4-arch1-1