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

Diff for /mandoc/Attic/mdocml.1 between version 1.26 and 1.31

version 1.26, 2008/12/10 14:42:46 version 1.31, 2009/02/20 23:35:36
Line 2 
Line 2 
 .Dd $Mdocdate$  .Dd $Mdocdate$
 .Dt mdocml 1  .Dt mdocml 1
 .Os  .Os
 .\"  .\" SECTION
 .Sh NAME  .Sh NAME
 .Nm mdocml  .Nm mdocml
 .Nd compile manpage source into mark-up language  .Nd mdoc macro compiler
 .\"  .\" SECTION
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .Nm mdocml  .Nm mdocml
 .Op Fl v  .Op Fl v
 .Op Fl W Ns Ar err...  .Op Fl W Ns Ar err...
 .Op Fl f Ar filter  
 .Op Fl o Ar outfile  
 .Op Ar infile  .Op Ar infile
 .\"  .\" SECTION
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm  .Nm
 utility parses mdoc formatted manual source and passes results into an  utility interfaces the
 output filter.  The current output filters are  .Xr mdoc 3
 .Fl f Ar html  library to scan, parse and validate mdoc-macro documents.  Arguments
 and  follow:
 .Fl f Ar xml .  .Bl -tag -width "\-Werr... "
 By default,  
 .Nm  
 only validates its input. This may be explicitly directed with  
 .Fl f Ar noop .  
 Arguments common to all filters follow:  
 .Bl -tag -width "\-o outfile"  
 .It Fl f Ar filter  
 The output filter name.  
 .It Fl o Ar outfile  
 Write output to  
 .Ar outfile ,  
 which may be  
 .Dq \-  
 for stdout.  This is meaningless for  
 .Fl f Ar noop .  
 .It Fl W Ns Ar err...  .It Fl W Ns Ar err...
 Print warning messages.  If set to  Print warning messages.  May be set to
 .Fl W Ns Ar all ,  .Fl W Ns Ar all
 all warnings are printed; if  for all warnings,
 .Fl W Ns Ar error ,  .Ar compat
 warnings are considered errors and cause utility termination.  Multiple  for groff/troff-compatibility warnings, or
   .Ar syntax
   for syntax warnings.  If
   .Fl W Ns Ar error
   is specified, warnings are considered errors and cause utility
   termination.  Multiple
 .Fl W  .Fl W
 arguments may be comma-separated, such as  arguments may be comma-separated, such as
 .Fl W Ns Ar error,all .  .Fl W Ns Ar error,all .
 .It Fl v  .It Fl v
 Make warning and error messages verbose.  Print verbose parsing output.
 .It Ar infile  .It Ar infile
 Read input from  Read input from
 .Ar infile ,  .Ar infile ,
Line 56  which may be 
Line 44  which may be 
 .Dq \-  .Dq \-
 for stdin.  for stdin.
 .El  .El
   .\" PARAGRAPH
 .Pp  .Pp
   Parsing and validation rules are drawn entirely from the
   .Xr mdoc 7
   and
   .Xr mdoc.samples 7
   manuals.
   .\" PARAGRAPH
   .Pp
 By default,  By default,
 .Nm  .Nm
 reads from stdin and writes to stdout.  reads from stdin, writes messages to stdout, and writes errors and
   warnings to stderr.
   .\" PARAGRAPH
 .Pp  .Pp
 .Ex -std mdocml  .Ex -std mdocml
 .\"  .\" PARAGRAPH
 .Ss Noop Filter  
 The default noop  
 .Dq validating  
 filter simply validates its input; it produces no output beyond error  
 and warning messages.  
 .\"  
 .Ss XML Filter  
 The XML filter, specified by  
 .Fl f Ar xml ,  
 produces correctly-formatted XML output.  This filter has no additional  
 arguments.  
 .Pp  .Pp
 The XML filter creates an XML document where element names are their respective  .Nm
 roff macro names.  Each element name has an associated  is
 namespace, which is one of  .Ud
 .Dq block ,  .\" SECTION
 .Dq head ,  
 .Dq body ,  
 or  
 .Dq inline ,  
 corresponding to the display mode of a node.  The document root is  
 always the  
 .Dq mdoc  
 element, in the default namespace; the  
 .Dq head  
 namespace is for block headers (such as  
 .Sq .Ss  
 and  
 .Sq .Sh ) ;  
 the  
 .Dq body  
 namespace is for block bodies; and the  
 .Dq inline  
 namespace is for in-line elements (such as  
 .Sq .Em ) .  
 .\"  
 .Ss HTML Filter  
 The HTML filter, specified by  
 .Fl f Ar html ,  
 accepts the following filter-specific arguments:  
 .Bl -tag -width "\-c css"  
 .It Fl c Ar css  
 The CSS file location, which defaults to  
 .Ar mdocml.css .  
 .It Fl e  
 Whether to embed the CSS file into the HTML prologue.  
 .El  
 .Pp  
 By default, the HTML filter produces HTML-4.01 strict mark-up.  The  
 default CSS document styles the page as it would appear in a terminal  
 window.  
 .\"  
 .Sh EXAMPLES  .Sh EXAMPLES
 To produce an HTML4-strict document  To validate this manual page:
 .Pa mdocml.html  .\" PARAGRAPH
 for  
 .Pa mdocml.1  
 with the default, embedded style-sheet:  
 .Pp  .Pp
 .D1 % mdocml -fhtml -e -o mdocml.html mdocml.1  .D1 % mdocml \-Wall,error mdocml.1
 .Pp  .\" SECTION
 To create an XML document on standard output from  
 .Pa mdocml.1  
 with the default namespace identifiers  
 .Li head ,  
 .Li body ,  
 .Li block  
 and  
 .Li inline :  
 .Pp  
 .D1 % mdocml -Wall,error -fxml mdocml.1  
 .Pp  
 The previous example will also halt on input document warnings.  
 .\"  
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr groff 1 ,  .Xr groff 1 ,
 .Xr mdoc.samples 7 ,  .Xr mdoc.samples 7 ,
 .Xr mdoc 7  .Xr mdoc 7 ,
 .\" .Sh STANDARDS  .Xr mdoc 3
 .\" .Sh HISTORY  .\"
 .Sh AUTHORS  .Sh AUTHORS
 The  The
 .Nm  .Nm
 utility was written by  utility was written by
 .An Kristaps Dzonsons Aq kristaps@kth.se .  .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\"  .\" SECTION
 .Sh CAVEATS  .Sh CAVEATS
 Most caveats of  See
 .Nm  .Xr mdoc 3
 stem from ambiguities in  for a list of bugs, caveats, and incomplete macros.
 .Xr mdoc 7  
 or the necessary limitations of converting an ad hoc language into  
 structured ones:  
 .Bl -enum -compact -offset indent  
 .It  
 The engine doesn't understand the  
 .Sq \&No ,  
 .Sq \&Db ,  
 .Sq \&Xc ,  
 and  
 .Sq \&Xo  
 mdoc macros.  
 .It  
 All macro arguments may be quoted, instead of only some.  
 .It  
 Blank lines raise errors.  
 .It  
 If terminating punctuation is found, then  
 .Em all  
 remaining tokens are flushed after line scope is closed, not just the  
 last one.  
 .El  
 .Pp  
 The roff engine in  
 .Nm  
 produces text in-line; thus, output may already be partially written by  
 the time an error is encountered.  
 .\" .Sh BUGS  
Legend:
Removed from v.1.26  
changed lines
  Added in v.1.31
CVSweb