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

Annotation of pod2mdoc/pod2mdoc.1, Revision 1.10

1.10    ! kristaps    1: .\"    $Id: pod2mdoc.1,v 1.9 2014/04/03 10:17:14 kristaps Exp $
1.1       schwarze    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    ! kristaps   17: .Dd $Mdocdate: April 3 2014 $
1.1       schwarze   18: .Dt POD2MDOC 1
                     19: .Os
                     20: .Sh NAME
                     21: .Nm pod2mdoc
                     22: .Nd Convert POD data to mdoc input
                     23: .Sh SYNOPSIS
                     24: .Nm pod2man
                     25: .Op Fl chloqruv
                     26: .Op Fl d Ar date
                     27: .Op Fl n Ar title
                     28: .Op Fl s Ar section
                     29: .Op Ar file
                     30: .Sh DESCRIPTION
                     31: The
                     32: .Nm
                     33: utility reads
                     34: .Ar file
                     35: and
                     36: generates
                     37: .Xr mdoc 7
                     38: input from
                     39: .Xr perlpod 1
                     40: source.
                     41: If unspecified or
                     42: .Ar \&- ,
                     43: .Ar file
                     44: is taken to be standard input.
                     45: Its arguments are as follows:
                     46: .Bl -tag -width Ds
                     47: .It Fl chloqruv
                     48: For compatibility with
                     49: .Xr pod2man 1 .
                     50: Ignored.
                     51: .It Fl d Ar date
                     52: Set the document date
                     53: .Pq Sq Dd
                     54: to
                     55: .Ar date
                     56: .Po
                     57: preferrably in
                     58: .Qq Month Day, Year
                     59: format
                     60: .Pc .
                     61: If unspecified,
                     62: .Nm
                     63: uses the file modification date or the current date if reading from
                     64: standard input.
                     65: .It Fl n Ar title
                     66: Set the document title
                     67: .Pq Sq Dt
                     68: to
                     69: .Ar title .
                     70: If unspecified,
                     71: .Nm
                     72: uses the suffix-stripped filename part of
                     73: .Ar file
                     74: as a document title or
                     75: .Ar STDIN
                     76: if reading from standard input
                     77: .Pq you probably don't want that .
                     78: .It Fl s Ar section
                     79: Set the document section
                     80: .Pq Sq Dt
                     81: to
                     82: .Ar section .
                     83: If unspecified,
                     84: .Nm
                     85: uses
                     86: .Ar 1
                     87: or, if the input file suffix is
                     88: .Li .pm ,
                     89: uses
                     90: .Ar 3p .
                     91: .El
1.7       kristaps   92: .Ss Smarts
                     93: Since
                     94: .Xr mdoc 7
                     95: is semantic and
                     96: .Xr perlpod 1
                     97: is not,
                     98: .Nm
                     99: tries to figure out semantic context for some terms.
                    100: Specifically, within each paragraph of the SYNOPSIS section, the
                    101: following occur:
                    102: .Bl -bullet
                    103: .It
                    104: An initial
                    105: .Li B<>
                    106: format code is rendered as
                    107: .Sq \&Nm .
                    108: .It
                    109: Subsequent
                    110: .Li B<>
                    111: format codes are rendered as
                    112: .Sq \&Ar .
                    113: However, if the leading character of a
                    114: .Li B<>
                    115: format code is
                    116: .Sq - ,
                    117: it is rendered as
                    118: .Sq \&Fl .
                    119: Subsequent space-separated terms without leading hyphens, e.g.,
                    120: .Li B<-foo bar> ,
                    121: are rendered as
                    122: .Sq \&Ar .
                    123: .It
                    124: Matching
                    125: .Li \&[
                    126: and
                    127: .Li \&]
                    128: pairs are rendered as
                    129: .Sq \&Oo
                    130: and
                    131: .Sq \&Oc .
                    132: .El
                    133: .Pp
                    134: Thus, the input
                    135: .Li B<foo> [B<-bar baz>]
                    136: is rendered as follows:
                    137: .Bd -literal
                    138: \&.Nm foo
                    139: \&.Oo
                    140: \&.Fl bar Ar baz
                    141: \&.Oc
                    142: .Ed
                    143: .Pp
1.8       kristaps  144: In the NAME section,
1.7       kristaps  145: .Sq \&Nm
                    146: and
                    147: .Sq \&Nd
1.8       kristaps  148: macros are inferred from text leading and trailing the last hyphen
1.7       kristaps  149: followed by a space (there may be any number of hyphens preceding the
                    150: space).
                    151: The space may occur on either side of the hyphen.
                    152: Thus,
                    153: .Li B<foo> - bar
                    154: will be rendered as follows:
                    155: .Bd -literal
                    156: \&.Nm foo
                    157: \&.Nd bar
                    158: .Ed
1.8       kristaps  159: .Pp
                    160: Multiple names separated by a comma are properly handled.
1.9       kristaps  161: .Pp
                    162: In any section, the
                    163: .Li L<>
                    164: format code is considered a
                    165: .Sq \&Lk
                    166: link if beginning with
                    167: .Li http: ,
                    168: .Li https: ,
                    169: .Li ftp: ,
                    170: .Li sftp: ,
                    171: .Li smb: ,
                    172: or
                    173: .Li afs: .
                    174: If beginning with
                    175: .Li mailto: ,
                    176: it is considered a
                    177: .Sq \&Mt
                    178: link.
                    179: Otherwise, it is considered a
                    180: .Sq \&Xr
                    181: manpage in section 3P if containing double-colons or section 1
                    182: otherwise.
                    183: The section may be overriden as
                    184: .Li L<foo(5)> .
1.10    ! kristaps  185: If only a section appears, such as in
        !           186: .Li </section> ,
        !           187: the link is rendered with
        !           188: .Sq \&Sx .
1.1       schwarze  189: .Sh EXIT STATUS
                    190: .Ex -std
1.6       kristaps  191: .Sh EXAMPLES
                    192: To pipe a POD document
                    193: .Pa foo.pod
                    194: through
                    195: .Xr mandoc 1
                    196: and a pager:
                    197: .Pp
                    198: .Dl % pod2mdoc foo.pod | mandoc | more
1.1       schwarze  199: .Sh COMPATIBILITY
                    200: If
                    201: .Fl s
                    202: is not specified and the suffix for
                    203: .Ar file
                    204: is
                    205: .Li .pm ,
1.4       kristaps  206: .Nm
1.6       kristaps  207: infers a manual section of 3p, not 3 as stipulated in
1.4       kristaps  208: .Xr perlpod 1 .
1.5       kristaps  209: Furthermore, all links in the format of
                    210: .Li L<Foo::Bar>
                    211: are assumed to be in section 3p.
1.4       kristaps  212: .Pp
                    213: If
                    214: .Nm
                    215: encounters an
                    216: .Li =item
                    217: without the necessary
                    218: .Li =over ,
                    219: it will pretend that a prior
                    220: .Li =over
                    221: was invoked.
                    222: However, it will do so silently and not, as
                    223: .Xr pod2man 1
                    224: does, append a POD ERRORS section in the output manpage saying so.
1.1       schwarze  225: .Sh SEE ALSO
1.4       kristaps  226: .Xr perlpod 1 ,
1.6       kristaps  227: .Xr pod2man 1 ,
                    228: .Xr mdoc 7
1.1       schwarze  229: .Sh AUTHORS
                    230: .Nm
                    231: was written by
                    232: .Ar Kristaps Dzonsons ,
                    233: .Mt kristaps@bsd.lv .
                    234: .Sh CAVEATS
1.4       kristaps  235: By way of being a presentational language, POD is not well-represented
                    236: by
1.1       schwarze  237: .Xr mdoc 7 .
                    238: Semantic content will be necessarily lost.
                    239: .Pp
                    240: .Nm
1.4       kristaps  241: only supports the named
                    242: .Li E<xxx>
                    243: escapes.
                    244: HTML names and numbers are silently discarded.
                    245: .Pp
                    246: Although most white-space requests in character encodings are properly
                    247: carried to output, adjacent character escapes with the specific
1.5       kristaps  248: whitespace sequence
1.4       kristaps  249: .Qq Li "B<2>B< 3>"
                    250: will cause the second space to be lost.
                    251: .Pp
                    252: The
                    253: .Li S<>
                    254: escape is discarded.
1.10    ! kristaps  255: .Pp
        !           256: Unless solely a section link, the text and section parts of
        !           257: .Li L<text|link/section>
        !           258: are discarded.

CVSweb