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

Diff for /mandoc/mdoc.7 between version 1.197 and 1.198

version 1.197, 2011/08/10 14:07:23 version 1.198, 2011/08/16 23:37:39
Line 471  Print verbose information.
Line 471  Print verbose information.
 .Ed  .Ed
 .Pp  .Pp
 Manuals not documenting a command won't include the above fragment.  Manuals not documenting a command won't include the above fragment.
   .Pp
   Since the
   .Em DESCRIPTION
   section usually contains most of the text of a manual, longer manuals
   often use the
   .Sx \&Ss
   macro to form subsections.
   In very long manuals, the
   .Em DESCRIPTION
   may be split into multiple sections, each started by an
   .Sx \&Sh
   macro followed by a non-standard section name, and each having
   several subsections, like in the present
   .Nm
   manual.
 .It Em IMPLEMENTATION NOTES  .It Em IMPLEMENTATION NOTES
 Implementation-specific notes should be kept here.  Implementation-specific notes should be kept here.
 This is useful when implementing standard functions that may have side  This is useful when implementing standard functions that may have side
Line 532  This section should exist for most manuals.
Line 547  This section should exist for most manuals.
 Cross-references should conventionally be ordered first by section, then  Cross-references should conventionally be ordered first by section, then
 alphabetically.  alphabetically.
 .Pp  .Pp
   References to other documentation concerning the topic of the manual page,
   for example authoritative books or journal articles, may also be
   provided in this section.
   .Pp
 See  See
   .Sx \&Rs
   and
 .Sx \&Xr .  .Sx \&Xr .
 .It Em STANDARDS  .It Em STANDARDS
 References any standards implemented or used.  References any standards implemented or used.
Line 543  section should be used instead.
Line 564  section should be used instead.
 See  See
 .Sx \&St .  .Sx \&St .
 .It Em HISTORY  .It Em HISTORY
 A brief history of the subject, including where support first appeared.  A brief history of the subject, including where it was first implemented,
   and when it was ported to or reimplemented for the operating system at hand.
 .It Em AUTHORS  .It Em AUTHORS
 Credits to the person or persons who wrote the code and/or documentation.  Credits to the person or persons who wrote the code and/or documentation.
 Authors should generally be noted by both name and email address.  Authors should generally be noted by both name and email address.
Line 1176  The
Line 1198  The
 must be one of the following:  must be one of the following:
 .Bl -tag -width 13n -offset indent  .Bl -tag -width 13n -offset indent
 .It Fl centered  .It Fl centered
 Centre-justify each line.  Produce one output line from each input line, and centre-justify each line.
 Using this display type is not recommended; many  Using this display type is not recommended; many
 .Nm  .Nm
 implementations render it poorly.  implementations render it poorly.
 .It Fl filled  .It Fl filled
 Left- and right-justify the block.  Change the positions of line breaks to fill each line, and left- and
   right-justify the resulting block.
 .It Fl literal  .It Fl literal
 Do not justify the block at all.  Produce one output line from each input line,
   and do not justify the block at all.
 Preserve white space as it appears in the input.  Preserve white space as it appears in the input.
   Always use a constant-width font.
   Use this for displaying source code.
 .It Fl ragged  .It Fl ragged
 Only left-justify the block.  Change the positions of line breaks to fill each line, and left-justify
   the resulting block.
 .It Fl unfilled  .It Fl unfilled
 An alias for  The same as
 .Fl literal .  .Fl literal ,
   but using the same font as for normal text, which is a variable width font
   if supported by the output device.
 .El  .El
 .Pp  .Pp
 The  The
Line 1205  which may be one of the following:
Line 1234  which may be one of the following:
 .It  .It
 One of the pre-defined strings  One of the pre-defined strings
 .Cm indent ,  .Cm indent ,
 the width of standard indentation;  the width of a standard indentation (six constant width characters);
 .Cm indent-two ,  .Cm indent-two ,
 twice  twice
 .Cm indent ;  .Cm indent ;
Line 1382  except that dashes are used in place of bullets.
Line 1411  except that dashes are used in place of bullets.
 Like  Like
 .Fl inset ,  .Fl inset ,
 except that item heads are not parsed for macro invocations.  except that item heads are not parsed for macro invocations.
 .\" but with additional formatting to the head.  Most often used in the
   .Em DIAGNOSTICS
   section with error constants in the item heads.
 .It Fl enum  .It Fl enum
 A numbered list.  A numbered list.
   No item heads can be specified.
 Formatted like  Formatted like
 .Fl bullet ,  .Fl bullet ,
 except that cardinal numbers are used in place of bullets,  except that cardinal numbers are used in place of bullets,
Line 1424  this head on the same output line.
Line 1456  this head on the same output line.
 Otherwise, the body starts on the output line following the head.  Otherwise, the body starts on the output line following the head.
 .El  .El
 .Pp  .Pp
   Lists may be nested within lists and displays.
   Nesting of
   .Fl column
   and
   .Fl enum
   lists may not be portable.
   .Pp
 See also  See also
 .Sx \&El  .Sx \&El
 and  and
Line 1500  and
Line 1539  and
 .Sx \&Ux .  .Sx \&Ux .
 .Ss \&Bt  .Ss \&Bt
 Prints  Prints
 .Dq is currently in beta test .  .Dq is currently in beta test.
 .Ss \&Bx  .Ss \&Bx
 Format the BSD version provided as an argument, or a default value if no  Format the BSD version provided as an argument, or a default value if no
 argument is provided.  argument is provided.
 .Pp  .Pp
 Examples:  Examples:
   .Dl \&.Bx 4.3 Tahoe
 .Dl \&.Bx 4.4  .Dl \&.Bx 4.4
 .Dl \&.Bx  .Dl \&.Bx
 .Pp  .Pp
Line 1865  See also
Line 1905  See also
 and  and
 .Sx \&It .  .Sx \&It .
 .Ss \&Em  .Ss \&Em
 Denotes text that should be emphasised.  Denotes text that should be
   .Em emphasised .
 Note that this is a presentation term and should not be used for  Note that this is a presentation term and should not be used for
 stylistically decorating technical terms.  stylistically decorating technical terms.
   Depending on the output device, this is usually represented
   using an italic font or underlined characters.
 .Pp  .Pp
 Examples:  Examples:
 .Dl \&.Em Warnings!  .Dl \&.Em Warnings!
Line 1875  Examples:
Line 1918  Examples:
 .Pp  .Pp
 See also  See also
 .Sx \&Bf ,  .Sx \&Bf ,
 .Sx \&Sy ,  .Sx \&Li ,
   .Sx \&No ,
 and  and
 .Sx \&Li .  .Sx \&Sy .
 .Ss \&En  .Ss \&En
 This macro is obsolete and not implemented in  This macro is obsolete and not implemented in
 .Xr mandoc 1 .  .Xr mandoc 1 .
Line 1994  output.
Line 2038  output.
 Examples:  Examples:
 .Dl ".Nm cat Fl v No considered harmful"  .Dl ".Nm cat Fl v No considered harmful"
 .Dl ".Nm cp Fl pR Ar source ... directory"  .Dl ".Nm cp Fl pR Ar source ... directory"
 .Dl ".Nm find Ar dir Fl type Cm d Fl name Pa CVS  .Dl ".Nm find Ar dir Fl type Cm d Fl name Pa CVS"
 .Dl ".Nm kill Fl Ar signal_number pid"  .Dl ".Nm kill Fl Ar signal_number pid"
 .Dl ".Nm su Fl"  .Dl ".Nm su Fl"
 .Pp  .Pp
Line 2069  See also
Line 2113  See also
 and  and
 .Sx \&Ft .  .Sx \&Ft .
 .Ss \&Fr  .Ss \&Fr
 This macro is obsolete and not implemented.  This macro is obsolete and not implemented in
   .Xr mandoc 1 .
   .Pp
   It was used to show function return values.
   The syntax was:
   .Pp
   .Dl Pf . Sx \&Fr Ar value
 .Ss \&Ft  .Ss \&Ft
 A function type.  A function type.
 Its syntax is as follows:  Its syntax is as follows:
Line 2112  See also
Line 2162  See also
 and  and
 .Sx \&Ux .  .Sx \&Ux .
 .Ss \&Hf  .Ss \&Hf
 This macro is obsolete and not implemented.  This macro is not implemented in
   .Xr mandoc 1 .
   .Pp
   It was used to include the contents of a (header) file literally.
   The syntax was:
   .Pp
   .Dl Pf . Sx \&Hf Ar filename
 .Ss \&Ic  .Ss \&Ic
 Designate an internal or interactive command.  Designate an internal or interactive command.
 This is similar to  This is similar to
Line 2251  Examples:
Line 2307  Examples:
 .Dl \&.Lb libz  .Dl \&.Lb libz
 .Dl \&.Lb mdoc  .Dl \&.Lb mdoc
 .Ss \&Li  .Ss \&Li
 Denotes text that should be in a literal font mode.  Denotes text that should be in a
   .Li literal
   font mode.
 Note that this is a presentation term and should not be used for  Note that this is a presentation term and should not be used for
 stylistically decorating technical terms.  stylistically decorating technical terms.
 .Pp  .Pp
   On terminal output devices, this is often indistinguishable from
   normal text.
   .Pp
 See also  See also
 .Sx \&Bf ,  .Sx \&Bf ,
 .Sx \&Sy ,  .Sx \&Em ,
   .Sx \&No ,
 and  and
 .Sx \&Em .  .Sx \&Sy .
 .Ss \&Lk  .Ss \&Lk
 Format a hyperlink.  Format a hyperlink.
 Its syntax is as follows:  Its syntax is as follows:
Line 2303  section subsequent the
Line 2365  section subsequent the
 macro.  macro.
 .Pp  .Pp
 Examples:  Examples:
 .Dl \&.Sx \&Nd mdoc language reference  .Dl Pf . Sx \&Nd mdoc language reference
 .Dl \&.Sx \&Nd format and display UNIX manuals  .Dl Pf . Sx \&Nd format and display UNIX manuals
 .Pp  .Pp
 The  The
 .Sx \&Nd  .Sx \&Nd
Line 2356  macro rather than
Line 2418  macro rather than
 .Sx \&Nm  .Sx \&Nm
 to mark up the name of the manual page.  to mark up the name of the manual page.
 .Ss \&No  .Ss \&No
 A  Normal text.
 .Dq noop  Closes the scope of any preceding in-line macro.
 macro used to terminate prior macro contexts.  When used after physical formatting macros like
   .Sx \&Em
   or
   .Sx \&Sy ,
   switches back to the standard font face and weight.
   Can also be used to embed plain text strings in macro lines
   using semantic annotation macros.
 .Pp  .Pp
 Examples:  Examples:
 .Dl \&.Sx \&Fl ab \&No cd \&Fl ef  .Dl ".Em italic , Sy bold , No and roman"
   .Pp
   .Bd -literal -offset indent -compact
   \&.Sm off
   \&.Cm :C No / Ar pattern No / Ar replacement No /
   \&.Sm on
   .Ed
   .Pp
   See also
   .Sx \&Em ,
   .Sx \&Li ,
   and
   .Sx \&Sy .
 .Ss \&Ns  .Ss \&Ns
 Suppress a space.  Suppress a space between the output of the preceding macro
 Following invocation, text is interpreted as free-form text until a  and the following text or macro.
 macro is encountered.  Following invocation, input is interpreted as normal text
   just like after an
   .Sx \&No
   macro.
 .Pp  .Pp
 This has no effect when invoked at the start of a macro line.  This has no effect when invoked at the start of a macro line.
 .Pp  .Pp
 Examples:  Examples:
 .Dl \&.Fl o \&Ns \&Ar output  .Dl ".Ar name Ns = Ns Ar value"
   .Dl ".Cm :M Ns Ar pattern"
   .Dl ".Fl o Ns Ar output"
 .Pp  .Pp
 See also  See also
 .Sx \&No  .Sx \&No
Line 2448  See also
Line 2533  See also
 and  and
 .Sx \&Dt .  .Sx \&Dt .
 .Ss \&Ot  .Ss \&Ot
 Unknown usage.  This macro is obsolete and not implemented in
   .Xr mandoc 1 .
 .Pp  .Pp
 .Em Remarks :  Historical
 this macro has been deprecated.  .Xr mdoc 7
   packages described it as
   .Dq "old function type (FORTRAN)" .
 .Ss \&Ox  .Ss \&Ox
 Format the  Format the
 .Ox  .Ox
Line 2487  See also
Line 2575  See also
 Close parenthesised context opened by  Close parenthesised context opened by
 .Sx \&Po .  .Sx \&Po .
 .Ss \&Pf  .Ss \&Pf
 Removes the space  Removes the space between its argument
 .Pq Dq prefix  .Pq Dq prefix
 between its arguments.  and the following macro.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. \&Pf Ar prefix suffix  .D1 .Pf Ar prefix macro arguments ...
 .Pp  .Pp
 The  This is equivalent to:
 .Ar suffix  
 argument may be a macro.  
 .Pp  .Pp
   .D1 .No Ar prefix No \&Ns Ar macro arguments ...
   .Pp
 Examples:  Examples:
 .Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix  .Dl ".Pf $ Ar variable_name"
   .Dl ".Pf 0x Ar hex_digits"
   .Pp
   See also
   .Sx \&Ns
   and
   .Sx \&Sm .
 .Ss \&Po  .Ss \&Po
 Multi-line version of  Multi-line version of
 .Sx \&Pq .  .Sx \&Pq .
Line 2507  Multi-line version of
Line 2601  Multi-line version of
 Break a paragraph.  Break a paragraph.
 This will assert vertical space between prior and subsequent macros  This will assert vertical space between prior and subsequent macros
 and/or text.  and/or text.
   .Pp
   Paragraph breaks are not needed before or after
   .Sx \&Sh
   or
   .Sx \&Ss
   macros or before displays
   .Pq Sx \&Bd
   or lists
   .Pq Sx \&Bl
   unless the
   .Fl compact
   flag is given.
 .Ss \&Pq  .Ss \&Pq
 Parenthesised enclosure.  Parenthesised enclosure.
 .Pp  .Pp
Line 2526  Multi-line version of
Line 2632  Multi-line version of
 .Sx \&Qq .  .Sx \&Qq .
 .Ss \&Qq  .Ss \&Qq
 Encloses its arguments in  Encloses its arguments in
 .Dq typewriter  .Qq typewriter
 double-quotes.  double-quotes.
 Consider using  Consider using
 .Sx \&Dq .  .Sx \&Dq .
Line 2640  Multi-line version of
Line 2746  Multi-line version of
 .Sx \&Sq .  .Sx \&Sq .
 .Ss \&Sq  .Ss \&Sq
 Encloses its arguments in  Encloses its arguments in
 .Dq typewriter  .Sq typewriter
 single-quotes.  single-quotes.
 .Pp  .Pp
 See also  See also
Line 2649  See also
Line 2755  See also
 and  and
 .Sx \&So .  .Sx \&So .
 .Ss \&Ss  .Ss \&Ss
 Begin a new sub-section.  Begin a new subsection.
 Unlike with  Unlike with
 .Sx \&Sh ,  .Sx \&Sh ,
 there's no convention for sub-sections.  there is no convention for the naming of subsections.
 Conventional sections, as described in  Except
 .Sx MANUAL STRUCTURE ,  .Em DESCRIPTION ,
 rarely have sub-sections.  the conventional sections described in
   .Sx MANUAL STRUCTURE
   rarely have subsections.
 .Pp  .Pp
 Sub-section names should be unique so that they may be keyed by  Sub-section names should be unique so that they may be keyed by
 .Sx \&Sx .  .Sx \&Sx .
Line 2767  The following standards are recognised:
Line 2875  The following standards are recognised:
 .St -svid4  .St -svid4
 .El  .El
 .Ss \&Sx  .Ss \&Sx
 Reference a section or sub-section.  Reference a section or subsection in the same manual page.
 The referenced section or sub-section name must be identical to the  The referenced section or subsection name must be identical to the
 enclosed argument, including whitespace.  enclosed argument, including whitespace.
 .Pp  .Pp
 Examples:  Examples:
Line 2786  stylistically decorating technical terms.
Line 2894  stylistically decorating technical terms.
 .Pp  .Pp
 See also  See also
 .Sx \&Bf ,  .Sx \&Bf ,
   .Sx \&Em ,
 .Sx \&Li ,  .Sx \&Li ,
 and  and
 .Sx \&Em .  .Sx \&No .
 .Ss \&Ta  .Ss \&Ta
 Table cell separator in  Table cell separator in
 .Sx \&Bl Fl column  .Sx \&Bl Fl column
Line 2797  lists; can only be used below
Line 2906  lists; can only be used below
 .Ss \&Tn  .Ss \&Tn
 Format a tradename.  Format a tradename.
 .Pp  .Pp
   Since this macro is often implemented to use a small caps font,
   it has historically been used for acronyms (like ASCII) as well.
   Such usage is not recommended because it would use the same macro
   sometimes for semantical annotation, sometimes for physical formatting.
   .Pp
 Examples:  Examples:
 .Dl \&.Tn IBM  .Dl \&.Tn IBM
 .Ss \&Ud  .Ss \&Ud
 Prints out  Prints out
 .Dq currently under development .  .Dq currently under development.
 .Ss \&Ux  .Ss \&Ux
 Format the UNIX name.  Format the UNIX name.
 Accepts no argument.  Accepts no argument.
Line 3097  This is not supported by mandoc.
Line 3211  This is not supported by mandoc.
 .Xr mandoc 1 ,  .Xr mandoc 1 ,
 .Xr eqn 7 ,  .Xr eqn 7 ,
 .Xr man 7 ,  .Xr man 7 ,
 .Xr mandoc_char 7  .Xr mandoc_char 7 ,
 .Xr roff 7 ,  .Xr roff 7 ,
 .Xr tbl 7  .Xr tbl 7
 .Sh HISTORY  .Sh HISTORY

Legend:
Removed from v.1.197  
changed lines
  Added in v.1.198

CVSweb