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

Diff for /mandoc/mandoc.1 between version 1.65 and 1.66

version 1.65, 2010/06/29 14:18:05 version 1.66, 2010/06/29 14:55:41
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 177  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  .Ss ASCII Output
 Default compiler behaviour may be overridden with the  Output produced by
 .Fl f  .Fl T Ns Cm ascii ,
 flag.  which is the default, is rendered in standard 7-bit ASCII documented in
   .Xr ascii 7 .
   .Pp
   Font styles are applied by using back-spaced encoding such that an
   underlined character
   .Sq c
   is rendered as
   .Sq _ Ns \e[bs] Ns c ,
   where
   .Sq \e[bs]
   is the back-space character number 8.
   Emboldened characters are rendered as
   .Sq c Ns \e[bs] Ns c .
   .Pp
   The special characters documented in
   .Xr mandoc_char 7
   are rendered best-effort in an ASCII equivalent.
   .Pp
   Output width is limited to 78 visible columns unless literal input lines
   exceed this limit.
   .Pp
   The following
   .Fl O
   arguments are accepted:
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Fl f Ns Cm ign-errors  .It Cm width Ns = Ns Ar width
 When parsing multiple files, don't halt when one errors out.  The output width is set to
 Useful with  .Ar width ,
 .Fl T Ns Cm lint  which will normalise to \(>=60.
 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  .El
 .Ss Output Options  .Ss HTML Output
   Output produced by
   .Fl T Ns Cm html
   conforms to HTML-4.01 strict.
   .Pp
   Font styles and page structure are applied using CSS2.
   By default, no font style is applied to any text,
   although CSS2 is hard-coded to format
   the basic structure of output.
   .Pp
 The  The
 .Fl T Ns Ar html  .Pa example.style.css
 and  file documents the range of styles applied to output and, if used, will
 .Fl T Ns Ar xhtml  cause rendered documents to appear as they do in
 modes accept the following  .Fl T Ns Cm ascii .
   .Pp
   Special characters are rendered in decimal-encoded UTF-8.
   .Pp
   The following
 .Fl O  .Fl O
 arguments:  arguments are accepted:
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Cm includes Ns = Ns Ar fmt  .It Cm includes Ns = Ns Ar fmt
 The string  The string
Line 251  is used for an external style-sheet.
Line 297  is used for an external style-sheet.
 This must be a valid absolute or  This must be a valid absolute or
 relative URI.  relative URI.
 .El  .El
 .Pp  
 The  
 .Fl T Ns Ar ascii  
 mode accepts the following  
 .Fl O  
 argument:  
 .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  
 .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  
 Output produced by  
 .Fl T Ns Cm ascii ,  
 which is the default, is rendered in standard 7-bit ASCII documented in  
 .Xr ascii 7 .  
 .Pp  
 Font styles are applied by using back-spaced encoding such that an  
 underlined character  
 .Sq c  
 is rendered as  
 .Sq _ Ns \e[bs] Ns c ,  
 where  
 .Sq \e[bs]  
 is the back-space character number 8.  
 Emboldened characters are rendered as  
 .Sq c Ns \e[bs] Ns c .  
 .Pp  
 The special characters documented in  
 .Xr mandoc_char 7  
 are rendered best-effort in an ASCII equivalent.  
 .Pp  
 Output width is limited to 78 visible columns unless literal input lines  
 exceed this limit.  
 .Ss HTML Output  
 Output produced by  
 .Fl T Ns Cm html  
 conforms to HTML-4.01 strict.  
 .Pp  
 Font styles and page structure are applied using CSS2.  
 By default, no font style is applied to any text,  
 although CSS2 is hard-coded to format  
 the basic structure of output.  
 .Pp  
 The  
 .Pa example.style.css  
 file documents the range of styles applied to output and, if used, will  
 cause rendered documents to appear as they do in  
 .Fl T Ns Cm ascii .  
 .Pp  
 Special characters are rendered in decimal-encoded UTF-8.  
 .Ss PostScript Output  .Ss PostScript Output
 PostScript  PostScript
 .Qq Adobe-3.0  .Qq Adobe-3.0
 Level-2 pages may be generated by  Level-2 pages may be generated by
 .Fl T Ns Cm ps .  .Fl T Ns Cm ps .
 Output pages are US-letter sized (215.9 x 279.4 mm) and rendered in  Output pages are US-letter sized and rendered in fixed, 10-point Courier
 fixed, 10-point Courier font.  font.
   .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 a4
   or
   .Ar letter .
   .El
 .Ss XHTML Output  .Ss XHTML Output
 Output produced by  Output produced by
 .Fl T Ns Cm xhtml  .Fl T Ns Cm xhtml
Line 382  as the style-sheet:
Line 344  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.65  
changed lines
  Added in v.1.66
CVSweb