Return to mdoctree.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mdoctree.1, Revision 1.5

1.5     ! kristaps    1: .\" $Id: mdoctree.1,v 1.4 2009/02/23 13:05:06 kristaps Exp $
1.1       kristaps    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$
                     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
1.5     ! kristaps   29: .Op Fl vV
        !            30: .Op Fl f Ns Ar options...
1.1       kristaps   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
1.3       kristaps   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:
1.5     ! kristaps   43: .Bl -tag -width XXXXXXXXXXXX
1.1       kristaps   44: .\" ITEM
                     45: .It Fl v
                     46: Print verbose parsing output.
                     47: .\" ITEM
1.5     ! kristaps   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
1.1       kristaps   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
1.2       kristaps   79: .Pp
1.1       kristaps   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 ,
1.5     ! kristaps   90: into an abstract syntax tree.  By default, it reads from stdin and
        !            91: prints the syntax tree to stdout.
1.1       kristaps   92: .\" PARAGRAPH
                     93: .Pp
                     94: .Ex -std mdoctree
1.5     ! kristaps   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
1.1       kristaps  107: .\" PARAGRAPH
                    108: .Pp
1.5     ! kristaps  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.
1.1       kristaps  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 ,
1.4       kristaps  125: .Xr mdoclint 1 ,
1.1       kristaps  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.