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

Annotation of docbook2mdoc/docbook2mdoc.1, Revision 1.10

1.10    ! schwarze    1: .\"    $Id: docbook2mdoc.1,v 1.9 2019/03/17 13:53:42 schwarze Exp $
1.1       kristaps    2: .\"
                      3: .\" Copyright (c) 2014 Kristaps Dzonsons <kristaps@bsd.lv>
                      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 above
                      7: .\" copyright notice and this permission notice appear in all copies.
                      8: .\"
                      9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     16: .\"
1.10    ! schwarze   17: .Dd $Mdocdate: March 17 2019 $
1.1       kristaps   18: .Dt DOCBOOK2MDOC 1
                     19: .Os
                     20: .Sh NAME
                     21: .Nm docbook2mdoc
                     22: .Nd Convert DocBook refentry to mdoc
                     23: .Sh SYNOPSIS
1.2       kristaps   24: .Nm docbook2mdoc
1.9       schwarze   25: .Op Fl W
1.1       kristaps   26: .Op Ar file
                     27: .Sh DESCRIPTION
                     28: The
                     29: .Nm
                     30: utility reads
                     31: .Ar file
1.9       schwarze   32: and generates
1.1       kristaps   33: .Xr mdoc 7
1.6       kristaps   34: and
                     35: .Xr eqn 7
1.8       schwarze   36: from the <refentry> section of DocBook source, ignoring other sections.
1.1       kristaps   37: If unspecified or
1.8       schwarze   38: .Sq Cm \- ,
1.1       kristaps   39: .Ar file
                     40: is taken to be standard input.
1.8       schwarze   41: .Pp
1.4       kristaps   42: The arguments are as follows:
                     43: .Bl -tag -width Ds
                     44: .It Fl W
1.10    ! schwarze   45: Report warnings on standard error output, and if any occur, raise the
        !            46: .Sx EXIT STATUS
        !            47: to at least 2.
1.4       kristaps   48: .El
1.2       kristaps   49: .Pp
                     50: .Nm
                     51: supports only well-formed XML DocBook V4.x until V5.1.
1.5       kristaps   52: Some earlier DocBook constructs are accepted as well.
1.2       kristaps   53: SGML DocBook documents may be parsed unless they contain SGML-specific
                     54: constructs, such as empty end tags
                     55: .Li </> .
1.8       schwarze   56: The only non-DocBook constructs recognised are <xi:include\ />
1.6       kristaps   57: .Pq which is discarded
1.8       schwarze   58: and <mml:*>, which is accepted and converted to
1.6       kristaps   59: .Xr eqn 7 .
1.1       kristaps   60: .Sh EXIT STATUS
1.10    ! schwarze   61: The
        !            62: .Nm
        !            63: utility exits with one of the following values:
        !            64: .Bl -tag -width 2n
        !            65: .It 0
        !            66: No error occurred, and if
        !            67: .Fl W
        !            68: was specified, no warning occurred either.
        !            69: .It 2
        !            70: At least one warning occurred, but no error, and
        !            71: .Fl W
        !            72: was specified.
        !            73: .It 3
        !            74: At least one parsing error occurred.
        !            75: .It 5
        !            76: Invalid command line arguments were specified.
        !            77: No input files have been read.
        !            78: .It 6
        !            79: Memory was exhausted.
        !            80: Parsing was aborted immediately.
        !            81: .El
1.1       kristaps   82: .Sh EXAMPLES
                     83: To pipe a DocBook document
                     84: .Pa foo.xml
                     85: through
                     86: .Xr mandoc 1
                     87: and a pager:
                     88: .Pp
1.9       schwarze   89: .Dl $ docbook2mdoc foo.xml | mandoc -l
1.10    ! schwarze   90: .Sh DIAGNOSTICS
        !            91: Messages displayed by
        !            92: .Nm
        !            93: follow this format:
        !            94: .Pp
        !            95: .D1 Nm : Ar file : Ns Ar line : Ns Ar column : level : message
        !            96: .Pp
        !            97: The first three fields identify the
        !            98: .Ar file
        !            99: name,
        !           100: .Ar line
        !           101: number, and
        !           102: .Ar column
        !           103: number of the input file where the message was triggered.
        !           104: The line and column numbers start at 1.
        !           105: .Pp
        !           106: Message levels have the following meanings:
        !           107: .Bl -tag -width warning
        !           108: .It Sy fatal
        !           109: An operating system error occurred, typically memory exhaustion,
        !           110: and parsing was aborted immediately.
        !           111: .It Sy error
        !           112: Indicates a risk of information loss or severe misformatting,
        !           113: for example caused by unknown elements or missing include files.
        !           114: .It Sy warning
        !           115: Indicates a risk that the information shown or its formatting
        !           116: may mismatch the author's intent in minor ways.
        !           117: For example, mismatched or missing end tags are classified as warnings.
        !           118: .El
1.1       kristaps  119: .Sh SEE ALSO
                    120: .Xr mandoc 1 ,
1.7       kristaps  121: .Xr eqn 7 ,
1.1       kristaps  122: .Xr mdoc 7
                    123: .Sh AUTHORS
                    124: .Nm
                    125: was written by
1.8       schwarze  126: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.1       kristaps  127: .Sh CAVEATS
                    128: The
                    129: .Nm
                    130: utility is experimental.
1.8       schwarze  131: As such, only a modest subset of the <refentry> domain is accepted.
1.2       kristaps  132: .Pp
                    133: The output
                    134: .Xr mdoc 7
                    135: could be much nicer: trailing spaces, superfluous space removal,
                    136: new-line new-sentence, and other niceties are not used.

CVSweb