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

Diff for /mandoc/mandoc.1 between version 1.59 and 1.70

version 1.59, 2010/04/13 05:26:49 version 1.70, 2010/07/04 19:24:00
Line 51  Defaults to
Line 51  Defaults to
 .Fl m Ns Cm andoc .  .Fl m Ns Cm andoc .
 .It Fl O Ns Ar option  .It Fl O Ns Ar option
 Comma-separated output options.  Comma-separated output options.
 See  
 .Sx Output Options  
 for details.  
 .It Fl T Ns Ar output  .It Fl T Ns Ar output
 Output format.  Output format.
 See  See
Line 139  specified and
Line 136  specified and
 or  or
 .Fl m Ns Cm an  .Fl m Ns Cm an
 is specified, then this format is used exclusively.  is specified, then this format is used exclusively.
   .Ss Compiler Options
   Default
   .Xr mdoc 7
   and
   .Xr man 7
   compilation behaviour may be overridden with the
   .Fl f
   flag.
   .Bl -tag -width Ds
   .It Fl f Ns Cm ign-errors
   When parsing multiple files, don't halt when one errors out.
   Useful with
   .Fl T Ns Cm lint
   over a large set of manuals passed on the command line.
   .It Fl f Ns Cm ign-escape
   Ignore invalid escape sequences.
   This is the default, but the option can be used to override an earlier
   .Fl f Ns Cm strict .
   .It Fl f Ns Cm ign-scope
   When rewinding the scope of a block macro, forces the compiler to ignore
   scope violations.
   This can seriously mangle the resulting tree.
   .Pq mdoc only
   .It Fl f Ns Cm no-ign-escape
   Do not ignore invalid escape sequences.
   .It Fl f Ns Cm no-ign-macro
   Do not ignore unknown macros at the start of input lines.
   .It Fl f Ns Cm strict
   Implies
   .Fl f Ns Cm no-ign-escape
   and
   .Fl f Ns Cm no-ign-macro .
   .El
 .Ss Output Formats  .Ss Output Formats
 The  The
 .Nm  .Nm
 utility accepts the following  utility accepts the following
 .Fl T  .Fl T
 arguments (see  arguments, which correspond to output modes:
 .Sx OUTPUT ) :  
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Fl T Ns Cm ascii  .It Fl T Ns Cm ascii
 Produce 7-bit ASCII output, backspace-encoded for bold and underline  Produce 7-bit ASCII output, backspace-encoded for bold and underline
Line 163  Implies
Line 192  Implies
 .Fl W Ns Cm all  .Fl W Ns Cm all
 and  and
 .Fl f Ns Cm strict .  .Fl f Ns Cm strict .
   .It Fl T Ns Cm ps
   Produce PostScript output.
   See
   .Sx PostScript Output .
 .It Fl T Ns Cm tree  .It Fl T Ns Cm tree
 Produce an indented parse tree.  Produce an indented parse tree.
 .It Fl T Ns Cm xhtml  .It Fl T Ns Cm xhtml
Line 173  See
Line 206  See
 .Pp  .Pp
 If multiple input files are specified, these will be processed by the  If multiple input files are specified, these will be processed by the
 corresponding filter in-order.  corresponding filter in-order.
 .Ss Compiler Options  
 Default compiler behaviour may be overridden with the  
 .Fl f  
 flag.  
 .Bl -tag -width Ds  
 .It Fl f Ns Cm ign-errors  
 When parsing multiple files, don't halt when one errors out.  
 Useful with  
 .Fl T Ns Cm lint  
 over a large set of manuals passed on the command line.  
 .It Fl f Ns Cm ign-escape  
 Ignore invalid escape sequences.  
 This is the default, but the option can be used to override an earlier  
 .Fl f Ns Cm strict .  
 .It Fl f Ns Cm ign-scope  
 When rewinding the scope of a block macro, forces the compiler to ignore  
 scope violations.  
 This can seriously mangle the resulting tree.  
 .Pq mdoc only  
 .It Fl f Ns Cm no-ign-chars  
 Do not ignore disallowed characters.  
 .It Fl f Ns Cm no-ign-escape  
 Do not ignore invalid escape sequences.  
 .It Fl f Ns Cm no-ign-macro  
 Do not ignore unknown macros at the start of input lines.  
 .It Fl f Ns Cm strict  
 Implies  
 .Fl f Ns Cm no-ign-escape ,  
 .Fl f Ns Cm no-ign-macro ,  
 and  
 .Fl f Ns Cm no-ign-chars .  
 .El  
 .Ss Output Options  
 For the time being, only  
 .Fl T Ns Ar html  
 and  
 .Fl T Ns Ar xhtml  
 accept output options:  
 .Bl -tag -width Ds  
 .It Fl O Ns Cm includes Ns = Ns Ar fmt  
 The string  
 .Ar fmt ,  
 for example,  
 .Ar ../src/%I.html ,  
 is used as a template for linked header files (usually via the  
 .Sq \&In  
 macro).  
 Instances of  
 .Sq \&%I  
 are replaced with the include filename.  
 The default is not to present a  
 hyperlink.  
 .It Fl O Ns Cm man Ns = Ns Ar fmt  
 The string  
 .Ar fmt ,  
 for example,  
 .Ar ../html%S/%N.%S.html ,  
 is used as a template for linked manuals (usually via the  
 .Sq \&Xr  
 macro).  
 Instances of  
 .Sq \&%N  
 and  
 .Sq %S  
 are replaced with the linked manual's name and section, respectively.  
 If no section is included, section 1 is assumed.  
 The default is not to  
 present a hyperlink.  
 .It Fl O Ns Cm style Ns = Ns Ar style.css  
 The file  
 .Ar style.css  
 is used for an external style-sheet.  
 This must be a valid absolute or  
 relative URI.  
 .El  
 .Sh OUTPUT  
 This section documents output details of  
 .Nm .  
 In general, output conforms to the traditional manual style of a header,  
 a body composed of sections and sub-sections, and a footer.  
 .Pp  
 The text style of output characters (non-macro characters, punctuation,  
 and white-space) is dictated by context.  
 .Pp  
 White-space is generally stripped from input.  
 This can be changed with  
 character escapes (specified in  
 .Xr mandoc_char 7 )  
 or literal modes (specified in  
 .Xr mdoc 7  
 and  
 .Xr man 7 ) .  
 .Pp  
 If non-macro punctuation is set apart from words, such as in the phrase  
 .Dq to be \&, or not to be ,  
 it's processed by  
 .Nm ,  
 regardless of output format, according to the following rules:  opening  
 punctuation  
 .Po  
 .Sq \&( ,  
 .Sq \&[ ,  
 and  
 .Sq \&{  
 .Pc  
 is not followed by a space; closing punctuation  
 .Po  
 .Sq \&. ,  
 .Sq \&, ,  
 .Sq \&; ,  
 .Sq \&: ,  
 .Sq \&? ,  
 .Sq \&! ,  
 .Sq \&) ,  
 .Sq \&]  
 and  
 .Sq \&}  
 .Pc  
 is not preceded by white-space.  
 .Pp  
 If the input is  
 .Xr mdoc 7 ,  
 however, these rules are also applied to macro arguments when appropriate.  
 .Ss ASCII Output  .Ss ASCII Output
 Output produced by  Output produced by
 .Fl T Ns Cm ascii ,  .Fl T Ns Cm ascii ,
Line 319  are rendered best-effort in an ASCII equivalent.
Line 229  are rendered best-effort in an ASCII equivalent.
 .Pp  .Pp
 Output width is limited to 78 visible columns unless literal input lines  Output width is limited to 78 visible columns unless literal input lines
 exceed this limit.  exceed this limit.
   .Pp
   The following
   .Fl O
   arguments are accepted:
   .Bl -tag -width Ds
   .It Cm width Ns = Ns Ar width
   The output width is set to
   .Ar width ,
   which will normalise to \(>=60.
   .El
 .Ss HTML Output  .Ss HTML Output
 Output produced by  Output produced by
 .Fl T Ns Cm html  .Fl T Ns Cm html
Line 336  cause rendered documents to appear as they do in
Line 256  cause rendered documents to appear as they do in
 .Fl T Ns Cm ascii .  .Fl T Ns Cm ascii .
 .Pp  .Pp
 Special characters are rendered in decimal-encoded UTF-8.  Special characters are rendered in decimal-encoded UTF-8.
   .Pp
   The following
   .Fl O
   arguments are accepted:
   .Bl -tag -width Ds
   .It Cm includes Ns = Ns Ar fmt
   The string
   .Ar fmt ,
   for example,
   .Ar ../src/%I.html ,
   is used as a template for linked header files (usually via the
   .Sq \&In
   macro).
   Instances of
   .Sq \&%I
   are replaced with the include filename.
   The default is not to present a
   hyperlink.
   .It Cm man Ns = Ns Ar fmt
   The string
   .Ar fmt ,
   for example,
   .Ar ../html%S/%N.%S.html ,
   is used as a template for linked manuals (usually via the
   .Sq \&Xr
   macro).
   Instances of
   .Sq \&%N
   and
   .Sq %S
   are replaced with the linked manual's name and section, respectively.
   If no section is included, section 1 is assumed.
   The default is not to
   present a hyperlink.
   .It Cm style Ns = Ns Ar style.css
   The file
   .Ar style.css
   is used for an external style-sheet.
   This must be a valid absolute or
   relative URI.
   .El
   .Ss PostScript Output
   PostScript
   .Qq Adobe-3.0
   Level-2 pages may be generated by
   .Fl T Ns Cm ps .
   Output pages default to letter sized and are rendered in the Times font
   family, 11-point.
   Margins are calculated as 1/9 the page length and width.
   .Pp
   Special characters are rendered as in
   .Sx ASCII Output .
   .Pp
   The following
   .Fl O
   arguments are accepted:
   .Bl -tag -width Ds
   .It Cm paper Ns = Ns Ar name
   The paper size
   .Ar name
   may be one of
   .Ar a3 ,
   .Ar a4 ,
   .Ar a5 ,
   .Ar legal ,
   or
   .Ar letter .
   You may also manually specify dimensions as
   .Ar NNxNN ,
   width by height in millimetres.
   If an unknown value is encountered,
   .Ar letter
   is used.
   .El
 .Ss XHTML Output  .Ss XHTML Output
 Output produced by  Output produced by
 .Fl T Ns Cm xhtml  .Fl T Ns Cm xhtml
Line 360  as the style-sheet:
Line 354  as the style-sheet:
 To check over a large set of manuals:  To check over a large set of manuals:
 .Pp  .Pp
 .Dl $ mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`  .Dl $ mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
   .Pp
   To produce a series of PostScript manuals for A4 paper:
   .Pp
   .D1 $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
 .Sh COMPATIBILITY  .Sh COMPATIBILITY
 This section summarises  This section summarises
 .Nm  .Nm
Legend:
Removed from v.1.59  
changed lines
  Added in v.1.70
CVSweb