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

Diff for /mandoc/roff.7 between version 1.15 and 1.41

version 1.15, 2010/12/06 16:37:32 version 1.41, 2013/07/13 19:41:16
Line 1 
Line 1 
 .\"     $Id$  .\"     $Id$
 .\"  .\"
 .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>  .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>  .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@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 above  .\" purpose with or without fee is hereby granted, provided that the above
Line 20 
Line 20 
 .Os  .Os
 .Sh NAME  .Sh NAME
 .Nm roff  .Nm roff
 .Nd roff language reference  .Nd roff language reference for mandoc
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm roff  .Nm roff
 language is a general-purpose text-formatting language.  The purpose of  language is a general purpose text formatting language.
 this document is to consistently describe those language constructs  Since traditional implementations of the
 accepted by the  .Xr mdoc 7
 .Xr mandoc 1  and
 utility.  It is a work in progress.  .Xr man 7
 .Pp  manual formatting languages are based on it,
 An  many real-world manuals use small numbers of
 .Nm  .Nm
 document follows simple rules:  lines beginning with the control  requests intermixed with their
 characters  .Xr mdoc 7
 .Sq \.  
 or  or
 .Sq \(aq  .Xr man 7
   code.
   To properly format such manuals, the
   .Xr mandoc 1
   utility supports a tiny subset of
   .Nm
   requests.
   Only these requests supported by
   .Xr mandoc 1
   are documented in the present manual,
   together with the basic language syntax shared by
   .Nm ,
   .Xr mdoc 7 ,
   and
   .Xr man 7 .
   For complete
   .Nm
   manuals, consult the
   .Sx SEE ALSO
   section.
   .Pp
   Input lines beginning with the control character
   .Sq \&.
 are parsed for requests and macros.  are parsed for requests and macros.
 Other lines are interpreted within the scope of  Such lines are called
 prior macros:  .Dq request lines
 .Bd -literal -offset indent  or
 \&.xx Macro lines change control state.  .Dq macro lines ,
 Other lines are interpreted within the current state.  respectively.
 .Ed  Requests change the processing state and manipulate the formatting;
   some macros also define the document structure and produce formatted
   output.
   The single quote
   .Pq Qq \(aq
   is accepted as an alternative control character,
   treated by
   .Xr mandoc 1
   just like
   .Ql \&.
   .Pp
   Lines not beginning with control characters are called
   .Dq text lines .
   They provide free-form text to be printed; the formatting of the text
   depends on the respective processing context.
 .Sh LANGUAGE SYNTAX  .Sh LANGUAGE SYNTAX
 .Nm  .Nm
 documents may contain only graphable 7-bit ASCII characters, the space  documents may contain only graphable 7-bit ASCII characters, the space
 character, and, in certain circumstances, the tab character.  All  character, and, in certain circumstances, the tab character.
 manuals must have  The backslash character
 .Ux  .Sq \e
 line terminators.  indicates the start of an escape sequence for
 .Sh MACRO SYNTAX  .Sx Comments ,
 Requests and macros are arbitrary in length and begin with a control  .Sx Special Characters ,
 character,  .Sx Predefined Strings ,
 .Sq \.  and
   user-defined strings defined using the
   .Sx ds
   request.
   .Ss Comments
   Text following an escaped double-quote
   .Sq \e\(dq ,
   whether in a request, macro, or text line, is ignored to the end of the line.
   A request line beginning with a control character and comment escape
   .Sq \&.\e\(dq
   is also ignored.
   Furthermore, request lines with only a control character and optional
   trailing whitespace are stripped from input.
   .Pp
   Examples:
   .Bd -literal -offset indent -compact
   \&.\e\(dq This is a comment line.
   \&.\e\(dq The next line is ignored:
   \&.
   \&.Sh EXAMPLES \e\(dq This is a comment, too.
   \&example text \e\(dq And so is this.
   .Ed
   .Ss Special Characters
   Special characters are used to encode special glyphs and are rendered
   differently across output media.
   They may occur in request, macro, and text 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.
   .Pp
   Examples:
   .Bl -tag -width Ds -offset indent -compact
   .It Li \e(em
   Two-letter em dash escape.
   .It Li \ee
   One-letter backslash escape.
   .El
   .Pp
   See
   .Xr mandoc_char 7
   for a complete list.
   .Ss Text Decoration
   Terms may be text-decorated using the
   .Sq \ef
   escape followed by an indicator: B (bold), I (italic), R (regular), or P
   (revert to previous mode).
   A numerical representation 3, 2, or 1 (bold, italic, and regular,
   respectively) may be used instead.
   The indicator or numerical representative may be preceded by C
   (constant-width), which is ignored.
   .Pp
   Examples:
   .Bl -tag -width Ds -offset indent -compact
   .It Li \efBbold\efR
   Write in bold, then switch to regular font mode.
   .It Li \efIitalic\efP
   Write in italic, then return to previous font mode.
   .El
   .Pp
   Text decoration is
   .Em not
   recommended for
   .Xr mdoc 7 ,
   which encourages semantic annotation.
   .Ss Predefined Strings
   Predefined strings, like
   .Sx Special Characters ,
   mark special output glyphs.
   Predefined strings are escaped with the slash-asterisk,
   .Sq \e* :
   single-character
   .Sq \e*X ,
   two-character
   .Sq \e*(XX ,
   and N-character
   .Sq \e*[N] .
   .Pp
   Examples:
   .Bl -tag -width Ds -offset indent -compact
   .It Li \e*(Am
   Two-letter ampersand predefined string.
   .It Li \e*q
   One-letter double-quote predefined string.
   .El
   .Pp
   Predefined strings are not recommended for use,
   as they differ across implementations.
   Those supported by
   .Xr mandoc 1
   are listed in
   .Xr mandoc_char 7 .
   Manuals using these predefined strings are almost certainly not portable.
   .Ss Whitespace
   Whitespace consists of the space character.
   In text lines, whitespace is preserved within a line.
   In request and macro lines, whitespace delimits arguments and is discarded.
   .Pp
   Unescaped trailing spaces are stripped from text line input unless in a
   literal context.
   In general, trailing whitespace on any input line is discouraged for
   reasons of portability.
   In the rare case that a blank character is needed at the end of an
   input line, it may be forced by
   .Sq \e\ \e& .
   .Pp
   Literal space characters can be produced in the output
   using escape sequences.
   In macro lines, they can also be included in arguments using quotation; see
   .Sx MACRO SYNTAX
   for details.
   .Pp
   Blank text lines, which may include whitespace, are only permitted
   within literal contexts.
   If the first character of a text line is a space, that line is printed
   with a leading newline.
   .Ss Scaling Widths
   Many requests and macros support scaled widths for their arguments.
   The syntax for a scaled width is
   .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
   where a decimal must be preceded or followed by at least one digit.
   Negative numbers, while accepted, are truncated to zero.
   .Pp
   The following scaling units are accepted:
   .Pp
   .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
   .Pp
   Using anything other than
   .Sq m ,
   .Sq n ,
   .Sq u ,
 or  or
 .Sq \(aq ,  .Sq v
 at the beginning of the line.  is necessarily non-portable across output media.
 An arbitrary amount of whitespace may sit between the control character  See
 and the request or macro name.  .Sx COMPATIBILITY .
 Thus, the following are equivalent:  .Pp
   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.
   .Pp
   Examples:
   .Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
   .It Li \&.Bl -tag -width 2i
   two-inch tagged list indentation in
   .Xr mdoc 7
   .It Li \&.HP 2i
   two-inch tagged list indentation in
   .Xr man 7
   .It Li \&.sp 2v
   two vertical spaces
   .El
   .Ss Sentence Spacing
   Each sentence should terminate at the end of an input line.
   By doing this, a formatter will be able to apply the proper amount of
   spacing after the end of sentence (unescaped) period, exclamation mark,
   or question mark followed by zero or more non-sentence closing
   delimiters
   .Po
   .Sq \&) ,
   .Sq \&] ,
   .Sq \&' ,
   .Sq \&"
   .Pc .
   .Pp
   The proper spacing is also intelligently preserved if a sentence ends at
   the boundary of a macro line.
   .Pp
   Examples:
   .Bd -literal -offset indent -compact
   Do not end sentences mid-line like this.  Instead,
   end a sentence like this.
   A macro would end like this:
   \&.Xr mandoc 1 \&.
   .Ed
   .Sh REQUEST SYNTAX
   A request or macro line consists of:
   .Pp
   .Bl -enum -compact
   .It
   the control character
   .Sq \&.
   or
   .Sq \(aq
   at the beginning of the line,
   .It
   optionally an arbitrary amount of whitespace,
   .It
   the name of the request or the macro, which is one word of arbitrary
   length, terminated by whitespace,
   .It
   and zero or more arguments delimited by whitespace.
   .El
   .Pp
   Thus, the following request lines are all equivalent:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.if  \&.ig end
 \&.\ \ \ \&if  \&.ig    end
   \&.   ig end
 .Ed  .Ed
   .Sh MACRO SYNTAX
   Macros are provided by the
   .Xr mdoc 7
   and
   .Xr man 7
   languages and can be defined by the
   .Sx \&de
   request.
   When called, they follow the same syntax as requests, except that
   macro arguments may optionally be quoted by enclosing them
   in double quote characters
   .Pq Sq \(dq .
   Quoted text, even if it contains whitespace or would cause
   a macro invocation when unquoted, is always considered literal text.
   Inside quoted text, pairs of double quote characters
   .Pq Sq Qq
   resolve to single double quote characters.
   .Pp
   To be recognised as the beginning of a quoted argument, the opening
   quote character must be preceded by a space character.
   A quoted argument extends to the next double quote character that is not
   part of a pair, or to the end of the input line, whichever comes earlier.
   Leaving out the terminating double quote character at the end of the line
   is discouraged.
   For clarity, if more arguments follow on the same input line,
   it is recommended to follow the terminating double quote character
   by a space character; in case the next character after the terminating
   double quote character is anything else, it is regarded as the beginning
   of the next, unquoted argument.
   .Pp
   Both in quoted and unquoted arguments, pairs of backslashes
   .Pq Sq \e\e
   resolve to single backslashes.
   In unquoted arguments, space characters can alternatively be included
   by preceding them with a backslash
   .Pq Sq \e\~ ,
   but quoting is usually better for clarity.
   .Pp
   Examples:
   .Bl -tag -width Ds -offset indent -compact
   .It Li .Fn strlen \(dqconst char *s\(dq
   Group arguments
   .Qq const char *s
   into one function argument.
   If unspecified,
   .Qq const ,
   .Qq char ,
   and
   .Qq *s
   would be considered separate arguments.
   .It Li .Op \(dqFl a\(dq
   Consider
   .Qq \&Fl a
   as literal text instead of a flag macro.
   .El
 .Sh REQUEST REFERENCE  .Sh REQUEST REFERENCE
 This section is a canonical reference of all requests recognized by the  The
 .Xr mandoc 1  .Xr mandoc 1
 .Nm  .Nm
 parser.  parser recognises the following requests.
 The  Note that the
 .Nm  .Nm
 language defines many more requests and macros not implemented in  language defines many more requests not implemented in
 .Xr mandoc 1 .  .Xr mandoc 1 .
 .Ss \&ad  .Ss \&ad
 Set line adjustment mode.  Set line adjustment mode.
 This line-scoped request is intended to have one argument to select  This line-scoped request is intended to have one argument to select
 normal, left, right, or center adjustment for subsequent text.  normal, left, right, or centre adjustment for subsequent text.
 Currently, it is ignored including its arguments,  Currently, it is ignored including its arguments,
 and the number of arguments is not checked.  and the number of arguments is not checked.
 .Ss \&am  .Ss \&am
Line 102  The syntax of this request is the same as that of
Line 417  The syntax of this request is the same as that of
 It is currently ignored by  It is currently ignored by
 .Xr mandoc 1 ,  .Xr mandoc 1 ,
 as are its children.  as are its children.
   .Ss \&cc
   Changes the control character.
   Its syntax is as follows:
   .Bd -literal -offset indent
   .Pf . Cm \&cc Op Ar c
   .Ed
   .Pp
   If
   .Ar c
   is not specified, the control character is reset to
   .Sq \&. .
   Trailing characters are ignored.
 .Ss \&de  .Ss \&de
 Define a user-defined  Define a
 .Nm  .Nm
 macro.  macro.
 Its syntax can be either  Its syntax can be either
Line 149  request or
Line 476  request or
 .Nm  .Nm
 macro, but not as a high-level macro.  macro, but not as a high-level macro.
 .Pp  .Pp
 A user-defined macro can be invoked later using the syntax  The macro can be invoked later using the syntax
 .Pp  .Pp
 .D1 Pf . Ar name Op Ar argument Op Ar argument ...  .D1 Pf . Ar name Op Ar argument Op Ar argument ...
 .Pp  .Pp
 Arguments are separated by blank characters and can be quoted  Regarding argument parsing, see
 using double-quotes  .Sx MACRO SYNTAX
 .Pq Sq \(dq  above.
 to allow inclusion of blank characters into arguments.  
 To include the double-quote character into a quoted argument,  
 escape it from ending the argument by doubling it.  
 .Pp  .Pp
 The line invoking the user-defined macro will be replaced  The line invoking the macro will be replaced
 in the input stream by the  in the input stream by the
 .Ar macro definition ,  .Ar macro definition ,
 replacing all occurrences of  replacing all occurrences of
 .No \e\e$ Ns Ar N ,  .No \e\e$ Ns Ar N ,
 where  where
 .Ar N  .Ar N
 is a digit, by the  is a digit, by the
 .Ar N Ns th Ar argument .  .Ar N Ns th Ar argument .
Line 183  produces
Line 507  produces
 .Pp  .Pp
 in the input stream, and thus in the output: \fI\^XtFree\^\fP.  in the input stream, and thus in the output: \fI\^XtFree\^\fP.
 .Pp  .Pp
 Since user-defined macros and strings share a common string table,  Since macros and user-defined strings share a common string table,
 defining a macro  defining a macro
 .Ar name  .Ar name
 clobbers the user-defined string  clobbers the user-defined string
Line 196  string interpolation syntax described below
Line 520  string interpolation syntax described below
 .Sx ds ,  .Sx ds ,
 but this is rarely useful because every macro definition contains at least  but this is rarely useful because every macro definition contains at least
 one explicit newline character.  one explicit newline character.
   .Pp
   In order to prevent endless recursion, both groff and
   .Xr mandoc 1
   limit the stack depth for expanding macros and strings
   to a large, but finite number.
   Do not rely on the exact value of this limit.
 .Ss \&dei  .Ss \&dei
 Define a user-defined  Define a
 .Nm  .Nm
 macro, specifying the macro name indirectly.  macro, specifying the macro name indirectly.
 The syntax of this macro is the same as that of  The syntax of this request is the same as that of
 .Sx \&de .  .Sx \&de .
 It is currently ignored by  It is currently ignored by
 .Xr mandoc 1 ,  .Xr mandoc 1 ,
 as are its children.  as are its children.
 .Ss \&de1  .Ss \&de1
 Define a user-defined  Define a
 .Nm  .Nm
 macro that will be executed with  macro that will be executed with
 .Nm  .Nm
Line 218  Since
Line 548  Since
 .Xr mandoc 1  .Xr mandoc 1
 does not implement  does not implement
 .Nm  .Nm
 compatibility mode at all, it handles this macro as an alias for  compatibility mode at all, it handles this request as an alias for
 .Sx \&de .  .Sx \&de .
 .Ss \&ds  .Ss \&ds
 Define a user-defined string.  Define a user-defined string.
Line 248  for a
Line 578  for a
 of arbitrary length, or \e*(NN or \e*N if the length of  of arbitrary length, or \e*(NN or \e*N if the length of
 .Ar name  .Ar name
 is two or one characters, respectively.  is two or one characters, respectively.
   Interpolation can be prevented by escaping the leading backslash;
   that is, an asterisk preceded by an even number of backslashes
   does not trigger string interpolation.
 .Pp  .Pp
 Since user-defined strings and macros share a common string table,  Since user-defined strings and macros share a common string table,
 defining a string  defining a string
 .Ar name  .Ar name
 clobbers the user-defined macro  clobbers the macro
 .Ar name ,  .Ar name ,
 and the  and the
 .Ar name  .Ar name
Line 286  If no stack entries are present (e.g., due to no prior
Line 619  If no stack entries are present (e.g., due to no prior
 .Sx \&ie  .Sx \&ie
 calls)  calls)
 then false is assumed.  then false is assumed.
 The syntax of this macro is similar to  The syntax of this request is similar to
 .Sx \&if  .Sx \&if
 except that the conditional is missing.  except that the conditional is missing.
   .Ss \&EN
   End an equation block.
   See
   .Sx \&EQ .
   .Ss \&EQ
   Begin an equation block.
   See
   .Xr eqn 7
   for a description of the equation language.
 .Ss \&hy  .Ss \&hy
 Set automatic hyphenation mode.  Set automatic hyphenation mode.
 This line-scoped request is currently ignored.  This line-scoped request is currently ignored.
Line 307  Begins a conditional.
Line 649  Begins a conditional.
 Right now, the conditional evaluates to true  Right now, the conditional evaluates to true
 if and only if it starts with the letter  if and only if it starts with the letter
 .Sy n ,  .Sy n ,
 indicating processing in  indicating processing in nroff style as opposed to troff style.
 .Xr nroff 1  
 style as opposed to  
 .Xr troff 1  
 style.  
 If a conditional is false, its children are not processed, but are  If a conditional is false, its children are not processed, but are
 syntactically interpreted to preserve the integrity of the input  syntactically interpreted to preserve the integrity of the input
 document.  document.
 Thus,  Thus,
 .Pp  .Pp
 .D1 \&.if t \e .ig  .D1 \&.if t .ig
 .Pp  .Pp
 will discard the  will discard the
 .Sq \&.ig ,  .Sq \&.ig ,
 which may lead to interesting results, but  which may lead to interesting results, but
 .Pp  .Pp
 .D1 \&.if t \e .if t \e{\e  .D1 \&.if t .if t \e{\e
 .Pp  .Pp
 will continue to syntactically interpret to the block close of the final  will continue to syntactically interpret to the block close of the final
 conditional.  conditional.
 Sub-conditionals, in this case, obviously inherit the truth value of  Sub-conditionals, in this case, obviously inherit the truth value of
 the parent.  the parent.
 This macro has the following syntax:  This request has the following syntax:
 .Pp  .Bd -literal -offset indent
 .Bd -literal -offset indent -compact  
 \&.if COND \e{\e  \&.if COND \e{\e
 BODY...  BODY...
 \&.\e}  \&.\e}
 .Ed  .Ed
 .Bd -literal -offset indent -compact  .Bd -literal -offset indent
 \&.if COND \e{ BODY  \&.if COND \e{ BODY
 BODY... \e}  BODY... \e}
 .Ed  .Ed
 .Bd -literal -offset indent -compact  .Bd -literal -offset indent
 \&.if COND \e{ BODY  \&.if COND \e{ BODY
 BODY...  BODY...
 \&.\e}  \&.\e}
 .Ed  .Ed
 .Bd -literal -offset indent -compact  .Bd -literal -offset indent
 \&.if COND \e  \&.if COND \e
 BODY  BODY
 .Ed  .Ed
Line 366  evaluate as false.
Line 703  evaluate as false.
 .Pp  .Pp
 If the BODY section is begun by an escaped brace  If the BODY section is begun by an escaped brace
 .Sq \e{ ,  .Sq \e{ ,
 scope continues until a closing-brace macro  scope continues until a closing-brace escape sequence
 .Sq \.\e} .  .Sq \.\e} .
 If the BODY is not enclosed in braces, scope continues until the next  If the BODY is not enclosed in braces, scope continues until
 macro or word.  the end of the line.
 If the COND is followed by a BODY on the same line, whether after a  If the COND is followed by a BODY on the same line, whether after a
 brace or not, then macros  brace or not, then requests and macros
 .Em must  .Em must
 begin with a control character.  begin with a control character.
 It is generally more intuitive, in this case, to write  It is generally more intuitive, in this case, to write
Line 382  bar
Line 719  bar
 \&.\e}  \&.\e}
 .Ed  .Ed
 .Pp  .Pp
 than having the macro follow as  than having the request or macro follow as
 .Pp  .Pp
 .D1 \&.if COND \e{ .foo  .D1 \&.if COND \e{ .foo
 .Pp  .Pp
 The scope of a conditional is always parsed, but only executed if the  The scope of a conditional is always parsed, but only executed if the
 conditional evaluates to true.  conditional evaluates to true.
 .Pp  .Pp
 Note that text subsequent a  Note that the
 .Sq \&.\e}  
 macro is discarded.  
 Furthermore, if an explicit closing sequence  
 .Sq \e}  .Sq \e}
 is specified in a free-form line, the entire line is accepted within the  is converted into a zero-width escape sequence if not passed as a
 scope of the prior macro, not only the text preceding the close, with the  standalone macro
   .Sq \&.\e} .
   For example,
   .Pp
   .D1 \&.Fl a \e} b
   .Pp
   will result in
 .Sq \e}  .Sq \e}
 collapsing into a zero-width space.  being considered an argument of the
   .Sq \&Fl
   macro.
 .Ss \&ig  .Ss \&ig
 Ignore input.  Ignore input.
 Its syntax can be either  Its syntax can be either
Line 416  or
Line 758  or
 .Pp  .Pp
 In the first case, input is ignored until a  In the first case, input is ignored until a
 .Sq \&..  .Sq \&..
 macro is encountered on its own line.  request is encountered on its own line.
 In the second case, input is ignored until the specified  In the second case, input is ignored until the specified
 .Sq Pf . Ar end  .Sq Pf . Ar end
 macro is encountered.  macro is encountered.
Line 441  Otherwise, it only terminates the
Line 783  Otherwise, it only terminates the
 .Ar ignored text ,  .Ar ignored text ,
 and arguments following it or the  and arguments following it or the
 .Sq \&..  .Sq \&..
 macro are discarded.  request are discarded.
 .Ss \&ne  .Ss \&ne
 Declare the need for the specified minimum vertical space  Declare the need for the specified minimum vertical space
 before the next trap or the bottom of the page.  before the next trap or the bottom of the page.
Line 466  Its syntax is as follows:
Line 808  Its syntax is as follows:
 The  The
 .Ar value  .Ar value
 may, at the moment, only be an integer.  may, at the moment, only be an integer.
 The  
 .Ar name  
 is defined up to the next whitespace.  
 So far, only the following register  So far, only the following register
 .Ar name  .Ar name
 is recognised:  is recognised:
Line 476  is recognised:
Line 815  is recognised:
 .It Cm nS  .It Cm nS
 If set to a positive integer value, certain  If set to a positive integer value, certain
 .Xr mdoc 7  .Xr mdoc 7
 macros will behave as if they were defined in the  macros will behave in the same way as in the
 .Em SYNOPSIS  .Em SYNOPSIS
 section.  section.
 Otherwise, this behaviour is unset (even if called within the  If set to 0, these macros will behave in the same way as outside the
 .Em SYNOPSIS  .Em SYNOPSIS
 section itself).  section, even when called within the
 Note that invoking a new  .Em SYNOPSIS
   section itself.
   Note that starting a new
 .Xr mdoc 7  .Xr mdoc 7
 section will unset this value.  section with the
   .Cm \&Sh
   macro will reset this register.
 .El  .El
   .Ss \&ns
   Turn on no-space mode.
   This line-scoped request is intended to take no arguments.
   Currently, it is ignored including its arguments,
   and the number of arguments is not checked.
   .Ss \&ps
   Change point size.
   This line-scoped request is intended to take one numerical argument.
   Currently, it is ignored including its arguments,
   and the number of arguments is not checked.
 .Ss \&so  .Ss \&so
 Include a source file.  Include a source file.
 Its syntax is as follows:  Its syntax is as follows:
Line 497  The
Line 850  The
 will be read and its contents processed as input in place of the  will be read and its contents processed as input in place of the
 .Sq \&.so  .Sq \&.so
 request line.  request line.
 To avoid inadvertant inclusion of unrelated files,  To avoid inadvertent inclusion of unrelated files,
 .Xr mandoc 1  .Xr mandoc 1
 only accepts relative paths not containing the strings  only accepts relative paths not containing the strings
 .Qq ../  .Qq ../
 and  and
 .Qq /.. .  .Qq /.. .
   .Pp
   This request requires
   .Xr man 1
   to change to the right directory before calling
   .Xr mandoc 1 ,
   per convention to the root of the manual tree.
   Typical usage looks like:
   .Pp
   .Dl \&.so man3/Xcursor.3
   .Pp
   As the whole concept is rather fragile, the use of
   .Sx \&so
   is discouraged.
   Use
   .Xr ln 1
   instead.
   .Ss \&ta
   Set tab stops.
   This line-scoped request can take an arbitrary number of arguments.
   Currently, it is ignored including its arguments.
 .Ss \&tr  .Ss \&tr
 Output character translation.  Output character translation.
 This macro is intended to have one argument,  Its syntax is as follows:
 consisting of an even number of characters.  .Pp
 Currently, it is ignored including its arguments,  .D1 Pf \. Cm \&tr Ar [ab]+
 and the number of arguments is not checked.  .Pp
   Pairs of
   .Ar ab
   characters are replaced
   .Ar ( a
   for
   .Ar b ) .
   Replacement (or origin) characters may also be character escapes; thus,
   .Pp
   .Dl tr \e(xx\e(yy
   .Pp
   replaces all invocations of \e(xx with \e(yy.
   .Ss \&T&
   Re-start a table layout, retaining the options of the prior table
   invocation.
   See
   .Sx \&TS .
   .Ss \&TE
   End a table context.
   See
   .Sx \&TS .
   .Ss \&TS
   Begin a table, which formats input in aligned rows and columns.
   See
   .Xr tbl 7
   for a description of the tbl language.
 .Sh COMPATIBILITY  .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other other  This section documents compatibility between mandoc and other
 troff implementations, at this time limited to GNU troff  .Nm
   implementations, at this time limited to GNU troff
 .Pq Qq groff .  .Pq Qq groff .
 The term  The term
 .Qq historic groff  .Qq historic groff
 refers to groff versions before the  refers to groff version 1.15.
 .Pa doc.tmac  
 file re-write  
 .Pq somewhere between 1.15 and 1.19 .  
 .Pp  .Pp
 .Bl -dash -compact  .Bl -dash -compact
 .It  .It
   In mandoc, the
   .Sx \&EQ ,
   .Sx \&TE ,
   .Sx \&TS ,
   and
   .Sx \&T& ,
   macros are considered regular macros.
   In all other
   .Nm
   implementations, these are special macros that must be specified without
   spacing between the control character (which must be a period) and the
   macro name.
   .It
 The  The
 .Cm nS  .Cm nS
 request to  register is only compatible with OpenBSD's groff-1.15.
 .Sx \&nr  
 is only compatible with OpenBSD's groff.  
 .It  .It
 Historic groff did not accept white-space buffering the custom END tag  Historic groff did not accept white-space before a custom
 for the  .Ar end
   macro for the
 .Sx \&ig  .Sx \&ig
 macro.  request.
 .It  .It
 The  The
 .Sx \&if  .Sx \&if
 and family would print funny white-spaces with historic groff when  and family would print funny white-spaces with historic groff when
 depending on next-line syntax.  using the next-line syntax.
 .El  .El
   .Sh SEE ALSO
   .Xr mandoc 1 ,
   .Xr eqn 7 ,
   .Xr man 7 ,
   .Xr mandoc_char 7 ,
   .Xr mdoc 7 ,
   .Xr tbl 7
   .Rs
   .%A Joseph F. Ossanna
   .%A Brian W. Kernighan
   .%I AT&T Bell Laboratories
   .%T Troff User's Manual
   .%R Computing Science Technical Report
   .%N 54
   .%C Murray Hill, New Jersey
   .%D 1976 and 1992
   .%U http://www.kohala.com/start/troff/cstr54.ps
   .Re
   .Rs
   .%A Joseph F. Ossanna
   .%A Brian W. Kernighan
   .%A Gunnar Ritter
   .%T Heirloom Documentation Tools Nroff/Troff User's Manual
   .%D September 17, 2007
   .%U http://heirloom.sourceforge.net/doctools/troff.pdf
   .Re
   .Sh HISTORY
   The RUNOFF typesetting system, whose input forms the basis for
   .Nm ,
   was written in MAD and FAP for the CTSS operating system by Jerome E.
   Saltzer in 1964.
   Doug McIlroy rewrote it in BCPL in 1969, renaming it
   .Nm .
   Dennis M. Ritchie rewrote McIlroy's
   .Nm
   in PDP-11 assembly for
   .At v1 ,
   Joseph F. Ossanna improved roff and renamed it nroff
   for
   .At v2 ,
   then ported nroff to C as troff, which Brian W. Kernighan released with
   .At v7 .
   In 1989, James Clarke re-implemented troff in C++, naming it groff.
 .Sh AUTHORS  .Sh AUTHORS
 .An -nosplit  .An -nosplit
 This partial  This
 .Nm  .Nm
 reference was written by  reference was written by
 .An Kristaps Dzonsons Aq kristaps@bsd.lv  .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 and  and
 .An Ingo Schwarze Aq schwarze@openbsd.org .  .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
Legend:
Removed from v.1.15  
changed lines
  Added in v.1.41
CVSweb