[BACK]Return to man.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/man.7 between version 1.1 and 1.20

version 1.1, 2009/03/23 16:02:56 version 1.20, 2009/07/20 13:45:11
Line 1 
Line 1 
 .\" $Id$  .\"     $Id$
 .\"  .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>  .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"  .\"
 .\" Permission to use, copy, modify, and distribute this software for any  .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the  .\" purpose with or without fee is hereby granted, provided that the above
 .\" above copyright notice and this permission notice appear in all  .\" copyright notice and this permission notice appear in all copies.
 .\" copies.  
 .\"  .\"
 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL  .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED  .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE  .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL  .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR  .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER  .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR  .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\" PERFORMANCE OF THIS SOFTWARE.  .\"
 .\"  
 .Dd $Mdocdate$  .Dd $Mdocdate$
 .Dt man 7  .Dt MAN 7
 .Os  .Os
 .\" SECTION  .\" SECTION
 .Sh NAME  .Sh NAME
Line 27 
Line 25 
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm man  .Nm man
 language was historically used to format  language was historically used to format
 .Ux  .Ux
 manuals.  In this reference document, we describe the syntax and  manuals.  This reference document describes its syntax, structure, and
 structure of the  usage.
 .Nm  
 language.  
 .Pp  .Pp
 .Em \&Do not  .Bf -emphasis
 use  Do not use
 .Nm  .Nm
 to write your manuals.  Use the  to write your manuals.
   .Ef
   Use the
 .Xr mdoc 7  .Xr mdoc 7
 language, instead.  language, instead.
 .\" PARAGRAPH  .\" PARAGRAPH
Line 45  language, instead.
Line 43  language, instead.
 An  An
 .Nm  .Nm
 document follows simple rules:  lines beginning with the control  document follows simple rules:  lines beginning with the control
 character  character
 .Sq \.  .Sq \&.
 are parsed for macros.  Other lines are interpreted within the scope of  are parsed for macros.  Other lines are interpreted within the scope of
 prior macros:  prior macros:
 .Bd -literal -offset XXX  .Bd -literal -offset indent
 \&.SH Macro lines change control state.  \&.SH Macro lines change control state.
 Other lines are interpreted within the current state.  Other lines are interpreted within the current state.
 .Ed  .Ed
 .\" PARAGRAPH  
 .Pp  
 Macros are character sequences whose structural rules are described  
 later in this document.  
 .\" SECTION  .\" SECTION
 .Sh INPUT ENCODING  .Sh INPUT ENCODING
 .Nm  .Nm
 documents may contain only graphable 7-bit ASCII characters and the  documents may contain only graphable 7-bit ASCII characters, the
 space character  space character, and the tabs character.  All manuals must have
 .Sq \  .  .Ux
 All manuals must have  line termination.
 .Sq \en  
 line termination.  
 .Pp  .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.  vertical space.
   .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.
 .\" SUB-SECTION  .\" SUB-SECTION
   .Ss Comments
   Anything following a
   .Sq \e"
   delimiter is considered a comment (unless the
   .Sq \e
   itself has been escaped) and is ignored to the end of line.
   Furthermore, a macro line with only a control character
   .Sq \. ,
   optionally followed by whitespace, is ignored.
   .\" SUB-SECTION
 .Ss Special Characters  .Ss Special Characters
 Special character sequences begin with the escape character  Special character sequences begin with the escape character
 .Sq \\  .Sq \e
 followed by either an open-parenthesis  followed by either an open-parenthesis
 .Sq \&(  .Sq \&(
 for two-character sequences; an open-bracket  for two-character sequences; an open-bracket
 .Sq \&[  .Sq \&[
Line 82  for n-character sequences (terminated at a close-brack
Line 91  for n-character sequences (terminated at a close-brack
 or a single one-character sequence.  or a single one-character sequence.
 .Pp  .Pp
 Characters may alternatively be escaped by a slash-asterisk,  Characters may alternatively be escaped by a slash-asterisk,
 .Sq \\* ,  .Sq \e* ,
 with the same combinations as described above.  This form is deprecated.  with the same combinations as described above.
 .Pp  .Pp
 The following is a table of all available escapes.  Terms may also be text-decorated using the
   .Sq \ef
   escape followed by a text-decoration letter: B (bold), I, (italic), or P
   and R (Roman, or reset).
   .\" SUB-SECTION
   .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 .
   .\" SECTION
   .Sh STRUCTURE
   Each
   .Nm
   document must contain contains at least the
   .Sq \&.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  .Pp
 Grammatic:  Beyond the
 .Bl -tag -width 12n -offset "XXXX" -compact  .Sq \&.TH ,
 .It \\(em  at least one macro or text node must appear in the document.
 .Pq em-dash  .\" SECTION
 .It \\(en  .Sh SYNTAX
 .Pq en-dash  Macros are one to three three characters in length and begin with a
 .It \e-  control character ,
 .Pq hyphen  .Sq \&. ,
 .It \\\\  at the beginning of the line.  An arbitrary amount of whitespace may
 .Pq back-slash  sit between the control character and the macro name.  Thus,
 .It \e'  .Sq \&.PP
 .Pq apostrophe  and
 .It \e`  .Sq \&.\ \ \ \&PP
 .Pq back-tick  are equivalent.
 .It \\  
 .Pq space  
 .It \\.  
 .Pq period  
 .It \\(r!  
 .Pq upside-down exclamation  
 .It \\(r?  
 .Pq upside-down question  
 .El  
 .\" PARAGRAPH  
 .Pp  .Pp
 Enclosures:  All
 .Bl -tag -width 12n -offset "XXXX" -compact  .Nm
 .It \\(lh  macros follow the same structural rules:
 .Pq left hand  .Bd -literal -offset indent
 .It \\(rh  \&.YO \(lBbody...\(rB
 .Pq right hand  .Ed
 .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  
 .Pp  .Pp
 Indicatives:  The
 .Bl -tag -width 12n -offset "XXXX" -compact  .Dq body
 .It \\(<-  consists of zero or more arguments to the macro.
 .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  
 .Pp  .Pp
 Mathematical:  .Nm
 .Bl -tag -width 12n -offset "XXXX" -compact  has a primitive notion of multi-line scope for the following macros:
 .It \\(es  .Sq \&.TM ,
 .Pq empty set  .Sq \&.SM ,
 .It \\(ca  .Sq \&.SB ,
 .Pq intersection  .Sq \&.BI ,
 .It \\(cu  .Sq \&.IB ,
 .Pq union  .Sq \&.BR ,
 .It \\(gr  .Sq \&.RB ,
 .Pq gradient  .Sq \&.R ,
 .It \\(pd  .Sq \&.B ,
 .Pq partial differential  .Sq \&.I ,
 .It \\(ap  .Sq \&.IR
 .Pq similarity  and
 .It \\(=)  .Sq \&.RI .
 .Pq proper superset  When these macros are invoked without arguments, the subsequent line is
 .It \\((=  considered a continuation of the macro.  Thus:
 .Pq proper subset  .Bd -literal -offset indent
 .It \\(eq  \&.RI
 .Pq equals  foo
 .It \\(di  .Ed
 .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  
 .Pp  .Pp
 Ligatures:  is equivalent to
 .Bl -tag -width 12n -offset "XXXX" -compact  .Sq \&.RI foo .
 .It \\(ss  If two consecutive lines exhibit the latter behaviour,
 .Pq German eszett  an error is raised.  Thus, the following is not acceptable:
 .It \\(AE  .Bd -literal -offset indent
 .Pq upper-case AE  \&.RI
 .It \\(ae  \&.I
 .Pq lower-case AE  Hello, world.
 .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  
 .El  
 .\" PARAGRAPH  
 .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  
 .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  
 .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  
 .Ed  .Ed
 .Pp  .Pp
 The  The
 .Dq body  .Sq \&.TP
 consists of zero or more arguments to the macro.  macro is similar, but does not need an empty argument line to trigger
 .\" PARAGRAPH  the behaviour.
   .\" SECTION
 .Sh MACROS  .Sh MACROS
 This section contains a complete list of all  This section contains a complete list of all
 .Nm  .Nm
 macros, arranged alphabetically, with the number of arguments.  macros and corresponding number of arguments.
 .Pp  .Pp
 .Bl -column "MacroX" "Arguments" -compact -offset XXXX  .Bl -column "MacroX" "Arguments" -compact -offset indent
 .It Em Macro Ta Em Arguments  .It Em Macro Ta Em Arguments
 .It \&.TH    Ta    >0  .It \&.TH    Ta    >1, <6
 .It \&.SH    Ta    n  .It \&.SH    Ta    >0
 .It \&.SS    Ta    n  .It \&.SS    Ta    >0
 .It \&.TP    Ta    n  .It \&.TP    Ta    n
 .It \&.LP    Ta    n  .It \&.LP    Ta    0
 .It \&.PP    Ta    n  .It \&.PP    Ta    0
 .It \&.P     Ta    n  .It \&.P     Ta    0
 .It \&.IP    Ta    n  .It \&.IP    Ta    <3
 .It \&.HP    Ta    n  .It \&.HP    Ta    <2
 .It \&.SM    Ta    n  .It \&.SM    Ta    n
 .It \&.SB    Ta    n  .It \&.SB    Ta    n
 .It \&.BI    Ta    n  .It \&.BI    Ta    n
Line 537  macros, arranged alphabetically, with the number of ar
Line 203  macros, arranged alphabetically, with the number of ar
 .It \&.B     Ta    n  .It \&.B     Ta    n
 .It \&.I     Ta    n  .It \&.I     Ta    n
 .It \&.IR    Ta    n  .It \&.IR    Ta    n
   .It \&.RI    Ta    n
 .El  .El
   .Pp
   Although not historically part of the
   .Nm
   system, the following macros are also supported:
   .Pp
   .Bl -column "MacroX" "Arguments" -compact -offset indent
   .It Em Macro Ta Em Arguments
   .It \&.br    Ta    0
   .It \&.i     Ta    n
   .El
   .Pp
   These follow the same calling conventions as the above
   .Nm
   macros.
 .\" SECTION  .\" SECTION
   .Sh COMPATIBILITY
   See
   .Xr mdoc 7
   for groff compatibility notes.
   .\" SECTION
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr mandoc 1  .Xr mandoc 1 ,
   .Xr mandoc_char 7
 .\" SECTION  .\" SECTION
 .Sh AUTHORS  .Sh AUTHORS
 The  The
 .Nm  .Nm
 utility was written by  utility was written by
 .An Kristaps Dzonsons Aq kristaps@openbsd.org .  .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION  .\" SECTION
 .Sh CAVEATS  .Sh CAVEATS
 Do not use this language.  Use  Do not use this language.  Use
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.20
CVSweb