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

Diff for /mandoc/mdoc.7 between version 1.251 and 1.263

version 1.251, 2015/02/15 17:57:45 version 1.263, 2017/05/05 02:31:35
Line 1 
Line 1 
 .\"     $Id$  .\"     $Id$
 .\"  .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>  .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>  .\" Copyright (c) 2010, 2011, 2013-2017 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 304  Print verbose information.
Line 304  Print verbose information.
 \&.El  \&.El
 .Ed  .Ed
 .Pp  .Pp
   List the options in alphabetical order,
   uppercase before lowercase for each letter and
   with no regard to whether an option takes an argument.
   Put digits in ascending order before all letter options.
   .Pp
 Manuals not documenting a command won't include the above fragment.  Manuals not documenting a command won't include the above fragment.
 .Pp  .Pp
 Since the  Since the
Line 471  in the alphabetical
Line 476  in the alphabetical
 .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)  .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
 .It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off  .It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off
 .It Sx \&Bk , \&Ek Ta keep block: Fl words  .It Sx \&Bk , \&Ek Ta keep block: Fl words
 .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 \&sp Ta force vertical space: Op Ar height
 .El  .El
 .Ss Semantic markup for command line utilities:  .Ss Semantic markup for command line utilities:
Line 969  argument.
Line 973  argument.
 A columnated list.  A columnated list.
 The  The
 .Fl width  .Fl width
 argument has no effect; instead, each argument specifies the width  argument has no effect; instead, the string length of each argument
 of one column, using either the scaling width syntax described in  specifies the width of one column.
 .Xr roff 7  
 or the string length of the argument.  
 If the first line of the body of a  If the first line of the body of a
 .Fl column  .Fl column
 list is not an  list is not an
Line 1622  See also
Line 1624  See also
 A function name.  A function name.
 Its syntax is as follows:  Its syntax is as follows:
 .Bd -ragged -offset indent  .Bd -ragged -offset indent
 .Pf \. Ns Sx \&Fn  .Pf . Sx \&Fn
 .Op Ar functype  .Op Ar functype
 .Ar funcname  .Ar funcname
 .Op Oo Ar argtype Oc Ar argname  .Op Oo Ar argtype Oc Ar argname
Line 1826  The
Line 1828  The
 list is the most complicated.  list is the most complicated.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...  
 .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...  .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
   .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
 .Pp  .Pp
 The arguments consist of one or more lines of text and macros  The arguments consist of one or more lines of text and macros
 representing a complete table line.  representing a complete table line.
 Cells within the line are delimited by tabs or by the special  Cells within the line are delimited by the special
 .Sx \&Ta  .Sx \&Ta
 block macro.  block macro or by literal tab characters.
   .Pp
   Using literal tabs is strongly discouraged because they are very
   hard to use correctly and
   .Nm
   code using them is very hard to read.
   In particular, a blank character is syntactically significant
   before and after the literal tab character.
   If a word precedes or follows the tab without an intervening blank,
   that word is never interpreted as a macro call, but always output
   literally.
   .Pp
 The tab cell delimiter may only be used within the  The tab cell delimiter may only be used within the
 .Sx \&It  .Sx \&It
 line itself; on following lines, only the  line itself; on following lines, only the
Line 1848  Note that quoted strings may span tab-delimited cells 
Line 1861  Note that quoted strings may span tab-delimited cells 
 line.  line.
 For example,  For example,
 .Pp  .Pp
 .Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;  .Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&;
 .Pp  .Pp
 will preserve the semicolon whitespace except for the last.  will preserve the whitespace before both commas,
   but not the whitespace before the semicolon.
 .Pp  .Pp
 See also  See also
 .Sx \&Bl .  .Sx \&Bl .
Line 1930  Examples:
Line 1944  Examples:
 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv  .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
 .Ss \&Nd  .Ss \&Nd
 A one line description of the manual's content.  A one line description of the manual's content.
 This may only be invoked in the  This is the mandatory last macro of the
 .Em SYNOPSIS  .Em NAME
 section subsequent the  section and not appropriate for other sections.
 .Sx \&Nm  
 macro.  
 .Pp  .Pp
 Examples:  Examples:
 .Dl Pf . Sx \&Nd mdoc language reference  .Dl Pf . Sx \&Nd mdoc language reference
Line 2095  It is suggested to leave it unspecified, in which case
Line 2107  It is suggested to leave it unspecified, in which case
 .Xr mandoc 1  .Xr mandoc 1
 uses its  uses its
 .Fl Ios  .Fl Ios
 argument, or, if that isn't specified either,  argument or, if that isn't specified either,
 .Fa sysname  .Fa sysname
 and  and
 .Fa release  .Fa release
Line 2157  See also
Line 2169  See also
 Close parenthesised context opened by  Close parenthesised context opened by
 .Sx \&Po .  .Sx \&Po .
 .Ss \&Pf  .Ss \&Pf
 Removes the space between its argument  Removes the space between its argument and the following macro.
 .Pq Dq prefix  
 and the following macro.  
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 .Pf Ar prefix macro arguments ...  .D1 .Pf Ar prefix macro arguments ...
 .Pp  .Pp
 This is equivalent to:  This is equivalent to:
 .Pp  .Pp
 .D1 .No Ar prefix No \&Ns Ar macro arguments ...  .D1 .No \e& Ns Ar prefix No \&Ns Ar macro arguments ...
 .Pp  .Pp
   The
   .Ar prefix
   argument is not parsed for macro names or delimiters,
   but used verbatim as if it were escaped.
   .Pp
 Examples:  Examples:
 .Dl ".Pf $ Ar variable_name"  .Dl ".Pf $ Ar variable_name"
   .Dl ".Pf . Ar macro_name"
 .Dl ".Pf 0x Ar hex_digits"  .Dl ".Pf 0x Ar hex_digits"
 .Pp  .Pp
 See also  See also
Line 2269  Examples:
Line 2285  Examples:
 \&.%A J. D. Ullman  \&.%A J. D. Ullman
 \&.%B Introduction to Automata Theory, Languages, and Computation  \&.%B Introduction to Automata Theory, Languages, and Computation
 \&.%I Addison-Wesley  \&.%I Addison-Wesley
 \&.%C Reading, Massachusettes  \&.%C Reading, Massachusetts
 \&.%D 1979  \&.%D 1979
 \&.Re  \&.Re
 .Ed  .Ed
Line 2707  Link to another manual
Line 2723  Link to another manual
 .Pq Qq cross-reference .  .Pq Qq cross-reference .
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Xr Ar name Op section  .D1 Pf \. Sx \&Xr Ar name section
 .Pp  .Pp
 Cross reference the  Cross reference the
 .Ar name  .Ar name
 and  and
 .Ar section  .Ar section
 number of another man page;  number of another man page.
 omitting the section number is rarely useful.  
 .Pp  .Pp
 Examples:  Examples:
 .Dl \&.Xr mandoc 1  .Dl \&.Xr mandoc 1
 .Dl \&.Xr mandoc 1 \&;  .Dl \&.Xr mandoc 1 \&;
 .Dl \&.Xr mandoc 1 \&Ns s behaviour  .Dl \&.Xr mandoc 1 \&Ns s behaviour
 .Ss \&br  
 Emits a line-break.  
 This macro should not be used; it is implemented for compatibility with  
 historical manuals.  
 .Pp  
 Consider using  
 .Sx \&Pp  
 in the event of natural paragraph breaks.  
 .Ss \&sp  .Ss \&sp
 Emits vertical space.  Emits vertical space.
 This macro should not be used; it is implemented for compatibility with  This macro should not be used; it is implemented for compatibility with
Line 3026  then the macro accepts an arbitrary number of argument
Line 3033  then the macro accepts an arbitrary number of argument
 .It Sx \&Ux  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Ux  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Va  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Va  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Vt  Ta    Yes      Ta    Yes      Ta    >0  .It Sx \&Vt  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0  .It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    2
 .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0  
 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1  .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1
 .El  .El
 .Ss Delimiters  .Ss Delimiters
Line 3046  For many macros, when the leading arguments are openin
Line 3052  For many macros, when the leading arguments are openin
 these delimiters are put before the macro scope,  these delimiters are put before the macro scope,
 and when the trailing arguments are closing delimiters,  and when the trailing arguments are closing delimiters,
 these delimiters are put after the macro scope.  these delimiters are put after the macro scope.
   Spacing is suppressed after opening delimiters
   and before closing delimiters.
 For example,  For example,
 .Pp  .Pp
 .D1 Pf \. \&Aq "( [ word ] ) ."  .D1 Pf \. \&Aq "( [ word ] ) ."
Line 3102  renders as:
Line 3110  renders as:
 .D1 Fl a ( b | c \*(Ba d ) e  .D1 Fl a ( b | c \*(Ba d ) e
 .Pp  .Pp
 This applies to both opening and closing delimiters,  This applies to both opening and closing delimiters,
 and also to the middle delimiter:  and also to the middle delimiter, which does not suppress spacing:
 .Pp  .Pp
 .Bl -tag -width Ds -offset indent -compact  .Bl -tag -width Ds -offset indent -compact
 .It \&|  .It \&|
Line 3210  but produces large indentations.
Line 3218  but produces large indentations.
 .Xr mandoc_char 7 ,  .Xr mandoc_char 7 ,
 .Xr roff 7 ,  .Xr roff 7 ,
 .Xr tbl 7  .Xr tbl 7
   .Pp
   The web page
   .Lk http://mdocml.bsd.lv/mdoc/ "extended documentation for the mdoc language"
   provides a few tutorial-style pages for beginners, an extensive style
   guide for advanced authors, and an alphabetic index helping to choose
   the best macros for various kinds of content.
 .Sh HISTORY  .Sh HISTORY
 The  The
 .Nm  .Nm
Legend:
Removed from v.1.251  
changed lines
  Added in v.1.263
CVSweb