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

Diff for /mandoc/Attic/mdocml.1 between version 1.11 and 1.29

version 1.11, 2008/11/30 23:05:57 version 1.29, 2009/01/20 13:44:05
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
 .\"  .\"
 .Sh NAME  .Sh NAME
 .Nm mdocml  .Nm mdocml
 .Nd compile manpage source into mark-up language  .Nd mdoc macro compiler
 .\"  .\"
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .Nm mdocml  .Nm mdocml
 .Op Fl W  .Op Fl v
 .Op Fl f Ar filter  .Op Fl W Ns Ar err...
 .Op Fl o Ar outfile  
 .Op Ar infile  .Op Ar infile
 .\"  .\"
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm  .Nm
 utility parses  utility interfaces the
 .Xr mdoc  .Xr mdoc 3
 formatted manual source and passes results into the output filter  library to scan, parse and validate mdoc-macro documents.  Arguments
 dictated by  follow:
 .Fl f Ar filter .  .Bl -tag -width "\-Werr... "
 The only current output filter is  .It Fl W Ns Ar err...
 .Ar xml ,  Print warning messages.  May be set to
 the default.  The arguments are as follows:  .Fl W Ns Ar all
 .Bl -tag -width "\-o outfile"  for all warnings,
 .It Fl f Ar filter  .Ar compat
 The output filter name, which defaults to  for groff/troff-compatibility warnings, or
 .Ar xml .  .Ar syntax
 .It Fl o Ar outfile  for syntax warnings.  If
 Place output in  .Fl W Ns Ar error
 .Ar outfile ,  is specified, warnings are considered errors and cause utility
 which may be  termination.  Multiple
 .Qq \-  .Fl W
 for stdout.  The default is stdout.  arguments may be comma-separated, such as
 .It Fl W  .Fl W Ns Ar error,all .
 Print compiler warnings to stderr.  .It Fl v
   Print verbose parsing output.
 .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
 .Ss XML Filter  .Pp
 The XML filter, specified by  Parsing and validation rules are drawn entirely from the
 .Fl f Ar xml ,  .Xr mdoc 7
 is the default filter.  It creates an XML document where element names are  and
 their respective roff macro names.  Each element name has an associated  .Xr mdoc.samples 7
 namespace, which is one of  manuals.
 .Qq block ,  .Pp
 .Qq inline ,  By default,
 or  .Nm
 .Qq special ,  reads from stdin, writes messages to stdout, and writes errors and
 corresponding to the display mode of a node.  warnings to stderr.
 .\" 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.  .Ex -std mdocml
 .\" .Sh RETURN VALUES  .Pp
 .\" This next request is for sections 1, 6, 7 & 8 only.  .Nm
 .\" .Sh ENVIRONMENT  is
 .\" .Sh FILES  .Ud
 .\" .Sh EXAMPLES  .\"
 .\" This next request is for sections 1, 4, 6, and 8 only.  .Sh EXAMPLES
 .\" .Sh DIAGNOSTICS  To validate this manual page:
 .\" The next request is for sections 2, 3, and 9 error and signal handling only.  .Pp
 .\" .Sh ERRORS  .D1 % mdocml \-Wall,error mdocml.1
   .\"
 .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 ,
   .Xr mdoc 3
 .\" .Sh STANDARDS  .\" .Sh STANDARDS
 .\" .Sh HISTORY  .\" .Sh HISTORY
 .Sh AUTHORS  .Sh AUTHORS
 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  The most glaring short-coming of
 .Nm  .Nm
 stem from ambiguities in  is that it doesn't yet support the
 .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  
 .Sq \&Xo  
 and  
 .Sq \&Xc  .Sq \&Xc
 troff macros.  and
 .It  .Sq \&Xo
 All macro arguments may be quoted, instead of only some.  macros when used to extend the line arguments to
 .It  .Sq \&It ;
 Blank lines raise warnings.  in effect, trampling the body section.  We note that this is explicitly
 .It  discouraged in
 If terminating punctuation is found, then  .Xr mdoc.samples 7 ,
 .Em all  but in practice used quite often.
 remaining tokens are flushed after line scope is closed, not just the  
 last one.  
 .El  
 .\" .Sh BUGS  .\" .Sh BUGS
Legend:
Removed from v.1.11  
changed lines
  Added in v.1.29
CVSweb