diff options
Diffstat (limited to 'mdoc.7')
| -rw-r--r-- | mdoc.7 | 285 |
1 files changed, 185 insertions, 100 deletions
@@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.4 2009/03/14 05:21:58 kristaps Exp $ +.\" $Id: mdoc.7,v 1.5 2009/03/16 22:19:19 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se> .\" @@ -16,7 +16,7 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 14 2009 $ +.Dd $Mdocdate: March 16 2009 $ .Dt mdoc 7 .Os .\" SECTION @@ -72,14 +72,16 @@ Within a macro line, the following characters are reserved: .It \&? .Pq question .It \&! -.Pq exclmamation +.Pq exclamation .El +.\" PARAGRAPH .Pp -Use of these characters must either be escaped with a non-breaking space -.Pq Sq \e& -or, if applicable, an appropriate escape-sequence used. Use of reserved -characters is described in +Use of reserved characters is described in .Sx Closure . +For general non-reserved use, characters must either be escaped with a +non-breaking space +.Pq Sq \e& +or, if applicable, an appropriate escape-sequence used. .\" SUB-SECTION .Ss Special Characters Special character sequences begin with the escape character @@ -121,6 +123,14 @@ Grammatic: .Pp Enclosures: .Bl -tag -width 12n -offset "XXXX" -compact +.It \\(lh +.Pq left hand +.It \\(rh +.Pq right hand +.It \\(<< +.Pq left guillemot +.It \\(>> +.Pq right guillemot .It \\(rC .Pq right brace .It \\(lC @@ -160,6 +170,18 @@ Indicatives: .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 @@ -200,12 +222,98 @@ Mathematical: .El .\" PARAGRAPH .Pp -Diacritics: +Diacritics and letter combinations: .Bl -tag -width 12n -offset "XXXX" -compact .It \\(ga .Pq accent grave .It \\(aa .Pq accent accute +.It \\(ad +.Pq accent dieresis +.It \\(a~ +.Pq accent tilde +.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 \\('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 .El .\" PARAGRAPH .Pp @@ -219,6 +327,10 @@ Special symbols: .Pq bar, deprecated .It \\(co .Pq copyright +.It \\(rg +.Pq registered +.It \\(tm +.Pq trademarked .It \\& .Pq non-breaking space .It \\e @@ -239,17 +351,18 @@ may span multiple lines. .Bl -inset -offset XXXX .\" LIST-ITEM .It Em Full-block -macros always span multiple lines. They consist optionally of one or +macros always span multiple lines. They consist of zero or more .Qq heads , -subsequent macros or text on the same line following invocation; a +subsequent macros or text on the same line following invocation; an +optional .Qq body , which spans subsequent lines of text or macros; and an optional .Qq tail , macros or text on the same line following closure. .\" LIST-ITEM .It Em Partial-block -macros may span multiple lines. They consists optionally of a +macros may span multiple lines. They consists of a optional .Qq head , text immediately following invocation; always a .Qq body , @@ -307,95 +420,6 @@ are followed by non-reserved characters, the behaviour differs per macro. In general, scope of the macro is closed and re-opened: subsequent tokens are interpreted as if the scope had just been opened. In other circumstances, scope is simply closed out. -.\" .\" SUB-SECTION -.\" .Ss Examples -.\" The following examples illustrate each macro classification. -.\" .\" PARAGRAPH -.\" .Pp -.\" Implicit full-block. Has head, body and no tail. Scope closed by -.\" second -.\" .Sq \&Sh -.\" invocation. -.\" .Bd -literal -offset XXXX -.\" \&.Sh SECTION 1 -.\" body... -.\" \&.Sh SECTION 2 -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Nested implicit full-block, where the subsection -.\" .Sq \&Ss -.\" is within the scope of the parent section -.\" .Sq \&Sh -.\" and closed along with its parent by the subsequent -.\" .Sq \&Sh . -.\" .Bd -literal -offset XXXX -.\" \&.Sh SECTION 1 -.\" \&.Ss Subsection 1 -.\" body... -.\" \&.Sh SECTION 2 -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Explicit full-block. Has a head, a body and no tail. Scope closed by -.\" .Sq \&Ef -.\" invocation. -.\" .Bd -literal -offset XXXX -.\" \&.Bf symbolic -.\" body... -.\" \&.Ef -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Nested explicit/implicit scope. -.\" .Sq \&It -.\" macro is an implicit block whose scope is closed by the explicit -.\" .Sq \&El -.\" closure. -.\" .Bd -literal -offset XXXX -.\" \&.Bl \-bullet -.\" \&.It head -.\" body... -.\" \&.El -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Explicit partial-block. Has head, body and tail. Scope closed by -.\" .Sq \&Ec -.\" invocation. -.\" .Bd -literal -offset XXX -.\" \&.Eo head body... \&Ec tail -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Implicit partial-block. Has only body. Scope is closed by end-of-line. -.\" .Bd -literal -offset XXX -.\" \&.Sq body... -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Explicit partial-block with only body and scope closed by -.\" .Sq \&Ac -.\" invocation. -.\" .Bd -literal -offset XXXX -.\" \&.Ao body... \&Ac -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Implicit partial-block enclosing explicit partial-block. -.\" .Bd -literal -offset XXX -.\" \&.Sq body... \&Ao body... \&Ac -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Inline macros, several in sequence. Scope is closed for -.\" .Sq \&Fl -.\" by the punctuation delimiter and -.\" .Sq \&Ar -.\" by the end-of-line. -.\" .Bd -literal -offset XXXX -.\" \&.Fl text0 text1 ; Ar text0 text1 -.\" .Ed .\" SECTION .Sh SYNTAX Macros are generally two and at times three characters in length. The @@ -640,6 +664,12 @@ compatibility with these systems. .Bl -dash -compact .\" LIST-ITEM .It +.Sq \&Fo +and +.Sq \&St +historically weren't always callable. Both are now correctly callable. +.\" LIST-ITEM +.It .Sq \&It \-nested is assumed for all lists: any list may be nested and .Sq \-enum @@ -689,3 +719,58 @@ The .Nm utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . +.\" SECTION +.Sh CAVEATS +There are several ambiguous parts of mdoc. +.Pp +.Bl -dash -compact +.\" LIST-ITEM +.It +.Sq \&Fa +should be +.Sq \&Va +as function arguments are variables. +.\" LIST-ITEM +.It +.Sq \&Ft +should be +.Sq \&Vt +as function return types are still types. Furthermore, the +.Sq \&Ft +should be removed and +.Sq \&Fo , +which ostensibly follows it, should follow the same convention as +.Sq \&Va . +.\" LIST-ITEM +.It +.Sq \&Va +should formalise that only one or two arguments are acceptable: a +variable name and optional, preceeding type. +.\" LIST-ITEM +.It +.Sq \&Fd +is ambiguous. It's commonly used to indicate an include file in the +synopsis section. +.Sq \&In +should be used, instead. +.\" LIST-ITEM +.It +Only the +.Sq \-literal +argument to +.Sq \&Bd +makes sense. The remaining ones should be removed. +.\" LIST-ITEM +.It +The +.Sq \&Xo +and +.Sq \&Xc +macros should be deprecated. +.\" LIST-ITEM +.It +The +.Sq \&Dt +macro lacks clarity. It should be absolutely clear which title will +render when formatting the manual page. +.El |