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

Diff for /mandoc/mdoc.7 between version 1.5 and 1.13

version 1.5, 2009/03/16 22:19:19 version 1.13, 2009/03/22 08:52:27
Line 1 
Line 1 
 .\" $Id$  .\" $Id$
 .\"  .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>  .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"  .\"
 .\" 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
Line 30  The
Line 30  The
 language is used to format  language is used to format
 .Bx  .Bx
 .Ux  .Ux
 manuals.  An  manuals.  In this reference document, we describe the syntax, ontology
   and structure of the
 .Nm  .Nm
   language.
   .\" PARAGRAPH
   .Pp
   An
   .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.  This document describes the encoding, ontology and syntax  prior macros:
 of these macros.  .Bd -literal -offset XXX
   \&.Sh Macro lines change control state.
   Other lines are interpreted within the current state.
   .Ed
   .\" PARAGRAPH
   .Pp
   Macros are two- or three-character sequences whose scope rules, rules
   that dictate handling of subsequent-line or same-line arguments, are
   governed by one of five classifications described in this document.
 .\" SECTION  .\" SECTION
 .Sh CHARACTER ENCODING  .Sh INPUT ENCODING
 .Nm  .Nm
 documents may contain only printable alphanumeric characters, the space  documents may contain only graphable 7-bit ASCII characters, the space
 character  character
 .Sq \  ,  .Sq \  ,
 and, in certain circumstances, the tab character  and, in certain circumstances, the tab character
 .Sq \et .  .Sq \et .
 All manuals must have  All manuals must have
 .Sq \en  .Sq \en
 line termination.  line termination.
   .Pp
   The only time a blank line is acceptable is within
   the context of
   .Sq \&Bd \-literal
   or
   .Sq \&Bd \-unfilled .
   .Pp
   Tab characters
   .Pq \et
   are only acceptable when delimiting
   .Sq \&Bl \-column
   and in
   .Sq \&Bd \-literal
   or
   .Sq \&Bd \-unfilled
   contexts.
 .\" SUB-SECTION  .\" SUB-SECTION
 .Ss Reserved Characters  .Ss Reserved Characters
 Within a macro line, the following characters are reserved:  Within a macro line, the following characters are reserved:
Line 118  Grammatic:
Line 148  Grammatic:
 .Pq space  .Pq space
 .It \\.  .It \\.
 .Pq period  .Pq period
   .It \\(r!
   .Pq upside-down exclamation
   .It \\(r?
   .Pq upside-down question
 .El  .El
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .Pp
Line 127  Enclosures:
Line 161  Enclosures:
 .Pq left hand  .Pq left hand
 .It \\(rh  .It \\(rh
 .Pq right hand  .Pq right hand
 .It \\(<<  .It \\(Fo
 .Pq left guillemot  .Pq left guillemet
 .It \\(>>  .It \\(Fc
 .Pq right guillemot  .Pq right guillemet
   .It \\(fo
   .Pq left guilsing
   .It \\(fc
   .Pq right guilsing
 .It \\(rC  .It \\(rC
 .Pq right brace  .Pq right brace
 .It \\(lC  .It \\(lC
Line 157  Enclosures:
Line 195  Enclosures:
 .Pq left single-quote  .Pq left single-quote
 .It \\(aq  .It \\(aq
 .Pq right single-quote  .Pq right single-quote
   .It \\(Bq
   .Pq right low double-quote
   .It \\(bq
   .Pq right low single-quote
 .El  .El
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .Pp
Line 187  Indicatives:
Line 229  Indicatives:
 .Pp  .Pp
 Mathematical:  Mathematical:
 .Bl -tag -width 12n -offset "XXXX" -compact  .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  .It \\(Gt
 .Pq greater-than, deprecated  .Pq greater-than, deprecated
 .It \\(Lt  .It \\(Lt
Line 222  Mathematical:
Line 318  Mathematical:
 .El  .El
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .Pp
 Diacritics and letter combinations:  Ligatures:
 .Bl -tag -width 12n -offset "XXXX" -compact  .Bl -tag -width 12n -offset "XXXX" -compact
 .It \\(ga  .It \\(ss
 .Pq accent grave  .Pq German eszett
 .It \\(aa  
 .Pq accent accute  
 .It \\(ad  
 .Pq accent dieresis  
 .It \\(a~  
 .Pq accent tilde  
 .It \\(AE  .It \\(AE
 .Pq upper-case AE  .Pq upper-case AE
 .It \\(ae  .It \\(ae
Line 240  Diacritics and letter combinations:
Line 330  Diacritics and letter combinations:
 .Pq upper-case OE  .Pq upper-case OE
 .It \\(oe  .It \\(oe
 .Pq lower-case 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  .It \\('A
 .Pq upper-case acute A  .Pq upper-case acute A
 .It \\('E  .It \\('E
Line 314  Diacritics and letter combinations:
Line 453  Diacritics and letter combinations:
 .Pq lower-case dieresis u  .Pq lower-case dieresis u
 .It \\(:y  .It \\(:y
 .Pq lower-case dieresis 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  .El
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .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:  Special symbols:
 .Bl -tag -width 12n -offset "XXXX" -compact  .Bl -tag -width 12n -offset "XXXX" -compact
 .It \\(bu  .It \\(de
 .Pq bullet  .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  .It \\(ba
 .Pq bar  .Pq bar
   .It \\(bb
   .Pq broken bar
 .It \\(Ba  .It \\(Ba
 .Pq bar, deprecated  .Pq bar, deprecated
 .It \\(co  .It \\(co
Line 340  Special symbols:
Line 544  Special symbols:
 .El  .El
 .\" SECTION  .\" SECTION
 .Sh ONTOLOGY  .Sh ONTOLOGY
 Macros are classified in an ontology described by scope rules.  Macros are classified in an ontology described by their scope rules.
   Some macros are allowed to deviate from their classifications to
   preserve backward-compatibility with old macro combinations still found
   in the manual corpus.  These are specifically noted on a per-macro
   basis.
 .\" SUB-SECTION  .\" SUB-SECTION
 .Ss Scope  .Ss Scope
 .Bl -inset  .Bl -inset
Line 540  close at the invocation's end-of-line.
Line 748  close at the invocation's end-of-line.
 .It \&.Dl    Ta    \&No  Ta    Yes  .It \&.Dl    Ta    \&No  Ta    Yes
 .It \&.Ql    Ta    Yes   Ta    Yes  .It \&.Ql    Ta    Yes   Ta    Yes
 .El  .El
   .\" PARAGRAPH
   .Pp
   The
   .Sq \&Op
   may be broken by \&Oc as in the following example:
   .Bd -literal -offset XXXX
   \&.Oo
   \&.Op Fl a Oc
   .Ed
   .Pp
   In the above example, the scope of
   .Sq \&Op
   is technically broken by
   .Sq \&Oc ,
   however, due to the overwhelming existence of this sequence, it's
   allowed.
 .\" SUB-SECTION  .\" SUB-SECTION
 .Ss Block partial-explicit  .Ss Block partial-explicit
 Each of these contains at least a body and, in limited circumstances, a  Each of these contains at least a body and, in limited circumstances, a
Line 593  then the macro accepts an arbitrary number of argument
Line 817  then the macro accepts an arbitrary number of argument
 .It \&.Ar    Ta    Yes   Ta    Yes     Ta    n  .It \&.Ar    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Cd    Ta    Yes   Ta    \&No    Ta    >0  .It \&.Cd    Ta    Yes   Ta    \&No    Ta    >0
 .It \&.Cm    Ta    Yes   Ta    Yes     Ta    n  .It \&.Cm    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Dv    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Dv    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Er    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Er    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Ev    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Ev    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Ex    Ta    \&No  Ta    \&No    Ta    0  .It \&.Ex    Ta    \&No  Ta    \&No    Ta    0
 .It \&.Fa    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Fa    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Fd    Ta    \&No  Ta    \&No    Ta    >0  .It \&.Fd    Ta    \&No  Ta    \&No    Ta    >0
 .It \&.Fl    Ta    Yes   Ta    Yes     Ta    n  .It \&.Fl    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Fn    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Fn    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Ft    Ta    \&No  Ta    Yes     Ta    n  .It \&.Ft    Ta    \&No  Ta    Yes     Ta    n
 .It \&.Ic    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Ic    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.In    Ta    \&No  Ta    \&No    Ta    n  .It \&.In    Ta    \&No  Ta    \&No    Ta    n
 .It \&.Li    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Li    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Nd    Ta    \&No  Ta    \&No    Ta    n  .It \&.Nd    Ta    \&No  Ta    \&No    Ta    n
 .It \&.Nm    Ta    Yes   Ta    Yes     Ta    n  .It \&.Nm    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Ot    Ta    \&No  Ta    \&No    Ta    n  .It \&.Ot    Ta    \&No  Ta    \&No    Ta    n
 .It \&.Pa    Ta    Yes   Ta    Yes     Ta    n  .It \&.Pa    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Rv    Ta    \&No  Ta    \&No    Ta    0  .It \&.Rv    Ta    \&No  Ta    \&No    Ta    0
 .It \&.St    Ta    \&No  Ta    Yes     Ta    1  .It \&.St    Ta    \&No  Ta    Yes     Ta    1
 .It \&.Va    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Va    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Vt    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Vt    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Xr    Ta    Yes   Ta    Yes     Ta    >0, <3  .It \&.Xr    Ta    Yes   Ta    Yes     Ta    >0, <3
 .It \&.%A    Ta    \&No  Ta    \&No    Ta    >0  .It \&.%A    Ta    \&No  Ta    \&No    Ta    >0
Line 630  then the macro accepts an arbitrary number of argument
Line 854  then the macro accepts an arbitrary number of argument
 .It \&.Bsx   Ta    Yes   Ta    Yes     Ta    n  .It \&.Bsx   Ta    Yes   Ta    Yes     Ta    n
 .It \&.Bx    Ta    Yes   Ta    Yes     Ta    n  .It \&.Bx    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Db    Ta    \&No  Ta    \&No    Ta    1  .It \&.Db    Ta    \&No  Ta    \&No    Ta    1
 .It \&.Em    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Em    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Fx    Ta    Yes   Ta    Yes     Ta    n  .It \&.Fx    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Ms    Ta    \&No  Ta    Yes     Ta    >0  .It \&.Ms    Ta    \&No  Ta    Yes     Ta    >0
 .It \&.No    Ta    Yes   Ta    Yes     Ta    0  .It \&.No    Ta    Yes   Ta    Yes     Ta    0
Line 643  then the macro accepts an arbitrary number of argument
Line 867  then the macro accepts an arbitrary number of argument
 .It \&.Sy    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Sy    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Tn    Ta    Yes   Ta    Yes     Ta    >0  .It \&.Tn    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Ux    Ta    Yes   Ta    Yes     Ta    n  .It \&.Ux    Ta    Yes   Ta    Yes     Ta    n
   .It \&.Dx    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Bt    Ta    \&No  Ta    \&No    Ta    0  .It \&.Bt    Ta    \&No  Ta    \&No    Ta    0
 .It \&.Hf    Ta    \&No  Ta    \&No    Ta    n  .It \&.Hf    Ta    \&No  Ta    \&No    Ta    n
 .It \&.Fr    Ta    \&No  Ta    \&No    Ta    n  .It \&.Fr    Ta    \&No  Ta    \&No    Ta    n
Line 652  then the macro accepts an arbitrary number of argument
Line 877  then the macro accepts an arbitrary number of argument
 .It \&.Lp    Ta    \&No  Ta    \&No    Ta    0  .It \&.Lp    Ta    \&No  Ta    \&No    Ta    0
 .It \&.Lk    Ta    \&No  Ta    Yes     Ta    >0  .It \&.Lk    Ta    \&No  Ta    Yes     Ta    >0
 .It \&.Mt    Ta    \&No  Ta    Yes     Ta    >0  .It \&.Mt    Ta    \&No  Ta    Yes     Ta    >0
   .It \&.Es    Ta    \&No  Ta    \&No    Ta    0
   .It \&.En    Ta    \&No  Ta    \&No    Ta    0
 .El  .El
   .Pp
   The
   .Sq \&Ot ,
   .Sq \&Fr ,
   .Sq \&Es
   and
   .Sq \&En ,
   macros are obsolete.
 .\" SECTION  .\" SECTION
 .Sh COMPATIBILITY  .Sh COMPATIBILITY
 The mdoc language was traditionally a  The mdoc language was traditionally a
Line 718  is callable.
Line 953  is callable.
 The  The
 .Nm  .Nm
 utility was written by  utility was written by
 .An Kristaps Dzonsons Aq kristaps@kth.se .  .An Kristaps Dzonsons Aq kristaps@openbsd.org .
 .\" SECTION  .\" SECTION
 .Sh CAVEATS  .Sh CAVEATS
 There are several ambiguous parts of mdoc.  There are several ambiguous parts of mdoc.
Line 773  The
Line 1008  The
 .Sq \&Dt  .Sq \&Dt
 macro lacks clarity.  It should be absolutely clear which title will  macro lacks clarity.  It should be absolutely clear which title will
 render when formatting the manual page.  render when formatting the manual page.
   .\" LIST-ITEM
   .It
   A
   .Sq \&Lx
   should be provided for Linux (\(`a la
   .Sq \&Ox ,
   .Sq \&Nx
   etc.).
 .El  .El
Legend:
Removed from v.1.5  
changed lines
  Added in v.1.13
CVSweb