pod2mdoc/pod2mdoc.1 - diff

Return to pod2mdoc.1 CVS log

Up to [cvsweb.bsd.lv] / pod2mdoc

Diff for /pod2mdoc/pod2mdoc.1 between version 1.6 and 1.13

-version 1.6, 2014/03/24 01:43:42
+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
 Line 89  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 .
  .Sh EXIT STATUS
  .Ex -std
  .Sh EXAMPLES
-Line 138  was written by
+Line 241  was written by
 Line 138  was written by
 Line 241  was written by
  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
  only supports the named
-Line 156  The
+Line 259  The
 Line 156  The
 Line 259  The
  .Li S<>
  escape is discarded.
  .Pp
- Lastly, only the
+ Unless solely a section link, the text and section parts of
- .Li L<Perl::Manpage>
+ .Li L<text|link/section>
- and
+ are discarded.
- .Li L<manpage(1)>
- links are understood and properly rendered as
- .Sq \&Xr .

CVSweb