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

Diff for /mandoc/mdoc.7 between version 1.200 and 1.208

version 1.200, 2011/08/17 20:34:53 version 1.208, 2011/09/02 19:37:35
Line 63  and
Line 63  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
 whitespace are  whitespace are
 stripped from input.  stripped from input.
   .Pp
   Examples:
   .Bd -literal -offset indent -compact
   \&.\e\(dq This is a comment line.
   \&.\e\(dq The next line is ignored:
   \&.
   \&.Em Emphasis \e\(dq This is also a comment.
   .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
 differently across output media.  differently across output media.
Line 89  or a single one character sequence.
Line 97  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 117  scope.
Line 125  scope.
 .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
 .Pp  .Pp
 Text decoration is  Text decoration is
Line 143  and N-character
Line 151  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 168  In the rare case that a blank character is needed at t
Line 176  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 .
   .Pp
 Blank text lines, which may include whitespace, are only permitted  Blank text lines, which may include whitespace, are only permitted
 within literal contexts.  within literal contexts.
 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.
 For example,  Quoted text, even if whitespace or if it would cause a macro invocation
   when unquoted, is considered literal text.
 .Pp  .Pp
 .D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq"  
 .Pp  
 renders as  
 .Sq Fn strlen "const char *s" ,  
 while  
 .Pp  
 .D1 Pf \. \&Fn strlen "const char *s"  
 .Pp  
 would produce  
 .Sq Fn strlen const char *s .  
 .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 .Fn strlen \(dqconst char *s\(dq
 but quoting is usually better for clarity.  Group arguments
 .Pp  .Qq const char *s
 Note that any quoted text, even if it would cause a macro invocation  into one function argument.
 when unquoted, is considered literal text.  If unspecified,
 Thus, the following produces  .Qq const ,
 .Sq Op "Fl a" :  .Qq char ,
 .Bd -literal -offset indent  and
 \&.Op "Fl a"  .Qq *s
 .Ed  would be considered separate arguments.
 .Pp  .Pq See Sx \&Fn .
 In text lines, quotes are regarded as opaque text.  .It Li .Op \(dqFl a\(dq
   Consider
   .Qq \&Fl a
   as literal text instead of a flag macro.
   .Pq Aee Sx \&Op , \&Fl .
   .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 257  See
Line 264  See
 .Pp  .Pp
 Examples:  Examples:
 .Bl -tag -width Ds -offset indent -compact  .Bl -tag -width Ds -offset indent -compact
 .It \&.Bl -tag -width 2i  .It Li \&.Bl -tag -width 2i
 two-inch tagged list indentation  two-inch tagged list indentation
 .Pq see Sx \&Bl  .Pq see Sx \&Bl
 .It \&.br 2v  .It Li \&.sp 2v
 two vertical spaces  two vertical spaces
 .Pq see Sx \&br  .Pq see Sx \&sp
 .El  .El
 .Ss Sentence Spacing  .Ss Sentence Spacing
 Sentences should terminate at the end of an input line.  Sentences should terminate at the end of an input line.
Line 324  file for a utility
Line 331  file for a utility
 \&.Sh NAME  \&.Sh NAME
 \&.Nm progname  \&.Nm progname
 \&.Nd one line about what it does  \&.Nd one line about what it does
 \&.\e\*q .Sh LIBRARY  \&.\e\(dq .Sh LIBRARY
 \&.\e\*q For sections 2, 3, & 9 only.  \&.\e\(dq For sections 2, 3, & 9 only.
 \&.\e\*q Not used in OpenBSD.  \&.\e\(dq Not used in OpenBSD.
 \&.Sh SYNOPSIS  \&.Sh SYNOPSIS
 \&.Nm progname  \&.Nm progname
 \&.Op Fl options  \&.Op Fl options
Line 335  file for a utility
Line 342  file for a utility
 The  The
 \&.Nm  \&.Nm
 utility processes files ...  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 .Xr foobar 1  \&.\e\(dq .Xr foobar 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 an  The sections in an
Line 438  macros should follow C header-file conventions.
Line 445  macros should follow C header-file conventions.
 .Pp  .Pp
 And for the third, configurations (section 4):  And for the third, configurations (section 4):
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Cd \*qit* at isa? port 0x2e\*q  \&.Cd \(dqit* at isa? port 0x2e\(dq
 \&.Cd \*qit* at isa? port 0x4e\*q  \&.Cd \(dqit* at isa? port 0x4e\(dq
 .Ed  .Ed
 .Pp  .Pp
 Manuals not in these sections generally don't need a  Manuals not in these sections generally don't need a
Line 682  contain a head.
Line 689  contain a head.
 \(lBbody...\(rB  \(lBbody...\(rB
 \&.Yc  \&.Yc
 .Ed  .Ed
 .Pp  .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX"  
 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope  .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&Bd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ed  .It Sx \&Bd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ed
 .It Sx \&Bf  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ef  .It Sx \&Bf  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ef
Line 715  has multiple heads.
Line 721  has multiple heads.
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB  \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
 \(lBbody...\(rB  \(lBbody...\(rB
 .Ed  .Ed
 .Pp  .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX"  
 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope  .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&It Ta \&No Ta Yes  Ta closed by Sx \&It , Sx \&El  .It Sx \&It Ta \&No Ta Yes  Ta closed by Sx \&It , Sx \&El
 .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh  .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
Line 751  and/or tail
Line 756  and/or tail
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \  \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
 \(lBbody...\(rB \&Yc \(lBtail...\(rB  \(lBbody...\(rB \&Yc \(lBtail...\(rB
 .Ed  .Ed
 .Pp  .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent  
 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope  .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&Ac  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Ao  .It Sx \&Ac  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Ao
 .It Sx \&Ao  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Ac  .It Sx \&Ao  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Ac
Line 785  end of the line.
Line 789  end of the line.
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
 .Ed  .Ed
 .Pp  .Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
 .Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent  
 .It Em Macro Ta Em Callable Ta Em Parsed  .It Em Macro Ta Em Callable Ta Em Parsed
 .It Sx \&Aq  Ta    Yes      Ta    Yes  .It Sx \&Aq  Ta    Yes      Ta    Yes
 .It Sx \&Bq  Ta    Yes      Ta    Yes  .It Sx \&Bq  Ta    Yes      Ta    Yes
Line 821  in
Line 824  in
 lists.  lists.
 It delimits blocks representing table cells;  It delimits blocks representing table cells;
 these blocks have bodies, but no heads.  these blocks have bodies, but no heads.
 .Pp  .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent  
 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope  .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&Ta  Ta    Yes      Ta    Yes    Ta closed by Sx \&Ta , Sx \&It  .It Sx \&Ta  Ta    Yes      Ta    Yes    Ta closed by Sx \&Ta , Sx \&It
 .El  .El
Line 840  then the macro accepts an arbitrary number of argument
Line 842  then the macro accepts an arbitrary number of argument
   
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN  \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
 .Ed  .Ed
 .Pp  .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
 .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent  
 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments  .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
 .It Sx \&%A  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%A  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%B  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%B  Ta    \&No     Ta    \&No     Ta    >0
Line 2095  section, this macro starts a new output line,
Line 2096  section, this macro starts a new output line,
 and a blank line is automatically inserted between function definitions.  and a blank line is automatically inserted between function definitions.
 .Pp  .Pp
 Examples:  Examples:
 .Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q  .Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
 .Dl \&.Fn funcname \*qint arg0\*q  .Dl \&.Fn funcname \(dqint arg0\(dq
 .Dl \&.Fn funcname arg0  .Dl \&.Fn funcname arg0
 .Pp  .Pp
 .Bd -literal -offset indent -compact  .Bd -literal -offset indent -compact
Line 2301  line itself; on following lines, only the
Line 2302  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
 .Sx \&Ta  .Sx \&Ta
 is only recognized as a macro when called by other macros,  is only recognised as a macro when called by other macros,
 not as the first macro on a line.  not 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
Line 2361  Its syntax is as follows:
Line 2362  Its syntax is as follows:
 .D1 Pf \. Sx \&Lk Ar uri Op Ar name  .D1 Pf \. Sx \&Lk Ar uri Op Ar name
 .Pp  .Pp
 Examples:  Examples:
 .Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q  .Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
 .Dl \&.Lk http://bsd.lv  .Dl \&.Lk http://bsd.lv
 .Pp  .Pp
 See also  See also
Line 3093  Newer groff and mandoc print
Line 3094  Newer groff and mandoc print
 and the arguments.  and the arguments.
 .It  .It
 .Sx \&Bl Fl column  .Sx \&Bl Fl column
 does not recognize trailing punctuation characters when they immediately  does not recognise trailing punctuation characters when they immediately
 precede tabulator characters, but treats them as normal text and  precede tabulator characters, but treats them as normal text and
 outputs a space before them.  outputs a space before them.
 .It  .It
Line 3205  The following features are unimplemented in mandoc:
Line 3206  The following features are unimplemented in mandoc:
 .Fl offset Ar center  .Fl offset Ar center
 and  and
 .Fl offset Ar right .  .Fl offset Ar right .
 Groff does not implement centered and flush-right rendering either,  Groff does not implement centred and flush-right rendering either,
 but produces large indentations.  but produces large indentations.
 .It  .It
 The  The
Line 3261  utility written by Kristaps Dzonsons appeared in
Line 3262  utility written by Kristaps Dzonsons appeared in
 The  The
 .Nm  .Nm
 reference was written by  reference was written by
 .An Kristaps Dzonsons Aq kristaps@bsd.lv .  .An Kristaps Dzonsons ,
   .Mt kristaps@bsd.lv .
Legend:
Removed from v.1.200  
changed lines
  Added in v.1.208
CVSweb