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

Annotation of docbook2mdoc/docbook2mdoc.1, Revision 1.16

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

CVSweb