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

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

version 1.10, 2008/11/30 21:41:35 version 1.26, 2008/12/10 14:42:46
Line 1 
Line 1 
 .\"     $OpenBSD$  
 .\"  .\"
 .\" The following requests are required for all man pages.  
 .\"  
 .\" Remove `\&' from the line below.  
 .Dd $Mdocdate$  .Dd $Mdocdate$
 .Dt mdocml 1  .Dt mdocml 1
 .Os  .Os
Line 13 
Line 9 
 .\"  .\"
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .Nm mdocml  .Nm mdocml
 .Op Fl W  .Op Fl v
   .Op Fl W Ns Ar err...
 .Op Fl f Ar filter  .Op Fl f Ar filter
 .Op Fl o Ar outfile  .Op Fl o Ar outfile
 .Op Ar infile  .Op Ar infile
Line 21 
Line 18 
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm  .Nm
 utility parses  utility parses mdoc formatted manual source and passes results into an
 .Xr mdoc  output filter.  The current output filters are
 formatted manual source and passes results into the output filter  .Fl f Ar html
 dictated by  and
 .Fl f Ar filter .  .Fl f Ar xml .
 The only current output filter is  By default,
 .Ar xml ,  .Nm
 the default.  The arguments are as follows:  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"  .Bl -tag -width "\-o outfile"
 .It Fl f Ar filter  .It Fl f Ar filter
 The output filter name, which defaults to  The output filter name.
 .Ar xml .  
 .It Fl o Ar outfile  .It Fl o Ar outfile
 Place output in  Write output to
 .Ar outfile ,  .Ar outfile ,
 which may be  which may be
 .Qq \-  .Dq \-
 for stdout.  The default is stdout.  for stdout.  This is meaningless for
 .It Fl W  .Fl f Ar noop .
 Print compiler warnings to stderr.  .It Fl W Ns Ar err...
   Print warning messages.  If set to
   .Fl W Ns Ar all ,
   all warnings are printed; if
   .Fl W Ns Ar error ,
   warnings are considered errors and cause utility termination.  Multiple
   .Fl W
   arguments may be comma-separated, such as
   .Fl W Ns Ar error,all .
   .It Fl v
   Make warning and error messages verbose.
 .It Ar infile  .It Ar infile
 Read input from  Read input from
 .Ar infile ,  .Ar infile ,
 which may be  which may be
 .Qq \-  .Dq \-
 for stdin.  The default is stdin.  for stdin.
 .El  .El
   .Pp
   By default,
   .Nm
   reads from stdin and writes to stdout.
   .Pp
   .Ex -std mdocml
   .\"
   .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  .Ss XML Filter
 The XML filter, specified by  The XML filter, specified by
 .Fl f Ar xml ,  .Fl f Ar xml ,
 is the default filter.  It creates an XML document where element names are  produces correctly-formatted XML output.  This filter has no additional
 their respective roff macro names.  Each element name has an associated  arguments.
   .Pp
   The XML filter creates an XML document where element names are their respective
   roff macro names.  Each element name has an associated
 namespace, which is one of  namespace, which is one of
 .Qq block ,  .Dq block ,
 .Qq inline ,  .Dq head ,
   .Dq body ,
 or  or
 .Qq special ,  .Dq inline ,
 corresponding to the display mode of a node.  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  .Pp
 Sample output follows:  By default, the HTML filter produces HTML-4.01 strict mark-up.  The
 .Bd -literal  default CSS document styles the page as it would appear in a terminal
 <?xml version="1.0" encoding="UTF-8"?>  window.
 <block:mdoc>  .\"
   <block:Sh>  .Sh EXAMPLES
     <inline:Sh>NAME</inline:Sh> <inline:Nm>example</inline:Nm>  To produce an HTML4-strict document
     <inline:Nd>example text</inline:Nd>  .Pa mdocml.html
   </block:Sh>  for
 </block:mdoc>  .Pa mdocml.1
 .Ed  with the default, embedded style-sheet:
 .\" The following requests should be uncommented and used where appropriate.  .Pp
 .\" This next request is for sections 2, 3, and 9 function return values only.  .D1 % mdocml -fhtml -e -o mdocml.html mdocml.1
 .\" .Sh RETURN VALUES  .Pp
 .\" This next request is for sections 1, 6, 7 & 8 only.  To create an XML document on standard output from
 .\" .Sh ENVIRONMENT  .Pa mdocml.1
 .\" .Sh FILES  with the default namespace identifiers
 .\" .Sh EXAMPLES  .Li head ,
 .\" This next request is for sections 1, 4, 6, and 8 only.  .Li body ,
 .\" .Sh DIAGNOSTICS  .Li block
 .\" The next request is for sections 2, 3, and 9 error and signal handling only.  and
 .\" .Sh ERRORS  .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 ,
Line 91  Sample output follows:
Line 147  Sample output follows:
 The  The
 .Nm  .Nm
 utility was written by  utility was written by
 .An Em Kristaps Dzonsons Aq kristaps@kth.se .  .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\"  .\"
 .Sh CAVEATS  .Sh CAVEATS
 Most caveats of  Most caveats of
Line 102  or the necessary limitations of converting an ad hoc l
Line 158  or the necessary limitations of converting an ad hoc l
 structured ones:  structured ones:
 .Bl -enum -compact -offset indent  .Bl -enum -compact -offset indent
 .It  .It
 The engine doesn't understand  The engine doesn't understand the
 .Sq \&Xo  .Sq \&No ,
   .Sq \&Db ,
   .Sq \&Xc ,
 and  and
 .Sq \&Xc  .Sq \&Xo
 troff macros.  mdoc macros.
 .It  .It
 All macro arguments may be quoted, instead of only some.  All macro arguments may be quoted, instead of only some.
 .It  .It
 Blank lines raise warnings.  Blank lines raise errors.
 .It  .It
 If terminating punctuation is found, then  If terminating punctuation is found, then
 .Em all  .Em all
 remaining tokens are flushed after line scope is closed, not just the  remaining tokens are flushed after line scope is closed, not just the
 last one.  last one.
 .El  .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  .\" .Sh BUGS
Legend:
Removed from v.1.10  
changed lines
  Added in v.1.26
CVSweb