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

Diff for /mandoc/man.7 between version 1.105 and 1.110

version 1.105, 2011/08/18 08:58:43 version 1.110, 2011/09/20 22:46:47
Line 39  language, instead.
Line 39  language, instead.
 .Pp  .Pp
 A  A
 .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.  are parsed for macros.
 Other lines are interpreted within the scope of  Lines not beginning with the control character are
 prior macros:  interpreted within the scope of prior macros:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.SH Macro lines change control state.  \&.SH Macro lines change control state.
 Other lines are interpreted within the current state.  Text lines are interpreted within the current state.
 .Ed  .Ed
 .Sh LANGUAGE SYNTAX  .Sh LANGUAGE SYNTAX
 .Nm  .Nm
Line 62  and
Line 62  and
 .Sx Special Characters .  .Sx Special Characters .
 .Ss Comments  .Ss Comments
 Text following an escaped double-quote  Text following an escaped double-quote
 .Sq \e\*q ,  .Sq \e\(dq ,
 whether in a macro or text line, is ignored to the end of  whether in a macro or text line, is ignored to the end of
 line.  line.
 A macro line beginning with a control character and comment escape  A macro line beginning with a control character and comment escape
 .Sq \&.\e\*q  .Sq \&.\e\(dq
 is also ignored.  is also ignored.
 Furthermore,  Furthermore,
 macro lines with only a control character and optional trailing  macro lines with only a control character and optional trailing
Line 75  stripped from input.
Line 75  stripped from input.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent -compact  .Bd -literal -offset indent -compact
 \&.\e\*q This is a comment line.  \&.\e\(dq This is a comment line.
 \&.\e\*q The next line is ignored:  \&.\e\(dq The next line is ignored:
 \&.  \&.
 \&.Em Emphasis \e\*q This is also a comment.  \&.Em Emphasis \e\(dq This is also a comment.
 .Ed  .Ed
 .Ss Special Characters  .Ss Special Characters
 Special characters are used to encode special glyphs and are rendered  Special characters are used to encode special glyphs and are rendered
Line 96  or a single one character sequence.
Line 96  or a single one character sequence.
 .Pp  .Pp
 Examples:  Examples:
 .Bl -tag -width Ds -offset indent -compact  .Bl -tag -width Ds -offset indent -compact
 .It \e(em  .It Li \e(em
 em dash  Two-letter em dash escape.
 .It \ee  .It Li \ee
 backslash  One-letter backslash escape.
 .El  .El
 .Pp  .Pp
 See  See
Line 109  for a complete list.
Line 109  for a complete list.
 Terms may be text-decorated using the  Terms may be text-decorated using the
 .Sq \ef  .Sq \ef
 escape followed by an indicator: B (bold), I (italic), R (regular), or P  escape followed by an indicator: B (bold), I (italic), R (regular), or P
 (revert to previous mode):  (revert to previous mode).
 A numerical representation 3, 2, or 1 (bold, italic, and regular,  A numerical representation 3, 2, or 1 (bold, italic, and regular,
 respectively) may be used instead.  respectively) may be used instead.
 A text decoration is only valid, if specified in free-form text, until  A text decoration is only valid, if specified in free-form text, until
Line 125  attribute is forgotten when entering or exiting a macr
Line 125  attribute is forgotten when entering or exiting a macr
 .Pp  .Pp
 Examples:  Examples:
 .Bl -tag -width Ds -offset indent -compact  .Bl -tag -width Ds -offset indent -compact
 .It \efBbold\efR  .It Li \efBbold\efR
 write in bold, then switch to regular  Write in bold, then switch to regular font mode.
 .It \efIitalic\efP  .It Li \efIitalic\efP
 write in italic, then return to previous  Write in italic, then return to previous font mode.
 .El  .El
 .Ss Predefined Strings  .Ss Predefined Strings
 Predefined strings, like  Predefined strings, like
Line 145  and N-character
Line 145  and N-character
 .Pp  .Pp
 Examples:  Examples:
 .Bl -tag -width Ds -offset indent -compact  .Bl -tag -width Ds -offset indent -compact
 .It \e*(Am  .It Li \e*(Am
 ampersand  Two-letter ampersand predefined string.
 .It \e*(Ba  .It Li \e*q
 vertical bar  One-letter double-quote predefined string.
 .El  .El
 .Pp  .Pp
 These strings are set using  These strings are set using
Line 170  In the rare case that a blank character is needed at t
Line 170  In the rare case that a blank character is needed at t
 input line, it may be forced by  input line, it may be forced by
 .Sq \e\ \e& .  .Sq \e\ \e& .
 .Pp  .Pp
   In general, space characters can be rendered as literal
   characters by using non-breaking space escapes or
   .Sx Quotation .
 If the first character of a text line is a space, that line is printed  If the first character of a text line is a space, that line is printed
 with a leading newline.  with a leading newline.
 .Ss Quotation  .Ss Quotation
 Macro arguments may be quoted with double-quotes; in this case,  Macro arguments may be quoted with double-quotes to so that the
 whitespace within the quotes is retained as part of the argument.  enclosed text is one literal term.
   Quoted text, even if whitespace or if it would cause a macro invocation
   when unquoted, is considered literal text.
 .Pp  .Pp
 A quoted argument begins with a double-quote preceded by whitespace.  A quoted argument begins with a double-quote preceded by whitespace.
 The next double-quote not pairwise adjacent to another double-quote  The next double-quote not pairwise adjacent to another double-quote
 terminates the literal, regardless of surrounding whitespace.  terminates the literal, regardless of surrounding whitespace.
 .Pp  .Pp
 In unquoted arguments, space characters can alternatively be included  Examples:
 by preceding them with a backslash  .Bl -tag -width Ds -offset indent -compact
 .Pq Sq \e\~ ,  .It Li .BR a \(dqb c\(dq d
 but quoting is usually better for clarity.  Group arguments
 .Pp  .Qq b c
 Note that any quoted text, even if it would cause a macro invocation  into one un-bolded argument.
 when unquoted, is considered literal text.  If unspecified,
 .Pp  .Qq a
 In text lines, quotes are regarded as opaque text.  and
   .Qq c
   will be in bold,
   .Qq b
   and
   .Qq d
   in regular font mode.
   Furthermore, will be preserved between
   .Qq b
   and
   .Qq c .
   .El
 .Ss Scaling Widths  .Ss Scaling Widths
 Many macros support scaled widths for their arguments.  Many macros support scaled widths for their arguments.
 The syntax for a scaled width is  The syntax for a scaled width is
Line 294  file for a utility
Line 310  file for a utility
 \&.TH PROGNAME 1 2009-10-10  \&.TH PROGNAME 1 2009-10-10
 \&.SH NAME  \&.SH NAME
 \efBprogname\efR \e(en a description goes here  \efBprogname\efR \e(en a description goes here
 \&.\e\*q .SH LIBRARY  \&.\e\(dq .SH LIBRARY
 \&.\e\*q For sections 2 & 3 only.  \&.\e\(dq For sections 2 & 3 only.
 \&.\e\*q Not used in OpenBSD.  \&.\e\(dq Not used in OpenBSD.
 \&.SH SYNOPSIS  \&.SH SYNOPSIS
 \efBprogname\efR [\efB\e-options\efR] arguments...  \efBprogname\efR [\efB\e-options\efR] arguments...
 \&.SH DESCRIPTION  \&.SH DESCRIPTION
 The \efBfoo\efR utility processes files...  The \efBfoo\efR utility processes files...
 \&.\e\*q .SH IMPLEMENTATION NOTES  \&.\e\(dq .SH IMPLEMENTATION NOTES
 \&.\e\*q Not used in OpenBSD.  \&.\e\(dq Not used in OpenBSD.
 \&.\e\*q .SH RETURN VALUES  \&.\e\(dq .SH RETURN VALUES
 \&.\e\*q For sections 2, 3, & 9 only.  \&.\e\(dq For sections 2, 3, & 9 only.
 \&.\e\*q .SH ENVIRONMENT  \&.\e\(dq .SH ENVIRONMENT
 \&.\e\*q For sections 1, 6, 7, & 8 only.  \&.\e\(dq For sections 1, 6, 7, & 8 only.
 \&.\e\*q .SH FILES  \&.\e\(dq .SH FILES
 \&.\e\*q .SH EXIT STATUS  \&.\e\(dq .SH EXIT STATUS
 \&.\e\*q For sections 1, 6, & 8 only.  \&.\e\(dq For sections 1, 6, & 8 only.
 \&.\e\*q .SH EXAMPLES  \&.\e\(dq .SH EXAMPLES
 \&.\e\*q .SH DIAGNOSTICS  \&.\e\(dq .SH DIAGNOSTICS
 \&.\e\*q For sections 1, 4, 6, 7, & 8 only.  \&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
 \&.\e\*q .SH ERRORS  \&.\e\(dq .SH ERRORS
 \&.\e\*q For sections 2, 3, & 9 only.  \&.\e\(dq For sections 2, 3, & 9 only.
 \&.\e\*q .SH SEE ALSO  \&.\e\(dq .SH SEE ALSO
 \&.\e\*q .BR foo ( 1 )  \&.\e\(dq .BR foo ( 1 )
 \&.\e\*q .SH STANDARDS  \&.\e\(dq .SH STANDARDS
 \&.\e\*q .SH HISTORY  \&.\e\(dq .SH HISTORY
 \&.\e\*q .SH AUTHORS  \&.\e\(dq .SH AUTHORS
 \&.\e\*q .SH CAVEATS  \&.\e\(dq .SH CAVEATS
 \&.\e\*q .SH BUGS  \&.\e\(dq .SH BUGS
 \&.\e\*q .SH SECURITY CONSIDERATIONS  \&.\e\(dq .SH SECURITY CONSIDERATIONS
 \&.\e\*q Not used in OpenBSD.  \&.\e\(dq Not used in OpenBSD.
 .Ed  .Ed
 .Pp  .Pp
 The sections in a  The sections in a
Line 485  The syntax is as follows:
Line 501  The syntax is as follows:
 \&.YO \(lBbody...\(rB  \&.YO \(lBbody...\(rB
 \(lBbody...\(rB  \(lBbody...\(rB
 .Ed  .Ed
 .Pp  .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX"  
 .It Em Macro Ta Em Arguments Ta Em Scope     Ta Em Notes  .It Em Macro Ta Em Arguments Ta Em Scope     Ta Em Notes
 .It Sx \&AT  Ta    <=1       Ta    current   Ta    \&  .It Sx \&AT  Ta    <=1       Ta    current   Ta    \&
 .It Sx \&B   Ta    n         Ta    next-line Ta    \&  .It Sx \&B   Ta    n         Ta    next-line Ta    \&
Line 553  No closure refers to an explicit block closing macro.
Line 568  No closure refers to an explicit block closing macro.
 As a rule, block macros may not be nested; thus, calling a block macro  As a rule, block macros may not be nested; thus, calling a block macro
 while another block macro scope is open, and the open scope is not  while another block macro scope is open, and the open scope is not
 implicitly closed, is syntactically incorrect.  implicitly closed, is syntactically incorrect.
 .Pp  .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX"  
 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope  Ta Em Notes  .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope  Ta Em Notes
 .It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph   Ta    \&  .It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph   Ta    \&
 .It Sx \&IP  Ta    <3        Ta    current    Ta    paragraph   Ta    \&  .It Sx \&IP  Ta    <3        Ta    current    Ta    paragraph   Ta    \&
Line 575  are as mentioned in
Line 589  are as mentioned in
 .Pp  .Pp
 If a block macro is next-line scoped, it may only be followed by in-line  If a block macro is next-line scoped, it may only be followed by in-line
 macros for decorating text.  macros for decorating text.
   .Sh MACRO OVERVIEW
   This overview is sorted such that macros of similar purpose are listed
   together, to help find the best macro for any given purpose.
   Deprecated macros are not included in the overview, but can be found
   in the alphabetical reference below.
   .Ss Page header and footer meta-data
   .Bl -column "PP, LP, P" description
   .It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume
   .It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
   .It Sx UC Ta display BSD version in the page footer (<= 1 argument)
   .El
   .Ss Sections and paragraphs
   .Bl -column "PP, LP, P" description
   .It Sx SH Ta section header (one line)
   .It Sx SS Ta subsection header (one line)
   .It Sx PP , LP , P Ta start an undecorated paragraph (no arguments)
   .It Sx RS , RE Ta reset the left margin: Op Ar width
   .It Sx IP Ta indented paragraph: Op Ar head Op Ar width
   .It Sx TP Ta tagged paragraph: Op Ar width
   .It Sx HP Ta hanged paragraph: Op Ar width
   .It Sx \&br Ta force output line break in text mode (no arguments)
   .It Sx \&sp Ta force vertical space: Op Ar height
   .It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
   .It Sx in Ta additional indent: Op Ar width
   .El
   .Ss Physical markup
   .Bl -column "PP, LP, P" description
   .It Sx B Ta boldface font
   .It Sx I Ta italic font
   .It Sx R Ta roman (default) font
   .It Sx SB Ta small boldface font
   .It Sx SM Ta small roman font
   .It Sx BI Ta alternate between boldface and italic fonts
   .It Sx BR Ta alternate between boldface and roman fonts
   .It Sx IB Ta alternate between italic and boldface fonts
   .It Sx IR Ta alternate between italic and roman fonts
   .It Sx RB Ta alternate between roman and boldface fonts
   .It Sx RI Ta alternate between roman and italic fonts
   .El
 .Sh REFERENCE  .Sh REFERENCE
 This section is a canonical reference to all macros, arranged  This section is a canonical reference to all macros, arranged
 alphabetically.  alphabetically.
Line 957  implementations of the
Line 1010  implementations of the
 language.  language.
 .Pp  .Pp
 .Bl -dash -compact  .Bl -dash -compact
   .It
   Do not depend on
   .Sx \&SH
   or
   .Sx \&SS
   to close out a literal context opened with
   .Sx \&nf .
   This behaviour may not be portable.
 .It  .It
 In quoted literals, GNU troff allowed pair-wise double-quotes to produce  In quoted literals, GNU troff allowed pair-wise double-quotes to produce
 a standalone double-quote in formatted output.  a standalone double-quote in formatted output.
Legend:
Removed from v.1.105  
changed lines
  Added in v.1.110
CVSweb