Return to pod2mdoc.1 CVS log

Up to [cvsweb.bsd.lv] / pod2mdoc

Annotation of pod2mdoc/pod2mdoc.1, Revision 1.5

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