version 1.3, 2014/03/23 13:00:24 |
version 1.13, 2014/04/07 11:46:03 |
Line 89 or, if the input file suffix is |
|
Line 89 or, if the input file suffix is |
|
uses |
uses |
.Ar 3p . |
.Ar 3p . |
.El |
.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 . |
.Sh EXIT STATUS |
.Sh EXIT STATUS |
.Ex -std |
.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 |
.Sh COMPATIBILITY |
If |
If |
.Fl s |
.Fl s |
Line 98 is not specified and the suffix for |
|
Line 209 is not specified and the suffix for |
|
.Ar file |
.Ar file |
is |
is |
.Li .pm , |
.Li .pm , |
infer a manual section of 3p, not 3. |
.Nm |
.Sh SEE ALSO |
infers a manual section of 3p, not 3 as stipulated in |
.Xr perlpod 1 |
.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 |
.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 |
.Sh AUTHORS |
.Nm |
.Nm |
was written by |
was written by |
.Ar Kristaps Dzonsons , |
.Ar Kristaps Dzonsons , |
.Mt kristaps@bsd.lv . |
.Mt kristaps@bsd.lv . |
.Sh CAVEATS |
.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 . |
.Xr mdoc 7 . |
Semantic content will be necessarily lost. |
Semantic content must be inferred and may be wrong. |
.Pp |
.Pp |
.Nm |
.Nm |
does not currently support the following: |
only supports the named |
.Bl -enum |
.Li E<xxx> |
.It |
escapes. |
escapes that are htmlnames or numbers |
HTML names and numbers are silently discarded. |
.It |
.Pp |
probably many other things |
Although most white-space requests in character encodings are properly |
.El |
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. |