mdoctree.1

   1 .\" $Id: mdoctree.1,v 1.5 2009/03/08 18:02:36 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the
   7 .\" above copyright notice and this permission notice appear in all
   8 .\" copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
  11 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
  12 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
  13 .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  14 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  15 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  16 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17 .\" PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .Dd $Mdocdate: March 8 2009 $
  20 .Dt mdoctree 1
  21 .Os
  22 .\" SECTION
  23 .Sh NAME
  24 .Nm mdoctree
  25 .Nd mdoc macro compiler
  26 .\" SECTION
  27 .Sh SYNOPSIS
  28 .Nm mdoctree
  29 .Op Fl vV
  30 .Op Fl f Ns Ar options...
  31 .Op Fl W Ns Ar err...
  32 .Op Ar infile
  33 .\" SECTION
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 utility parses a BSD
  38 .Dq mdoc
  39 manual pages and prints its syntax tree.  It's commonly used to see the
  40 syntax tree of a document when building new
  41 .Xr mdoc 3
  42 utilities.  The arguments are as follows:
  43 .Bl -tag -width XXXXXXXXXXXX
  44 .\" ITEM
  45 .It Fl v
  46 Print verbose parsing output.
  47 .\" ITEM
  48 .It Fl V
  49 Print version and exit.
  50 .\" ITEM
  51 .It Fl f Ns Ar option...
  52 Override default compiler behaviour.  See
  53 .Sx Compiler Options
  54 for details.
  55 .\" ITEM
  56 .It Fl W Ns Ar err...
  57 Print warning messages.  May be set to
  58 .Fl W Ns Ar all
  59 for all warnings,
  60 .Ar compat
  61 for groff/troff-compatibility warnings, or
  62 .Ar syntax
  63 for syntax warnings.  If
  64 .Fl W Ns Ar error
  65 is specified, warnings are considered errors and cause utility
  66 termination.  Multiple
  67 .Fl W
  68 arguments may be comma-separated, such as
  69 .Fl W Ns Ar error,all .
  70 .\" ITEM
  71 .It Ar infile
  72 Read input from
  73 .Ar infile ,
  74 which may be
  75 .Dq \-
  76 for stdin.
  77 .El
  78 .\" PARAGRAPH
  79 .Pp
  80 The
  81 .Nm
  82 utility is a formatting front-end for
  83 .Xr mdoc 3 ,
  84 which parses the
  85 .Dq mdoc
  86 input, documented at
  87 .Xr mdoc 7
  88 and
  89 .Xr mdoc.samples 7 ,
  90 into an abstract syntax tree.  By default, it reads from stdin and
  91 prints the syntax tree to stdout.
  92 .\" PARAGRAPH
  93 .Pp
  94 .Ex -std mdoctree
  95 .\" SUB-SECTION
  96 .Ss Compiler Options
  97 Default compiler behaviour may be overriden with the
  98 .Fl f
  99 flag.  The available options are as follows:
 100 .Bl -tag -width XXXXXXXXXXXX -offset XXXX
 101 .It Fl f Ns Ar ign-scope
 102 When rewinding the scope of a block macro, forces the compiler to ignore
 103 scope violations.  This can seriously mangle the resulting tree.
 104 .It Fl f Ns Ar ign-escape
 105 Ignore invalid escape sequences.
 106 .El
 107 .\" PARAGRAPH
 108 .Pp
 109 As with the
 110 .Fl W
 111 flag, multiple
 112 .Fl f
 113 options may be grouped and delimited with a comma.  Using
 114 .Fl f Ns Ar ign-scope,ign-escape ,
 115 for example, will try to ignore scope and character-escape errors.
 116 .\" SECTION
 117 .Sh EXAMPLES
 118 To validate this manual page:
 119 .\" PARAGRAPH
 120 .Pp
 121 .D1 % mdoctree \-Wall,error mdoctree.1
 122 .\" SECTION
 123 .Sh SEE ALSO
 124 .Xr mdocterm 1 ,
 125 .Xr mdoclint 1 ,
 126 .Xr mdoc.samples 7 ,
 127 .Xr mdoc 7 ,
 128 .Xr mdoc 3
 129 .\"
 130 .Sh AUTHORS
 131 The
 132 .Nm
 133 utility was written by
 134 .An Kristaps Dzonsons Aq kristaps@kth.se .
 135 .\" SECTION
 136 .Sh CAVEATS
 137 See
 138 .Xr mdoc 3
 139 for a list of bugs, caveats, and incomplete macros.