=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.1 retrieving revision 1.45 diff -u -p -r1.1 -r1.45 --- mandoc/man.7 2009/03/23 16:02:56 1.1 +++ mandoc/man.7 2009/11/02 09:56:42 1.45 @@ -1,554 +1,985 @@ -.\" $Id: man.7,v 1.1 2009/03/23 16:02:56 kristaps Exp $ +.\" $Id: man.7,v 1.45 2009/11/02 09:56:42 kristaps Exp $ .\" -.\" Copyright (c) 2009 Kristaps Dzonsons +.\" Copyright (c) 2009 Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the -.\" above copyright notice and this permission notice appear in all -.\" copies. +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. .\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL -.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE -.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL -.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR -.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER -.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR -.\" PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: March 23 2009 $ -.Dt man 7 +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: November 2 2009 $ +.Dt MAN 7 .Os -.\" SECTION +. +. .Sh NAME .Nm man .Nd man language reference -.\" SECTION +. +. .Sh DESCRIPTION The .Nm man -language was historically used to format +language was historically used to format .Ux -manuals. In this reference document, we describe the syntax and -structure of the -.Nm -language. +manuals. This reference document describes its syntax, structure, and +usage. +. .Pp -.Em \&Do not -use +.Bf -emphasis +Do not use .Nm -to write your manuals. Use the +to write your manuals. +.Ef +Use the .Xr mdoc 7 language, instead. -.\" PARAGRAPH +. .Pp An .Nm document follows simple rules: lines beginning with the control -character -.Sq \. +character +.Sq \&. are parsed for macros. Other lines are interpreted within the scope of prior macros: -.Bd -literal -offset XXX +.Bd -literal -offset indent \&.SH Macro lines change control state. Other lines are interpreted within the current state. .Ed -.\" PARAGRAPH -.Pp -Macros are character sequences whose structural rules are described -later in this document. -.\" SECTION +. +. .Sh INPUT ENCODING .Nm -documents may contain only graphable 7-bit ASCII characters and the -space character -.Sq \ . -All manuals must have -.Sq \en -line termination. +documents may contain only graphable 7-bit ASCII characters, the +space character, and the tabs character. All manuals must have +.Ux +line termination. +. .Pp -Blank lines are acceptable; where found, the output will also assert a +Blank lines are acceptable; where found, the output will assert a vertical space. -.\" SUB-SECTION +. +.Pp +The +.Sq \ec +escape is common in historical +.Nm +documents; if encountered at the end of a word, it ensures that the +subsequent word isn't off-set by whitespace. +. +. +.Ss Comments +Text following a +.Sq \e\*" , +whether in a macro or free-form text line, is ignored to the end of +line. A macro line with only a control character and comment escape, +.Sq \&.\e" , +is also ignored. Macro lines with only a control character and +optionally whitespace are stripped from input. +. +. .Ss Special Characters -Special character sequences begin with the escape character -.Sq \\ -followed by either an open-parenthesis +Special characters may occur in both macro and free-form lines. +Sequences begin with the escape character +.Sq \e +followed by either an open-parenthesis .Sq \&( for two-character sequences; an open-bracket .Sq \&[ for n-character sequences (terminated at a close-bracket .Sq \&] ) ; -or a single one-character sequence. +or a single one-character sequence. See +.Xr mandoc_char 7 +for a complete list. Examples include +.Sq \e(em +.Pq em-dash +and +.Sq \ee +.Pq back-slash . +. +. +.Ss Text Decoration +Terms may be text-decorated using the +.Sq \ef +escape followed by an indicator: B (bold), I, (italic), or P and R +(Roman, or reset). +. +. +.Ss Whitespace +Unless specifically escaped, consecutive blocks of whitespace are pruned +from input. These are later re-added, if applicable, by a front-end +utility such as +.Xr mandoc 1 . +. +. +.Ss Dates +The +.Sx \&TH +macro is the only +.Nm +macro that requires a date. The form for this date is the ISO-8601 +standard +.Cm YYYY-MM-DD . +. +. +.Ss Scaling Widths +Many macros support scaled widths for their arguments, such as +stipulating a two-inch paragraph indentation with the following: +.Bd -literal -offset indent +\&.HP 2i +.Ed +. .Pp -Characters may alternatively be escaped by a slash-asterisk, -.Sq \\* , -with the same combinations as described above. This form is deprecated. +The syntax for scaled widths is +.Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? , +where a decimal must be preceded or proceeded by at least one digit. +Negative numbers, while accepted, are truncated to zero. The following +scaling units are accepted: +. .Pp -The following is a table of all available escapes. -.Pp -Grammatic: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(em -.Pq em-dash -.It \\(en -.Pq en-dash -.It \e- -.Pq hyphen -.It \\\\ -.Pq back-slash -.It \e' -.Pq apostrophe -.It \e` -.Pq back-tick -.It \\ -.Pq space -.It \\. -.Pq period -.It \\(r! -.Pq upside-down exclamation -.It \\(r? -.Pq upside-down question +.Bl -tag -width Ds -offset indent -compact +.It c +centimetre +.It i +inch +.It P +pica (~1/6 inch) +.It p +point (~1/72 inch) +.It f +synonym for +.Sq u +.It v +default vertical span +.It m +width of rendered +.Sq m +.Pq em +character +.It n +width of rendered +.Sq n +.Pq en +character +.It u +default horizontal span +.It M +mini-em (~1/100 em) .El -.\" PARAGRAPH .Pp -Enclosures: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(lh -.Pq left hand -.It \\(rh -.Pq right hand -.It \\(Fo -.Pq left guillemet -.It \\(Fc -.Pq right guillemet -.It \\(fo -.Pq left guilsing -.It \\(fc -.Pq right guilsing -.It \\(rC -.Pq right brace -.It \\(lC -.Pq left brace -.It \\(ra -.Pq right angle -.It \\(la -.Pq left angle -.It \\(rB -.Pq right bracket -.It \\(lB -.Pq left bracket -.It \\q -.Pq double-quote -.It \\(lq -.Pq left double-quote -.It \\(Lq -.Pq left double-quote, deprecated -.It \\(rq -.Pq right double-quote -.It \\(Rq -.Pq right double-quote, deprecated -.It \\(oq -.Pq left single-quote -.It \\(aq -.Pq right single-quote -.It \\(Bq -.Pq right low double-quote -.It \\(bq -.Pq right low single-quote -.El -.\" PARAGRAPH +Using anything other than +.Sq m , +.Sq n , +.Sq u , +or +.Sq v +is necessarily non-portable across output media. +. .Pp -Indicatives: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(<- -.Pq left arrow -.It \\(-> -.Pq right arrow -.It \\(ua -.Pq up arrow -.It \\(da -.Pq down arrow -.It \\(<> -.Pq left-right arrow -.It \\(lA -.Pq left double-arrow -.It \\(rA -.Pq right double-arrow -.It \\(uA -.Pq up double-arrow -.It \\(dA -.Pq down double-arrow -.It \\(hA -.Pq left-right double-arrow -.El -.\" PARAGRAPH +If a scaling unit is not provided, the numerical value is interpreted +under the default rules of +.Sq v +for vertical spaces and +.Sq u +for horizontal ones. +.Em Note : +this differs from +.Xr mdoc 7 , +which, if a unit is not provided, will instead interpret the string as +literal text. +. +. +.Sh MANUAL STRUCTURE +Each +.Nm +document must contain contains at least the +.Sx \&TH +macro describing the document's section and title. It may occur +anywhere in the document, although conventionally, it appears as the +first macro. +. .Pp -Mathematical: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(es -.Pq empty set -.It \\(ca -.Pq intersection -.It \\(cu -.Pq union -.It \\(gr -.Pq gradient -.It \\(pd -.Pq partial differential -.It \\(ap -.Pq similarity -.It \\(=) -.Pq proper superset -.It \\((= -.Pq proper subset -.It \\(eq -.Pq equals -.It \\(di -.Pq division -.It \\(mu -.Pq multiplication -.It \\(pl -.Pq addition -.It \\(nm -.Pq not element -.It \\(mo -.Pq element -.It \\(Im -.Pq imaginary -.It \\(Re -.Pq real -.It \\(Ah -.Pq aleph -.It \\(te -.Pq existential quantifier -.It \\(fa -.Pq universal quantifier -.It \\(AN -.Pq logical AND -.It \\(OR -.Pq logical OR -.It \\(no -.Pq logical NOT -.It \\(st -.Pq such that -.It \\(tf -.Pq therefore -.It \\(~~ -.Pq approximate -.It \\(~= -.Pq approximately equals -.It \\(=~ -.Pq congruent -.It \\(Gt -.Pq greater-than, deprecated -.It \\(Lt -.Pq less-than, deprecated -.It \\(<= -.Pq less-than-equal -.It \\(Le -.Pq less-than-equal, deprecated -.It \\(>= -.Pq greater-than-equal -.It \\(Ge -.Pq greater-than-equal -.It \\(== -.Pq equal -.It \\(!= -.Pq not equal -.It \\(Ne -.Pq not equal, deprecated -.It \\(if -.Pq infinity -.It \\(If -.Pq infinity, deprecated -.It \\(na -.Pq NaN , an extension -.It \\(Na -.Pq NaN, deprecated -.It \\(+- -.Pq plus-minus -.It \\(Pm -.Pq plus-minus, deprecated -.It \\(** -.Pq asterisk -.El -.\" PARAGRAPH +Beyond +.Sx \&TH , +at least one macro or text node must appear in the document. Documents +are generally structured as follows: +.Bd -literal -offset indent +\&.TH FOO 1 2009-10-10 +\&. +\&.SH NAME +\efBfoo\efR \e(en a description goes here +\&.\e\*q The next is for sections 2 & 3 only. +\&.\e\*q .SH LIBRARY +\&. +\&.SH SYNOPSIS +\efBfoo\efR [\efB\e-options\efR] arguments... +\&. +\&.SH DESCRIPTION +The \efBfoo\efR utility processes files... +\&. +\&.\e\*q .SH IMPLEMENTATION NOTES +\&.\e\*q The next is for sections 1 & 8 only. +\&.\e\*q .SH EXIT STATUS +\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.\e\*q .SH RETURN VALUES +\&.\e\*q The next is for sections 1, 6, 7, & 8 only. +\&.\e\*q .SH ENVIRONMENT +\&.\e\*q .SH FILES +\&.\e\*q .SH EXAMPLES +\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. +\&.\e\*q .SH DIAGNOSTICS +\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.\e\*q .SH ERRORS +\&.\e\*q .SH SEE ALSO +\&.\e\*q .BR foo ( 1 ) +\&.\e\*q .SH STANDARDS +\&.\e\*q .SH HISTORY +\&.\e\*q .SH AUTHORS +\&.\e\*q .SH CAVEATS +\&.\e\*q .SH BUGS +\&.\e\*q .SH SECURITY CONSIDERATIONS +.Ed .Pp -Ligatures: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(ss -.Pq German eszett -.It \\(AE -.Pq upper-case AE -.It \\(ae -.Pq lower-case AE -.It \\(OE -.Pq upper-case OE -.It \\(oe -.Pq lower-case OE -.It \\(ff -.Pq ff ligature -.It \\(fi -.Pq fi ligature -.It \\(fl -.Pq fl ligature -.It \\(Fi -.Pq ffi ligature -.It \\(Fl -.Pq ffl ligature +The sections in a +.Nm +document are conventionally ordered as they appear above. Sections +should be composed as follows: +.Bl -ohang -offset indent +.It Em NAME +The name(s) and a short description of the documented material. The +syntax for this is generally as follows: +.Pp +.D1 \efBname\efR \e(en description +.It Em LIBRARY +The name of the library containing the documented material, which is +assumed to be a function in a section 2 or 3 manual. For functions in +the C library, this may be as follows: +.Pp +.D1 Standard C Library (libc, -lc) +.It Em SYNOPSIS +Documents the utility invocation syntax, function call syntax, or device +configuration. +.Pp +For the first, utilities (sections 1, 6, and 8), this is +generally structured as follows: +.Pp +.D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR... +.Pp +For the second, function calls (sections 2, 3, 9): +.Pp +.D1 \&.B char *name(char *\efIarg\efR); +.Pp +And for the third, configurations (section 4): +.Pp +.D1 \&.B name* at cardbus ? function ? +.Pp +Manuals not in these sections generally don't need a +.Em SYNOPSIS . +.It Em DESCRIPTION +This expands upon the brief, one-line description in +.Em NAME . +It usually contains a break-down of the options (if documenting a +command). +.It Em IMPLEMENTATION NOTES +Implementation-specific notes should be kept here. This is useful when +implementing standard functions that may have side effects or notable +algorithmic implications. +.It Em EXIT STATUS +Command exit status for section 1, 6, and 8 manuals. This section is +the dual of +.Em RETURN VALUES , +which is used for functions. Historically, this information was +described in +.Em DIAGNOSTICS , +a practise that is now discouraged. +. +.It Em RETURN VALUES +This section is the dual of +.Em EXIT STATUS , +which is used for commands. It documents the return values of functions +in sections 2, 3, and 9. +. +.It Em ENVIRONMENT +Documents any usages of environment variables, e.g., +.Xr environ 7 . +. +.It Em FILES +Documents files used. It's helpful to document both the file and a +short description of how the file is used (created, modified, etc.). +. +.It Em EXAMPLES +Example usages. This often contains snippets of well-formed, +well-tested invocations. Make doubly sure that your examples work +properly! +. +.It Em DIAGNOSTICS +Documents error conditions. This is most useful in section 4 manuals. +Historically, this section was used in place of +.Em EXIT STATUS +for manuals in sections 1, 6, and 8; however, this practise is +discouraged. +. +.It Em ERRORS +Documents error handling in sections 2, 3, and 9. +. +.It Em SEE ALSO +References other manuals with related topics. This section should exist +for most manuals. +.Pp +.D1 \&.BR bar \&( 1 \&), +.Pp +Cross-references should conventionally be ordered +first by section, then alphabetically. +. +.It Em STANDARDS +References any standards implemented or used, such as +.Pp +.D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq) +.Pp +If not adhering to any standards, the +.Em HISTORY +section should be used. +. +.It Em HISTORY +The history of any manual without a +.Em STANDARDS +section should be described in this section. +. +.It Em AUTHORS +Credits to authors, if applicable, should appear in this section. +Authors should generally be noted by both name and an e-mail address. +. +.It Em CAVEATS +Explanations of common misuses and misunderstandings should be explained +in this section. +. +.It Em BUGS +Extant bugs should be described in this section. +. +.It Em SECURITY CONSIDERATIONS +Documents any security precautions that operators should consider. +. .El -.\" PARAGRAPH +. +. +.Sh MACRO SYNTAX +Macros are one to three three characters in length and begin with a +control character , +.Sq \&. , +at the beginning of the line. An arbitrary amount of whitespace may +sit between the control character and the macro name. Thus, the +following are equivalent: +.Bd -literal -offset indent +\&.PP +\&.\ \ \ PP +.Ed +. .Pp -Diacritics and letters: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(ga -.Pq grave accent -.It \\(aa -.Pq accute accent -.It \\(a" -.Pq umlaut accent -.It \\(ad -.Pq dieresis accent -.It \\(a~ -.Pq tilde accent -.It \\(a^ -.Pq circumflex accent -.It \\(ac -.Pq cedilla accent -.It \\(ad -.Pq dieresis accent -.It \\(ah -.Pq caron accent -.It \\(ao -.Pq ring accent -.It \\(ho -.Pq hook accent -.It \\(ab -.Pq breve accent -.It \\(a- -.Pq macron accent -.It \\(-D -.Pq upper-case eth -.It \\(Sd -.Pq lower-case eth -.It \\(TP -.Pq upper-case thorn -.It \\(Tp -.Pq lower-case thorn -.It \\('A -.Pq upper-case acute A -.It \\('E -.Pq upper-case acute E -.It \\('I -.Pq upper-case acute I -.It \\('O -.Pq upper-case acute O -.It \\('U -.Pq upper-case acute U -.It \\('a -.Pq lower-case acute a -.It \\('e -.Pq lower-case acute e -.It \\('i -.Pq lower-case acute i -.It \\('o -.Pq lower-case acute o -.It \\('u -.Pq lower-case acute u -.It \\(`A -.Pq upper-case grave A -.It \\(`E -.Pq upper-case grave E -.It \\(`I -.Pq upper-case grave I -.It \\(`O -.Pq upper-case grave O -.It \\(`U -.Pq upper-case grave U -.It \\(`a -.Pq lower-case grave a -.It \\(`e -.Pq lower-case grave e -.It \\(`i -.Pq lower-case grave i -.It \\(`o -.Pq lower-case grave o -.It \\(`u -.Pq lower-case grave u -.It \\(~A -.Pq upper-case tilde A -.It \\(~N -.Pq upper-case tilde N -.It \\(~O -.Pq upper-case tilde O -.It \\(~a -.Pq lower-case tilde a -.It \\(~n -.Pq lower-case tilde n -.It \\(~o -.Pq lower-case tilde o -.It \\(:A -.Pq upper-case dieresis A -.It \\(:E -.Pq upper-case dieresis E -.It \\(:I -.Pq upper-case dieresis I -.It \\(:O -.Pq upper-case dieresis O -.It \\(:U -.Pq upper-case dieresis U -.It \\(:a -.Pq lower-case dieresis a -.It \\(:e -.Pq lower-case dieresis e -.It \\(:i -.Pq lower-case dieresis i -.It \\(:o -.Pq lower-case dieresis o -.It \\(:u -.Pq lower-case dieresis u -.It \\(:y -.Pq lower-case dieresis y -.It \\(^A -.Pq upper-case circumflex A -.It \\(^E -.Pq upper-case circumflex E -.It \\(^I -.Pq upper-case circumflex I -.It \\(^O -.Pq upper-case circumflex O -.It \\(^U -.Pq upper-case circumflex U -.It \\(^a -.Pq lower-case circumflex a -.It \\(^e -.Pq lower-case circumflex e -.It \\(^i -.Pq lower-case circumflex i -.It \\(^o -.Pq lower-case circumflex o -.It \\(^u -.Pq lower-case circumflex u -.It \\(,C -.Pq upper-case cedilla C -.It \\(,c -.Pq lower-case cedilla c -.It \\(/L -.Pq upper-case stroke L -.It \\(/l -.Pq lower-case stroke l -.It \\(/O -.Pq upper-case stroke O -.It \\(/o -.Pq lower-case stroke o -.It \\(oA -.Pq upper-case ring A -.It \\(oa -.Pq lower-case ring a +The +.Nm +macros are classified by scope: line scope or block scope. Line +macros are only scoped to the current line (and, in some situations, +the subsequent line). Block macros are scoped to the current line and +subsequent lines until closed by another block macro. +. +. +.Ss Line Macros +Line macros are generally scoped to the current line, with the body +consisting of zero or more arguments. If a macro is scoped to the next +line and the line arguments are empty, the next line is used instead, +else the general syntax is used. Thus: +.Bd -literal -offset indent +\&.I +foo +.Ed +. +.Pp +is equivalent to +.Sq \&.I foo . +If next-line macros are invoked consecutively, only the last is used; in +other words, if a next-line macro is preceded by a block macro, it is +ignored. +.Bd -literal -offset indent +\&.YO \(lBbody...\(rB +\(lBbody...\(rB +.Ed +. +.Pp +.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" +.It Em Macro Ta Em Arguments Ta Em Scope +.It Sx \&B Ta n Ta next-line +.It Sx \&BI Ta n Ta current +.It Sx \&BR Ta n Ta current +.It Sx \&DT Ta 0 Ta current +.It Sx \&I Ta n Ta next-line +.It Sx \&IB Ta n Ta current +.It Sx \&IR Ta n Ta current +.It Sx \&PD Ta n Ta current +.It Sx \&R Ta n Ta next-line +.It Sx \&RB Ta n Ta current +.It Sx \&RI Ta n Ta current +.It Sx \&SB Ta n Ta next-line +.It Sx \&SM Ta n Ta next-line +.It Sx \&TH Ta >1, <6 Ta current +.It Sx \&UC Ta n Ta current +.It Sx \&br Ta 0 Ta current +.It Sx \&fi Ta 0 Ta current +.It Sx \&i Ta n Ta current +.It Sx \&na Ta 0 Ta current +.It Sx \&nf Ta 0 Ta current +.It Sx \&r Ta 0 Ta current +.It Sx \&sp Ta 1 Ta current .El -.\" PARAGRAPH +. .Pp -Monetary: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(Cs -.Pq Scandinavian -.It \\(Do -.Pq dollar -.It \\(Po -.Pq pound -.It \\(Ye -.Pq yen -.It \\(Fn -.Pq florin -.It \\(ct -.Pq cent +The +.Sx \&PD , +.Sx \&RS , +.Sx \&RE , +.Sx \&UC , +.Sx \&br , +.Sx \&fi , +.Sx \&i , +.Sx \&na , +.Sx \&nf , +.Sx \&r , +and +.Sx \&sp +macros should not be used. They're included for compatibility. +. +. +.Ss Block Macros +Block macros are comprised of a head and body. Like for in-line macros, +the head is scoped to the current line and, in one circumstance, the +next line; the body is scoped to subsequent lines and is closed out by a +subsequent block macro invocation. +.Bd -literal -offset indent +\&.YO \(lBhead...\(rB +\(lBhead...\(rB +\(lBbody...\(rB +.Ed +. +.Pp +The closure of body scope may be to the section, where a macro is closed +by +.Sx \&SH ; +sub-section, closed by a section or +.Sx \&SS ; +part, closed by a section, sub-section, or +.Sx \&RE ; +or paragraph, closed by a section, sub-section, part, +.Sx \&HP , +.Sx \&IP , +.Sx \&LP , +.Sx \&P , +.Sx \&PP , +or +.Sx \&TP . +No closure refers to an explicit block closing macro. +. +.Pp +.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent +.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope +.It Sx \&HP Ta <2 Ta current Ta paragraph +.It Sx \&IP Ta <3 Ta current Ta paragraph +.It Sx \&LP Ta 0 Ta current Ta paragraph +.It Sx \&P Ta 0 Ta current Ta paragraph +.It Sx \&PP Ta 0 Ta current Ta paragraph +.It Sx \&RE Ta 0 Ta current Ta none +.It Sx \&RS Ta 1 Ta current Ta part +.It Sx \&SH Ta >0 Ta next-line Ta section +.It Sx \&SS Ta >0 Ta next-line Ta sub-section +.It Sx \&TP Ta n Ta next-line Ta paragraph .El -.\" PARAGRAPH +. .Pp -Special symbols: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(de -.Pq degree -.It \\(ps -.Pq paragraph -.It \\(sc -.Pq section -.It \\(dg -.Pq dagger -.It \\(dd -.Pq double dagger -.It \\(ci -.Pq circle -.It \\(ba -.Pq bar -.It \\(bb -.Pq broken bar -.It \\(Ba -.Pq bar, deprecated -.It \\(co -.Pq copyright -.It \\(rg -.Pq registered -.It \\(tm -.Pq trademarked -.It \\& -.Pq non-breaking space -.It \\e -.Pq escape -.It \\(Am -.Pq ampersand, deprecated -.El -.\" SECTION -.Sh STRUCTURE -Macros are case in-sensitive and one to three three characters in -length. All follow the same structural rules: -.Bd -literal -offset XXXX -\&.Yo \(lBbody...\(rB +If a block macro is next-line scoped, it may only be followed by in-line +macros (excluding +.Sx \&DT , +.Sx \&PD , +.Sx \&TH , +.Sx \&UC , +.Sx \&br , +.Sx \&na , +.Sx \&sp , +.Sx \&nf , +and +.Sx \&fi ) . +. +. +.Sh REFERENCE +This section is a canonical reference to all macros, arranged +alphabetically. For the scoping of individual macros, see +.Sx MACRO SYNTAX . +. +. +.Ss \&B +Text is rendered in bold face. +.Pp +See also +.Sx \&I , +.Sx \&R , +.Sx \&b , +.Sx \&i , +and +.Sx \&r . +. +. +.Ss \&BI +Text is rendered alternately in bold face and italic. Thus, +.Sq .BI this word and that +causes +.Sq this +and +.Sq and +to render in bold face, while +.Sq word +and +.Sq that +render in italics. Whitespace between arguments is omitted in output. +.Pp +Examples: +.Bd -filled -offset indent +.Pf \. Sx \&BI +bold italic bold italic .Ed .Pp +The output of this example will be emboldened +.Dq bold +and italicised +.Dq italic , +with spaces stripped between arguments. +.Pp +See also +.Sx \&IB , +.Sx \&BR , +.Sx \&RB , +.Sx \&RI , +and +.Sx \&IR . +. +. +.Ss \&BR +Text is rendered alternately in bold face and roman (the default font). +Whitespace between arguments is omitted in output. +.Pp +See +.Sx \&BI +for an equivalent example. +.Pp +See also +.Sx \&BI , +.Sx \&IB , +.Sx \&RB , +.Sx \&RI , +and +.Sx \&IR . +. +. +.Ss \&DT +Has no effect. Included for compatibility. +. +. +.Ss \&HP +Begin a paragraph whose initial output line is left-justified, but +subsequent output lines are indented, with the following syntax: +.Bd -filled -offset indent +.Pf \. Sx \&HP +.Op Cm width +.Ed +.Pp The -.Dq body -consists of zero or more arguments to the macro. -.\" PARAGRAPH -.Sh MACROS -This section contains a complete list of all -.Nm -macros, arranged alphabetically, with the number of arguments. +.Cm width +argument must conform to +.Sx Scaling Widths . +If specified, it's saved for later paragraph left-margins; if unspecified, the +saved or default width is used. .Pp -.Bl -column "MacroX" "Arguments" -compact -offset XXXX -.It Em Macro Ta Em Arguments -.It \&.TH Ta >0 -.It \&.SH Ta n -.It \&.SS Ta n -.It \&.TP Ta n -.It \&.LP Ta n -.It \&.PP Ta n -.It \&.P Ta n -.It \&.IP Ta n -.It \&.HP Ta n -.It \&.SM Ta n -.It \&.SB Ta n -.It \&.BI Ta n -.It \&.IB Ta n -.It \&.BR Ta n -.It \&.RB Ta n -.It \&.R Ta n -.It \&.B Ta n -.It \&.I Ta n -.It \&.IR Ta n +See also +.Sx \&IP , +.Sx \&LP , +.Sx \&P , +.Sx \&PP , +and +.Sx \&TP . +. +. +.Ss \&I +Text is rendered in italics. +.Pp +See also +.Sx \&B , +.Sx \&R , +.Sx \&b , +.Sx \&i , +and +.Sx \&r . +. +. +.Ss \&IB +Text is rendered alternately in italics and bold face. Whitespace +between arguments is omitted in output. +.Pp +See +.Sx \&BI +for an equivalent example. +.Pp +See also +.Sx \&BI , +.Sx \&BR , +.Sx \&RB , +.Sx \&RI , +and +.Sx \&IR . +. +. +.Ss \&IP +Begin an indented paragraph with the following syntax: +.Bd -filled -offset indent +.Pf \. Sx \&IP +.Op Cm head Op Cm width +.Ed +.Pp +The +.Cm width +argument defines the width of the left margin and is defined by +.Sx Scaling Widths , +It's saved for later paragraph left-margins; if unspecified, the saved or +default width is used. +.Pp +The +.Cm head +argument is used as a leading term, flushed to the left margin. This is +useful for bulleted paragraphs and so on. +.Pp +See also +.Sx \&HP , +.Sx \&LP , +.Sx \&P , +.Sx \&PP , +and +.Sx \&TP . +. +. +.Ss \&IR +Text is rendered alternately in italics and roman (the default font). +Whitespace between arguments is omitted in output. +.Pp +See +.Sx \&BI +for an equivalent example. +.Pp +See also +.Sx \&BI , +.Sx \&IB , +.Sx \&BR , +.Sx \&RB , +and +.Sx \&RI . +. +. +.Ss \&LP +Begin an undecorated paragraph. The scope of a paragraph is closed by a +subsequent paragraph, sub-section, section, or end of file. The saved +paragraph left-margin width is re-set to the default. +.Pp +See also +.Sx \&HP , +.Sx \&IP , +.Sx \&P , +.Sx \&PP , +and +.Sx \&TP . +. +. +.Ss \&P +Synonym for +.Sx \&LP . +.Pp +See also +.Sx \&HP , +.Sx \&IP , +.Sx \&LP , +.Sx \&PP , +and +.Sx \&TP . +. +. +.Ss \&PP +Synonym for +.Sx \&LP . +.Pp +See also +.Sx \&HP , +.Sx \&IP , +.Sx \&LP , +.Sx \&P , +and +.Sx \&TP . +. +. +.Ss \&R +Text is rendered in roman (the default font). +.Pp +See also +.Sx \&I , +.Sx \&B , +.Sx \&b , +.Sx \&i , +and +.Sx \&r . +. +. +.Ss \&RB +Text is rendered alternately in roman (the default font) and bold face. +Whitespace between arguments is omitted in output. +.Pp +See +.Sx \&BI +for an equivalent example. +.Pp +See also +.Sx \&BI , +.Sx \&IB , +.Sx \&BR , +.Sx \&RI , +and +.Sx \&IR . +. +. +.Ss \&RE +Explicitly close out the scope of a prior +.Sx \&RS . +. +. +.Ss \&RI +Text is rendered alternately in roman (the default font) and italics. +Whitespace between arguments is omitted in output. +.Pp +See +.Sx \&BI +for an equivalent example. +.Pp +See also +.Sx \&BI , +.Sx \&IB , +.Sx \&BR , +.Sx \&RB , +and +.Sx \&IR . +. +. +.Ss \&RS +Begin a part setting the left margin. The left margin controls the +offset, following an initial indentation, to un-indented text such as +that of +.Sx \&PP . +This has the following syntax: +.Bd -filled -offset indent +.Pf \. Sx \&Rs +.Op Cm width +.Ed +.Pp +The +.Cm width +argument must conform to +.Sx Scaling Widths . +If not specified, the saved or default width is used. +. +. +.Ss \&SB +Text is rendered in small size (one point smaller than the default font) +bold face. +. +. +.Ss \&SH +Begin a section. The scope of a section is only closed by another +section or the end of file. The paragraph left-margin width is re-set +to the default. +. +. +.Ss \&SM +Text is rendered in small size (one point smaller than the default +font). +. +. +.Ss \&SS +Begin a sub-section. The scope of a sub-section is closed by a +subsequent sub-section, section, or end of file. The paragraph +left-margin width is re-set to the default. +. +. +.Ss \&TH +Sets the title of the manual page with the following syntax: +.Bd -filled -offset indent +.Pf \. Sx \&TH +.Cm title section +.Op Cm date Op Cm source Op Cm volume +.Ed +.Pp +At least the upper-case document title +.Cm title +and numeric manual section +.Cm section +arguments must be provided. The +.Cm date +argument should be formatted as described in +.Sx Dates : +if it does not conform, the current date is used instead. The +.Cm source +string specifies the organisation providing the utility. The +.Cm volume +string replaces the default rendered volume, which is dictated by the +manual section. +.Pp +Examples: +.Bd -filled -offset indent +\&.TH CVS 5 "1992-02-12" GNU +.Ed +. +. +.Ss \&TP +Begin a paragraph where the head, if exceeding the indentation width, is +followed by a newline; if not, the body follows on the same line after a +buffer to the indentation width. Subsequent output lines are indented. +The syntax is as follows: +.Bd -filled -offset indent +.Pf \. Sx \&TP +.Op Cm width +.Ed +.Pp +The +.Cm width +argument must conform to +.Sx Scaling Widths . +If specified, it's saved for later paragraph left-margins; if +unspecified, the saved or default width is used. +.Pp +See also +.Sx \&HP , +.Sx \&IP , +.Sx \&LP , +.Sx \&P , +and +.Sx \&PP . +. +. +.Ss \&PD +Has no effect. Included for compatibility. +. +. +.Ss \&UC +Has no effect. Included for compatibility. +. +. +.Ss \&br +Breaks the current line. Consecutive invocations have no further effect. +.Pp +See also +.Sx \&sp . +. +. +.Ss \&fi +End literal mode begun by +.Sx \&nf . +. +. +.Ss \&i +Italicise arguments. If no arguments are specified, all subsequent text +is italicised. +.Pp +See also +.Sx \&B , +.Sx \&I , +.Sx \&R . +.Sx \&b , +and +.Sx \&r . +. +. +.Ss \&na +Don't align to the right margin. +. +. +.Ss \&nf +Begin literal mode: all subsequent free-form lines have their end of +line boundaries preserved. May be ended by +.Sx \&fi . +. +. +.Ss \&r +Fonts and styles (bold face, italics) reset to roman (default font). +.Pp +See also +.Sx \&B , +.Sx \&I , +.Sx \&R , +.Sx \&b , +and +.Sx \&i . +. +. +.Ss \&sp +Insert vertical spaces into output with the following syntax: +.Bd -filled -offset indent +.Pf \. Sx \&sp +.Op Cm height +.Ed +.Pp +Insert +.Cm height +spaces, which must conform to +.Sx Scaling Widths . +If 0, this is equivalent to the +.Sx \&br +macro. Defaults to 1, if unspecified. +.Pp +See also +.Sx \&br . +. +. +.Sh COMPATIBILITY +This section documents compatibility with other roff implementations, at +this time limited to +.Xr groff 1 . +.Bl -hyphen +.It +In quoted literals, groff allowed pair-wise double-quotes to produce a +standalone double-quote in formatted output. This idiosyncratic +behaviour is no longer applicable. +.It +The +.Sq sp +macro does not accept negative numbers. +.It +Blocks of whitespace are stripped from both macro and free-form text +lines (except when in literal mode), while groff would retain whitespace +in free-form text lines. .El -.\" SECTION +. +. .Sh SEE ALSO -.Xr mandoc 1 -.\" SECTION +.Xr mandoc 1 , +.Xr mandoc_char 7 +. +. .Sh AUTHORS The .Nm -utility was written by -.An Kristaps Dzonsons Aq kristaps@openbsd.org . -.\" SECTION +reference was written by +.An Kristaps Dzonsons Aq kristaps@kth.se . +. +. .Sh CAVEATS Do not use this language. Use .Xr mdoc 7 , instead. +.