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

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

version 1.1, 2008/11/22 14:53:29 version 1.26, 2008/12/10 14:42:46
Line 1 
Line 1 
 .\"     $OpenBSD$  
 .\"  .\"
 .\" The following requests are required for all man pages.  .Dd $Mdocdate$
 .\"  .Dt mdocml 1
 .\" Remove `\&' from the line below.  
 .Dd $\&Mdocdate$  
 .Dt NAME SECTION#  
 .Os  .Os
   .\"
 .Sh NAME  .Sh NAME
 .Nm program  .Nm mdocml
 .Nd one line about what it does  .Nd compile manpage source into mark-up language
   .\"
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .\" For a program:  program [-abc] file ...  .Nm mdocml
 .Nm program  .Op Fl v
 .Op Fl abc  .Op Fl W Ns Ar err...
 .Ar  .Op Fl f Ar filter
   .Op Fl o Ar outfile
   .Op Ar infile
   .\"
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm  .Nm
 utility processes files ...  utility parses mdoc formatted manual source and passes results into an
 something  output filter.  The current output filters are
 something.  .Fl f Ar html
 .\" The following requests should be uncommented and used where appropriate.  and
 .\" This next request is for sections 2, 3, and 9 function return values only.  .Fl f Ar xml .
 .\" .Sh RETURN VALUES  By default,
 .\" This next request is for sections 1, 6, 7 & 8 only.  .Nm
 .\" .Sh ENVIRONMENT  only validates its input. This may be explicitly directed with
 .\" .Sh FILES  .Fl f Ar noop .
 .\" .Sh EXAMPLES  Arguments common to all filters follow:
 .\" This next request is for sections 1, 4, 6, and 8 only.  .Bl -tag -width "\-o outfile"
 .\" .Sh DIAGNOSTICS  .It Fl f Ar filter
 .\" The next request is for sections 2, 3, and 9 error and signal handling only.  The output filter name.
 .\" .Sh ERRORS  .It Fl o Ar outfile
 .\" .Sh SEE ALSO  Write output to
 .\" .Xr foobar 1  .Ar outfile ,
   which may be
   .Dq \-
   for stdout.  This is meaningless for
   .Fl f Ar noop .
   .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
   Read input from
   .Ar infile ,
   which may be
   .Dq \-
   for stdin.
   .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
   The XML filter, specified by
   .Fl f Ar xml ,
   produces correctly-formatted XML output.  This filter has no additional
   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
   .Dq block ,
   .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
   To produce an HTML4-strict document
   .Pa mdocml.html
   for
   .Pa mdocml.1
   with the default, embedded style-sheet:
   .Pp
   .D1 % mdocml -fhtml -e -o mdocml.html mdocml.1
   .Pp
   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
   .Xr groff 1 ,
   .Xr mdoc.samples 7 ,
   .Xr mdoc 7
 .\" .Sh STANDARDS  .\" .Sh STANDARDS
 .\" .Sh HISTORY  .\" .Sh HISTORY
 .\" .Sh AUTHORS  .Sh AUTHORS
 .\" .Sh CAVEATS  The
   .Nm
   utility was written by
   .An Kristaps Dzonsons Aq kristaps@kth.se .
   .\"
   .Sh CAVEATS
   Most caveats of
   .Nm
   stem from ambiguities in
   .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  .\" .Sh BUGS
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.26
CVSweb