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

Diff for /mandoc/mdoc.7 between version 1.250 and 1.268

version 1.250, 2015/01/29 00:33:57 version 1.268, 2017/07/05 12:25:17
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  
 .El  .El
 .Ss Semantic markup for command line utilities:  .Ss Semantic markup for command line utilities
 .Bl -column "Brq, Bro, Brc" description  .Bl -column "Brq, Bro, Brc" description
 .It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility  .It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
 .It Sx \&Fl Ta command line options (flags) (>=0 arguments)  .It Sx \&Fl Ta command line options (flags) (>=0 arguments)
Line 485  in the alphabetical
Line 488  in the alphabetical
 .It Sx \&Ev Ta environmental variable (>0 arguments)  .It Sx \&Ev Ta environmental variable (>0 arguments)
 .It Sx \&Pa Ta file system path (>=0 arguments)  .It Sx \&Pa Ta file system path (>=0 arguments)
 .El  .El
 .Ss Semantic markup for function libraries:  .Ss Semantic markup for function libraries
 .Bl -column "Brq, Bro, Brc" description  .Bl -column "Brq, Bro, Brc" description
 .It Sx \&Lb Ta function library (one argument)  .It Sx \&Lb Ta function library (one argument)
 .It Sx \&In Ta include file (one argument)  .It Sx \&In Ta include file (one argument)
Line 506  in the alphabetical
Line 509  in the alphabetical
 .It Sx \&Er Ta error constant (>0 arguments)  .It Sx \&Er Ta error constant (>0 arguments)
 .It Sx \&Ev Ta environmental variable (>0 arguments)  .It Sx \&Ev Ta environmental variable (>0 arguments)
 .El  .El
 .Ss Various semantic markup:  .Ss Various semantic markup
 .Bl -column "Brq, Bro, Brc" description  .Bl -column "Brq, Bro, Brc" description
 .It Sx \&An Ta author name (>0 arguments)  .It Sx \&An Ta author name (>0 arguments)
 .It Sx \&Lk Ta hyperlink: Ar uri Op Ar name  .It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
Line 732  A version of
Line 735  A version of
 .At .  .At .
 .It Cm III  .It Cm III
 .At III .  .At III .
 .It Cm V[.[1-4]]?  .It Cm V | V.[1-4]
 A version of  A version of
 .At V .  .At V .
 .El  .El
Line 969  argument.
Line 972  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 1623  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 1758  is preferred for displaying code; the
Line 1759  is preferred for displaying code; the
 .Sx \&Ic  .Sx \&Ic
 macro is used when referring to specific instructions.  macro is used when referring to specific instructions.
 .Ss \&In  .Ss \&In
 An  The name of an include file.
 .Dq include  This macro is most often used in section 2, 3, and 9 manual pages.
 file.  .Pp
 When invoked as the first macro on an input line in the  When invoked as the first macro on an input line in the
 .Em SYNOPSIS  .Em SYNOPSIS
 section, the argument is displayed in angle brackets  section, the argument is displayed in angle brackets
 and preceded by  and preceded by
 .Dq #include ,  .Qq #include ,
 and a blank line is inserted in front if there is a preceding  and a blank line is inserted in front if there is a preceding
 function declaration.  function declaration.
 This is most often used in section 2, 3, and 9 manual pages.  In other sections, it only encloses its argument in angle brackets
   and causes no line break.
 .Pp  .Pp
 Examples:  Examples:
 .Dl \&.In sys/types.h  .Dl \&.In sys/types.h
Line 1825  The
Line 1827  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
 .Sx \&Ta  .Sx \&Ta
 macro can be used to delimit cells, and  macro can be used to delimit cells, and portability requires that
 .Sx \&Ta  .Sx \&Ta
 is only recognised as a macro when called by other macros,  is called by other macros: some parsers do not recognize it when
 not as the first macro on a line.  it appears as the first macro on a line.
 .Pp  .Pp
 Note that quoted strings may span tab-delimited cells on an  Note that quoted strings may span tab-delimited cells on an
 .Sx \&It  .Sx \&It
 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 1929  Examples:
Line 1943  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 2094  It is suggested to leave it unspecified, in which case
Line 2106  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 2156  See also
Line 2168  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 2268  Examples:
Line 2284  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 2559  The second and last Technical Corrigendum.
Line 2575  The second and last Technical Corrigendum.
 .br  .br
 This standard is also called  This standard is also called
 X/Open Portability Guide version 7.  X/Open Portability Guide version 7.
 .Pp  
 .It \-p1003.1-2013  
 .St -p1003.1-2013  
 .br  
 This is the first Technical Corrigendum.  
 .El  .El
 .It Other standards  .It Other standards
 .Pp  .Pp
Line 2706  Link to another manual
Line 2717  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  
 Emits vertical space.  
 This macro should not be used; it is implemented for compatibility with  
 historical manuals.  
 Its syntax is as follows:  
 .Pp  
 .D1 Pf \. Sx \&sp Op Ar height  
 .Pp  
 The  
 .Ar height  
 argument is a scaling width as described in  
 .Xr roff 7 .  
 If unspecified,  
 .Sx \&sp  
 asserts a single vertical space.  
 .Sh MACRO SYNTAX  .Sh MACRO SYNTAX
 The syntax of a macro depends on its classification.  The syntax of a macro depends on its classification.
 In this section,  In this section,
Line 3025  then the macro accepts an arbitrary number of argument
Line 3012  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  
 .El  .El
 .Ss Delimiters  .Ss Delimiters
 When a macro argument consists of one single input character  When a macro argument consists of one single input character
Line 3045  For many macros, when the leading arguments are openin
Line 3030  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 3101  renders as:
Line 3088  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 3209  but produces large indentations.
Line 3196  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.250  
changed lines
  Added in v.1.268
CVSweb