1 .\" $Id: mdoc.7,v 1.1 2009/03/13 07:46:10 kristaps Exp $
3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the
7 .\" above copyright notice and this permission notice appear in all
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
11 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
12 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
13 .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
14 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
15 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
16 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17 .\" PERFORMANCE OF THIS SOFTWARE.
19 .Dd $Mdocdate: March 13 2009 $
25 .Nd mdoc macro reference
30 language is used to format
35 document follows simple rules: lines beginning with the control
38 are parsed for macros. Other lines are interpreted within the scope of
39 prior macros. Macros are either two or three characters in length.
41 .Sh CHARACTER ENCODING
43 documents may contain only printable alphanumeric characters, the space
46 and, in certain circumstances, the tab character
52 .Ss Special Characters
53 Within a macro line, the following characters are special:
56 .Bl -tag -width Ds -offset XXXX -compact
79 Use of these characters must either be escaped with a non-breaking space
81 or, if applicable, an appropriate escape-sequence used.
83 .Ss Special Characters
84 Special character sequences begin with the escape character
86 and followed by either an open-parenthesis
88 for two-character sequences; an open-bracket
90 for n-character sequences (terminated at a close-bracket
92 or a single one-character sequence.
94 Characters may alternatively be escaped by a slash-asterisk,
96 with the same combinations as described above. This form, however, is
97 deprecated. The following is a table of all available escapes, arranged
102 .Bl -tag -width 12n -offset "XXXX" -compact
124 .Bl -tag -width 12n -offset "XXXX" -compact
140 .Pq left double-quote
142 .Pq left double-quote, deprecated
144 .Pq right double-quote
146 .Pq right double-quote, deprecated
148 .Pq left single-quote
150 .Pq right single-quote
156 .Bl -tag -width 12n -offset "XXXX" -compact
170 .Bl -tag -width 12n -offset "XXXX" -compact
172 .Pq greater-than, deprecated
174 .Pq less-than, deprecated
178 .Pq less-than-equal, deprecated
180 .Pq greater-than-equal
182 .Pq greater-than-equal
188 .Pq not equal, deprecated
192 .Pq infinity, deprecated
194 .Pq NaN , an extension
200 .Pq plus-minus, deprecated
208 .Bl -tag -width 12n -offset "XXXX" -compact
218 .Bl -tag -width 12n -offset "XXXX" -compact
228 .Pq non-breaking space
232 .Pq ampersand, deprecated
236 Macros are classified in an ontology described by scope rules.
237 .Bl -tag -width "in-lineX"
240 Block macros enclose other block macros, in-line macros or text, and
241 may span multiple lines.
243 block scope is closed by a subsequent invocation of the same macro,
244 one of a set of corresponding closure macros or end-of-file.
246 block scope is closed by a corresponding closure macro.
247 .Bl -tag -width "partial-blockX"
250 Always spans multiple lines. Consists optionally of one or more
252 subsequent macros or text on the same line following invocation; a
254 which spans subsequent lines of text or macros; and an optional
256 macros or text on the same line following closure.
259 May span multiple lines. Consists optionally of a
261 text immediately following invocation; always a
263 text or macros following the head on the same and subsequent lines; and
266 text immediately following closure.
270 In-line macros may only enclose text and span at most a single line. If
271 a macro is parsable, its scope may be closed by subsequent macros or
272 delimiting punctuation. In-line macros follow different conventions for
275 for per-macro details.
279 .\" The following examples illustrate each macro classification.
282 .\" Implicit full-block. Has head, body and no tail. Scope closed by
286 .\" .Bd -literal -offset XXXX
293 .\" Nested implicit full-block, where the subsection
295 .\" is within the scope of the parent section
297 .\" and closed along with its parent by the subsequent
299 .\" .Bd -literal -offset XXXX
301 .\" \&.Ss Subsection 1
307 .\" Explicit full-block. Has a head, a body and no tail. Scope closed by
310 .\" .Bd -literal -offset XXXX
317 .\" Nested explicit/implicit scope.
319 .\" macro is an implicit block whose scope is closed by the explicit
322 .\" .Bd -literal -offset XXXX
330 .\" Explicit partial-block. Has head, body and tail. Scope closed by
333 .\" .Bd -literal -offset XXX
334 .\" \&.Eo head body... \&Ec tail
338 .\" Implicit partial-block. Has only body. Scope is closed by end-of-line.
339 .\" .Bd -literal -offset XXX
344 .\" Explicit partial-block with only body and scope closed by
347 .\" .Bd -literal -offset XXXX
348 .\" \&.Ao body... \&Ac
352 .\" Implicit partial-block enclosing explicit partial-block.
353 .\" .Bd -literal -offset XXX
354 .\" \&.Sq body... \&Ao body... \&Ac
358 .\" Inline macros, several in sequence. Scope is closed for
360 .\" by the punctuation delimiter and
362 .\" by the end-of-line.
363 .\" .Bd -literal -offset XXXX
364 .\" \&.Fl text0 text1 ; Ar text0 text1
368 This section contains a complete list of all
370 macros, arranged ontologically then alphanumerically by macro name. A
372 macro is may be invoked subsequent to the initial macro-line macro. A
374 macro May be followed by further (ostensibly callable) macros.
376 .Ss Block full-implicit
377 The head of these macros follows invocation; the body is the content of
378 subsequent lines prior to closure. None of these macros have tails;
388 .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
389 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
390 .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
391 .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
392 .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
395 .Ss Block full-explicit
396 None of these macros are callable or parsed. The last column indicates
397 the explicit scope rules. All contains bodies, some may contain heads
400 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
401 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
402 .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
403 .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
404 .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
405 .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
406 .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
407 .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
410 .Ss Block partial-implicit
411 All of these are callable and parsed for further macros. Their scopes
412 close at the invocation's end-of-line.
414 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
415 .It Em Macro Ta Em Callable Ta Em Parsable
416 .It \&.Aq Ta Yes Ta Yes
417 .It \&.Op Ta Yes Ta Yes
418 .It \&.Bq Ta Yes Ta Yes
419 .It \&.Dq Ta Yes Ta Yes
420 .It \&.Pq Ta Yes Ta Yes
421 .It \&.Qq Ta Yes Ta Yes
422 .It \&.Sq Ta Yes Ta Yes
423 .It \&.Brq Ta Yes Ta Yes
426 .Ss Block partial-explicit
427 Each of these contains at least a body and, in limited circumstances, a
429 .Pq So \&Fo Sc , So \&Eo Sc
433 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
434 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
435 .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
436 .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
437 .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
438 .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
439 .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
440 .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
441 .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
442 .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
443 .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
444 .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
445 .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
446 .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
447 .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
448 .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
449 .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
450 .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
451 .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
452 .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
453 .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
454 .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
455 .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
456 .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
460 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
461 .It Em Macro Ta Em Callable Ta Em Parsable
462 .It \&.Dd Ta \& Ta \&
463 .It \&.Dt Ta \& Ta \&
464 .It \&.Os Ta \& Ta \&
465 .It \&.Pp Ta \& Ta \&
466 .It \&.D1 Ta \& Ta \&
467 .It \&.Dl Ta \& Ta Yes
468 .It \&.Ad Ta Yes Ta Yes
469 .It \&.An Ta \& Ta Yes
470 .It \&.Ar Ta Yes Ta Yes
471 .It \&.Cd Ta Yes Ta \&
472 .It \&.Cm Ta Yes Ta Yes
473 .It \&.Dv Ta Yes Ta Yes
474 .It \&.Er Ta Yes Ta Yes
475 .It \&.Ev Ta Yes Ta Yes
476 .It \&.Ex Ta \& Ta \&
477 .It \&.Fa Ta Yes Ta Yes
478 .It \&.Fd Ta \& Ta \&
479 .It \&.Fl Ta Yes Ta Yes
480 .It \&.Fn Ta Yes Ta Yes
481 .It \&.Ft Ta \& Ta \&
482 .It \&.Ic Ta Yes Ta Yes
483 .It \&.In Ta \& Ta \&
484 .It \&.Li Ta Yes Ta Yes
485 .It \&.Nd Ta \& Ta \&
486 .It \&.Nm Ta Yes Ta Yes
487 .It \&.Ot Ta \& Ta \&
488 .It \&.Pa Ta Yes Ta Yes
489 .It \&.Rv Ta \& Ta \&
490 .It \&.St Ta Yes Ta \&
491 .It \&.Va Ta Yes Ta Yes
492 .It \&.Vt Ta Yes Ta Yes
493 .It \&.Xr Ta Yes Ta Yes
494 .It \&.%A Ta \& Ta \&
495 .It \&.%B Ta \& Ta \&
496 .It \&.%C Ta \& Ta \&
497 .It \&.%D Ta \& Ta \&
498 .It \&.%I Ta \& Ta \&
499 .It \&.%J Ta \& Ta \&
500 .It \&.%N Ta \& Ta \&
501 .It \&.%O Ta \& Ta \&
502 .It \&.%P Ta \& Ta \&
503 .It \&.%R Ta \& Ta \&
504 .It \&.%T Ta \& Ta \&
505 .It \&.%V Ta \& Ta \&
506 .It \&.At Ta Yes Ta Yes
507 .It \&.Bsx Ta Yes Ta Yes
508 .It \&.Bx Ta Yes Ta Yes
509 .It \&.Db Ta \& Ta \&
510 .It \&.Em Ta Yes Ta Yes
511 .It \&.Fx Ta Yes Ta Yes
512 .It \&.Ms Ta \& Ta Yes
513 .It \&.No Ta Yes Ta Yes
514 .It \&.Ns Ta Yes Ta Yes
515 .It \&.Nx Ta Yes Ta Yes
516 .It \&.Ox Ta Yes Ta Yes
517 .It \&.Pf Ta \& Ta Yes
518 .It \&.Ql Ta Yes Ta Yes
519 .It \&.Re Ta \& Ta \&
520 .It \&.Rs Ta \& Ta \&
521 .It \&.Sm Ta \& Ta \&
522 .It \&.Sx Ta Yes Ta Yes
523 .It \&.Sy Ta Yes Ta Yes
524 .It \&.Tn Ta Yes Ta Yes
525 .It \&.Ux Ta Yes Ta Yes
526 .It \&.Bk Ta \& Ta \&
527 .It \&.Ek Ta \& Ta \&
528 .It \&.Bt Ta \& Ta \&
529 .It \&.Hf Ta \& Ta \&
530 .It \&.Fr Ta \& Ta \&
531 .It \&.Ud Ta \& Ta \&
532 .It \&.Lb Ta \& Ta \&
533 .It \&.Ap Ta Yes Ta Yes
534 .It \&.Lp Ta \& Ta \&
535 .It \&.Lk Ta \& Ta Yes
536 .It \&.Mt Ta \& Ta Yes
git.ckatri.com / mandoc.git / blob