Return to pod2mdoc.1 CVS log

Up to [cvsweb.bsd.lv] / pod2mdoc

Annotation of pod2mdoc/pod2mdoc.1, Revision 1.6

1.6     ! kristaps    1: .\"    $Id: pod2mdoc.1,v 1.5 2014/03/24 01:07:30 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.6     ! kristaps   17: .Dd $Mdocdate: March 24 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
                     92: .Sh EXIT STATUS
                     93: .Ex -std
1.6     ! kristaps   94: .Sh EXAMPLES
        !            95: To pipe a POD document
        !            96: .Pa foo.pod
        !            97: through
        !            98: .Xr mandoc 1
        !            99: and a pager:
        !           100: .Pp
        !           101: .Dl % pod2mdoc foo.pod | mandoc | more
1.1       schwarze  102: .Sh COMPATIBILITY
                    103: If
                    104: .Fl s
                    105: is not specified and the suffix for
                    106: .Ar file
                    107: is
                    108: .Li .pm ,
1.4       kristaps  109: .Nm
1.6     ! kristaps  110: infers a manual section of 3p, not 3 as stipulated in
1.4       kristaps  111: .Xr perlpod 1 .
1.5       kristaps  112: Furthermore, all links in the format of
                    113: .Li L<Foo::Bar>
                    114: are assumed to be in section 3p.
1.4       kristaps  115: .Pp
                    116: If
                    117: .Nm
                    118: encounters an
                    119: .Li =item
                    120: without the necessary
                    121: .Li =over ,
                    122: it will pretend that a prior
                    123: .Li =over
                    124: was invoked.
                    125: However, it will do so silently and not, as
                    126: .Xr pod2man 1
                    127: does, append a POD ERRORS section in the output manpage saying so.
1.1       schwarze  128: .Sh SEE ALSO
1.4       kristaps  129: .Xr perlpod 1 ,
1.6     ! kristaps  130: .Xr pod2man 1 ,
        !           131: .Xr mdoc 7
1.1       schwarze  132: .Sh AUTHORS
                    133: .Nm
                    134: was written by
                    135: .Ar Kristaps Dzonsons ,
                    136: .Mt kristaps@bsd.lv .
                    137: .Sh CAVEATS
1.4       kristaps  138: By way of being a presentational language, POD is not well-represented
                    139: by
1.1       schwarze  140: .Xr mdoc 7 .
                    141: Semantic content will be necessarily lost.
                    142: .Pp
                    143: .Nm
1.4       kristaps  144: only supports the named
                    145: .Li E<xxx>
                    146: escapes.
                    147: HTML names and numbers are silently discarded.
                    148: .Pp
                    149: Although most white-space requests in character encodings are properly
                    150: carried to output, adjacent character escapes with the specific
1.5       kristaps  151: whitespace sequence
1.4       kristaps  152: .Qq Li "B<2>B< 3>"
                    153: will cause the second space to be lost.
                    154: .Pp
                    155: The
                    156: .Li S<>
                    157: escape is discarded.
1.5       kristaps  158: .Pp
                    159: Lastly, only the
                    160: .Li L<Perl::Manpage>
                    161: and
                    162: .Li L<manpage(1)>
                    163: links are understood and properly rendered as
                    164: .Sq \&Xr .