===================================================================
RCS file: /cvs/pod2mdoc/pod2mdoc.1,v
retrieving revision 1.3
retrieving revision 1.15
diff -u -p -r1.3 -r1.15
--- pod2mdoc/pod2mdoc.1	2014/03/23 13:00:24	1.3
+++ pod2mdoc/pod2mdoc.1	2015/02/13 15:35:15	1.15
@@ -1,4 +1,4 @@
-.\"	$Id: pod2mdoc.1,v 1.3 2014/03/23 13:00:24 kristaps Exp $
+.\"	$Id: pod2mdoc.1,v 1.15 2015/02/13 15:35:15 schwarze Exp $
 .\"
 .\" Copyright (c) 2014 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: March 23 2014 $
+.Dd $Mdocdate: February 13 2015 $
 .Dt POD2MDOC 1
 .Os
 .Sh NAME
@@ -50,7 +50,7 @@ For compatibility with
 Ignored.
 .It Fl d Ar date
 Set the document date
-.Pq Sq Dd
+.Pq Sq \&Dd
 to
 .Ar date
 .Po
@@ -64,7 +64,7 @@ uses the file modification date or the current date if
 standard input.
 .It Fl n Ar title
 Set the document title
-.Pq Sq Dt
+.Pq Sq \&Dt
 to
 .Ar title .
 If unspecified,
@@ -77,7 +77,7 @@ if reading from standard input
 .Pq you probably don't want that .
 .It Fl s Ar section
 Set the document section
-.Pq Sq Dt
+.Pq Sq \&Dt
 to
 .Ar section .
 If unspecified,
@@ -89,8 +89,133 @@ or, if the input file suffix is
 uses
 .Ar 3p .
 .El
+.Ss Smarts
+Since
+.Xr mdoc 7
+is semantic and
+.Xr perlpod 1
+is not,
+.Nm
+tries to figure out semantic context for some terms.
+Specifically, within each paragraph of the SYNOPSIS section, the
+following occur:
+.Bl -bullet
+.It
+If any number of
+.Li #include <foo.h>
+lines are found at the start of a verbatim paragraph, they're rendered
+with
+.Sq \&In .
+.It
+An initial
+.Li B<>
+format code is rendered as
+.Sq \&Nm .
+.It
+Subsequent
+.Li B<>
+format codes are rendered as
+.Sq \&Ar .
+However, if the leading character of a
+.Li B<>
+format code is
+.Sq - ,
+it is rendered as
+.Sq \&Fl .
+Subsequent space-separated terms without leading hyphens, e.g.,
+.Li B<-foo bar> ,
+are rendered as
+.Sq \&Ar .
+.It
+Matching
+.Li \&[
+and
+.Li \&]
+pairs are rendered as
+.Sq \&Oo
+and
+.Sq \&Oc .
+.El
+.Pp
+Thus, the input
+.Li B<foo> [B<-bar baz>]
+is rendered as follows:
+.Bd -literal
+\&.Nm foo
+\&.Oo
+\&.Fl bar Ar baz
+\&.Oc
+.Ed
+.Pp
+In the NAME section,
+.Sq \&Nm
+and
+.Sq \&Nd
+macros are inferred from text leading and trailing the last hyphen
+followed by a space (there may be any number of hyphens preceding the
+space).
+The space may occur on either side of the hyphen.
+Thus,
+.Li B<foo> - bar
+will be rendered as follows:
+.Bd -literal
+\&.Nm foo
+\&.Nd bar
+.Ed
+.Pp
+Multiple names separated by a comma are properly handled.
+.Pp
+In any section, the
+.Li L<>
+format code is considered a
+.Sq \&Lk
+link if beginning with
+.Li http: ,
+.Li https: ,
+.Li ftp: ,
+.Li sftp: ,
+.Li smb: ,
+or
+.Li afs: .
+If beginning with
+.Li mailto: ,
+it is considered a
+.Sq \&Mt
+link.
+Otherwise, it is considered a
+.Sq \&Xr
+manpage in section 3P if containing double-colons or section 1
+otherwise.
+The section may be overriden as
+.Li L<foo(5)> .
+If only a section appears, such as in
+.Li </section> ,
+the link is rendered with
+.Sq \&Sx .
+.Pp
+Words followed by
+.Qq Pq
+that match function names listed in the SYNOPSIS section are marked up with
+.Sq \&Fn .
+.Pp
+If the contents of a
+.Li B<>
+format code matches a type name mentioned in the SYNOPSIS section,
+it is rendered as
+.Sq \&Vt .
+If it matches a function argument name mentioned there,
+it is rendered as
+.Sq \&Fa .
 .Sh EXIT STATUS
 .Ex -std
+.Sh EXAMPLES
+To pipe a POD document
+.Pa foo.pod
+through
+.Xr mandoc 1
+and a pager:
+.Pp
+.Dl % pod2mdoc foo.pod | mandoc | more
 .Sh COMPATIBILITY
 If
 .Fl s
@@ -98,25 +223,55 @@ is not specified and the suffix for
 .Ar file
 is
 .Li .pm ,
-infer a manual section of 3p, not 3.
-.Sh SEE ALSO
-.Xr perlpod 1
+.Nm
+infers a manual section of 3p, not 3 as stipulated in
+.Xr perlpod 1 .
+Furthermore, all links in the format of
+.Li L<Foo::Bar>
+are assumed to be in section 3p.
+.Pp
+If
+.Nm
+encounters an
+.Li =item
+without the necessary
+.Li =over ,
+it will pretend that a prior
+.Li =over
+was invoked.
+However, it will do so silently and not, as
 .Xr pod2man 1
+does, append a POD ERRORS section in the output manpage saying so.
+.Sh SEE ALSO
+.Xr perlpod 1 ,
+.Xr pod2man 1 ,
+.Xr mdoc 7
 .Sh AUTHORS
 .Nm
 was written by
-.Ar Kristaps Dzonsons ,
-.Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
 .Sh CAVEATS
-By way of being a presentational language, POD translates poorly to
+By way of being a presentational language, POD is not well-represented
+by
 .Xr mdoc 7 .
-Semantic content will be necessarily lost.
+Semantic content must be inferred and may be wrong.
 .Pp
 .Nm
-does not currently support the following:
-.Bl -enum
-.It
-escapes that are htmlnames or numbers
-.It
-probably many other things
-.El
+only supports the named
+.Li E<xxx>
+escapes.
+HTML names and numbers are silently discarded.
+.Pp
+Although most white-space requests in character encodings are properly
+carried to output, adjacent character escapes with the specific
+whitespace sequence
+.Qq Li "B<2>B< 3>"
+will cause the second space to be lost.
+.Pp
+The
+.Li S<>
+escape is discarded.
+.Pp
+Unless solely a section link, the text and section parts of
+.Li L<text|link/section>
+are discarded.