===================================================================
RCS file: /cvs/pod2mdoc/pod2mdoc.1,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -p -r1.6 -r1.7
--- pod2mdoc/pod2mdoc.1	2014/03/24 01:43:42	1.6
+++ pod2mdoc/pod2mdoc.1	2014/04/02 14:50:09	1.7
@@ -1,4 +1,4 @@
-.\"	$Id: pod2mdoc.1,v 1.6 2014/03/24 01:43:42 kristaps Exp $
+.\"	$Id: pod2mdoc.1,v 1.7 2014/04/02 14:50:09 kristaps 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 24 2014 $
+.Dd $Mdocdate: April 2 2014 $
 .Dt POD2MDOC 1
 .Os
 .Sh NAME
@@ -89,6 +89,73 @@ 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
+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, an
+.Sq \&Nm
+and
+.Sq \&Nd
+macro 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
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES