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

Annotation of docbook2mdoc/docbook2mdoc.1, Revision 1.14

1.14    ! schwarze    1: .\" $Id: docbook2mdoc.1,v 1.13 2019/04/23 15:47:23 schwarze Exp $
1.1       kristaps    2: .\"
                      3: .\" Copyright (c) 2014 Kristaps Dzonsons <kristaps@bsd.lv>
1.11      schwarze    4: .\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
1.1       kristaps    5: .\"
                      6: .\" Permission to use, copy, modify, and distribute this software for any
                      7: .\" purpose with or without fee is hereby granted, provided that the above
                      8: .\" copyright notice and this permission notice appear in all copies.
                      9: .\"
                     10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     17: .\"
1.14    ! schwarze   18: .Dd $Mdocdate: April 23 2019 $
1.1       kristaps   19: .Dt DOCBOOK2MDOC 1
                     20: .Os
                     21: .Sh NAME
                     22: .Nm docbook2mdoc
1.11      schwarze   23: .Nd convert DocBook to mdoc
1.1       kristaps   24: .Sh SYNOPSIS
1.2       kristaps   25: .Nm docbook2mdoc
1.9       schwarze   26: .Op Fl W
1.12      schwarze   27: .Op Fl T Cm mdoc | tree | lint
1.1       kristaps   28: .Op Ar file
                     29: .Sh DESCRIPTION
                     30: The
                     31: .Nm
1.11      schwarze   32: utility reads DocBook input from a
1.1       kristaps   33: .Ar file
1.11      schwarze   34: and translates it to
1.1       kristaps   35: .Xr mdoc 7
1.6       kristaps   36: and
1.11      schwarze   37: .Xr eqn 7 .
                     38: If
1.1       kristaps   39: .Ar file
1.11      schwarze   40: is
                     41: .Sq Cm \-
                     42: or omitted, standard input is used.
1.8       schwarze   43: .Pp
1.12      schwarze   44: The options are as follows:
                     45: .Bl -tag -width 2n
                     46: .It Fl T
                     47: Select the output mode.
                     48: The following arguments are supported:
                     49: .Bl -tag -width 4n
                     50: .It Cm mdoc
                     51: Translate the input to
                     52: .Xr mdoc 7 .
                     53: This is the default.
                     54: .It Cm tree
                     55: Dump a human-readable representation of the parse tree.
                     56: Each output line shows one tree node.
                     57: Child nodes are indented with respect to their parent node.
                     58: The columns are:
                     59: .Bl -enum -width 2n
                     60: .It
1.14    ! schwarze   61: An asterisk if the node starts a new text line,
        !            62: or a hyphen if the node follows the previous node
1.12      schwarze   63: without intervening whitespace.
                     64: .It
                     65: The node type.
                     66: .It
                     67: For text nodes, the text contents.
                     68: For other nodes, the attributes, if any.
                     69: .El
                     70: .It Cm lint
                     71: Do not produce any output, only error messages.
                     72: Can be combined with
                     73: .Fl W .
                     74: .El
1.4       kristaps   75: .It Fl W
1.10      schwarze   76: Report warnings on standard error output, and if any occur, raise the
                     77: .Sx EXIT STATUS
                     78: to at least 2.
1.4       kristaps   79: .El
1.2       kristaps   80: .Pp
1.11      schwarze   81: A subset of DocBook 5.1 elements are recognized,
                     82: as well as some elements from earlier versions.
                     83: The parser is optimized for robustness even on invalid input,
                     84: always producing some output on a best-effort basis.
                     85: Input is not required to be well-formed, nor to adhere to DocBook
                     86: syntactic or semantic requirements.
                     87: .Pp
                     88: Unknown elements are ignored in the sense that they do not affect
                     89: formatting and only their content is rendered.
                     90: Unknown attributes are silently discarded.
                     91: .Pp
                     92: In addition to DocBook elements, the following constructs are handled:
                     93: .Bl -tag -width Ds
                     94: .It Eo <!
                     95: .Ic DOCTYPE No ...
                     96: .Eo "[ <!" Ic ENTITY Ar name Qo Ar definition Qc Ec "> ]"
                     97: .Ec >
                     98: Internal subset declaration to define an XML entity.
                     99: .It Eo <!
                    100: .Ic DOCTYPE No ...
                    101: .Eo "[ <!" Ic ENTITY Ar name Cm SYSTEM Qo Ar file Qc Ec "> ]"
                    102: .Ec >
                    103: Internal subset declaration to define an XML entity using an external
                    104: .Ar file .
1.13      schwarze  105: .It Eo <!
                    106: .Ic DOCTYPE No ...
                    107: .Bo
                    108: .Eo " <!" Ic ENTITY No % Ar name Cm SYSTEM Qo Ar file Qc Ec >
                    109: .Pf % Ar name No \&
                    110: .Bc
                    111: .Ec >
                    112: Internal subset declaration to include an external
                    113: .Ar file
                    114: that is supposed to contain entity declarations.
1.11      schwarze  115: .It Eo < Ic mml : Ns ... Ec >
                    116: Elements from the MathML namespace.
                    117: These are translated to
1.6       kristaps  118: .Xr eqn 7 .
1.11      schwarze  119: .It Eo <
                    120: .Ic xi : Ns Ic include No ...
                    121: .Cm href Ns = Ns Qq Ar file
                    122: .Ec >
                    123: Include an external DocBook file into the current document.
                    124: .El
1.1       kristaps  125: .Sh EXIT STATUS
1.10      schwarze  126: The
                    127: .Nm
                    128: utility exits with one of the following values:
                    129: .Bl -tag -width 2n
                    130: .It 0
                    131: No error occurred, and if
                    132: .Fl W
                    133: was specified, no warning occurred either.
                    134: .It 2
                    135: At least one warning occurred, but no error, and
                    136: .Fl W
                    137: was specified.
                    138: .It 3
                    139: At least one parsing error occurred.
                    140: .It 5
                    141: Invalid command line arguments were specified.
                    142: No input files have been read.
                    143: .It 6
                    144: Memory was exhausted.
                    145: Parsing was aborted immediately.
                    146: .El
1.1       kristaps  147: .Sh EXAMPLES
                    148: To pipe a DocBook document
                    149: .Pa foo.xml
                    150: through
                    151: .Xr mandoc 1
                    152: and a pager:
                    153: .Pp
1.9       schwarze  154: .Dl $ docbook2mdoc foo.xml | mandoc -l
1.10      schwarze  155: .Sh DIAGNOSTICS
                    156: Messages displayed by
                    157: .Nm
                    158: follow this format:
                    159: .Pp
                    160: .D1 Nm : Ar file : Ns Ar line : Ns Ar column : level : message
                    161: .Pp
                    162: The first three fields identify the
                    163: .Ar file
                    164: name,
                    165: .Ar line
                    166: number, and
                    167: .Ar column
                    168: number of the input file where the message was triggered.
                    169: The line and column numbers start at 1.
                    170: .Pp
                    171: Message levels have the following meanings:
                    172: .Bl -tag -width warning
                    173: .It Sy fatal
                    174: An operating system error occurred, typically memory exhaustion,
                    175: and parsing was aborted immediately.
                    176: .It Sy error
                    177: Indicates a risk of information loss or severe misformatting,
                    178: for example caused by unknown elements or missing include files.
                    179: .It Sy warning
                    180: Indicates a risk that the information shown or its formatting
                    181: may mismatch the author's intent in minor ways.
                    182: For example, mismatched or missing end tags are classified as warnings.
                    183: .El
1.1       kristaps  184: .Sh SEE ALSO
                    185: .Xr mandoc 1 ,
1.7       kristaps  186: .Xr eqn 7 ,
1.1       kristaps  187: .Xr mdoc 7
                    188: .Sh AUTHORS
                    189: .Nm
                    190: was written by
1.11      schwarze  191: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
                    192: and
                    193: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
1.1       kristaps  194: .Sh CAVEATS
                    195: The
                    196: .Nm
                    197: utility is experimental.
1.11      schwarze  198: Many elements are not recognized yet.
1.2       kristaps  199: .Pp
                    200: The output
                    201: .Xr mdoc 7
                    202: could be much nicer: trailing spaces, superfluous space removal,
                    203: new-line new-sentence, and other niceties are not used.

CVSweb