Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
POD2MDOC(1)		FreeBSD	General	Commands Manual		   POD2MDOC(1)

NAME
     pod2mdoc -- Convert POD data to mdoc input

SYNOPSIS
     pod2man [-chloqruv] [-d date] [-n title] [-s section] [file]

DESCRIPTION
     The pod2mdoc utility reads	file and generates mdoc(7) input from
     perlpod(1)	source.	 If unspecified	or -, file is taken to be standard in-
     put.  Its arguments are as	follows:

     -chloqruv
	     For compatibility with pod2man(1).	 Ignored.

     -d	date
	     Set the document date (`Dd') to date (preferrably in "Month Day,
	     Year" format).  If	unspecified or if date is the literal string
	     Mdocdate, pod2mdoc	uses the file modification date	or the current
	     date if reading from standard input.  If date is the literal
	     string Mdocdate, pod2mdoc prepends	"$Mdocdate:" to	the date and
	     appends a dollar sign, producing the format used by OpenBSD
	     cvs(1).

     -n	title
	     Set the document title (`Dt') to title.  If unspecified, pod2mdoc
	     uses the suffix-stripped filename part of file as a document ti-
	     tle or STDIN if reading from standard input (you probably don't
	     want that).

     -s	section
	     Set the document section (`Dt') to	section.  If unspecified,
	     pod2mdoc uses 1 or, if the	input file suffix is .pm, uses 3p.

   Smarts
     Since mdoc(7) is semantic and perlpod(1) is not, pod2mdoc tries to	figure
     out semantic context for some terms.  Specifically, within	each paragraph
     of	the SYNOPSIS section, the following occur:

     +o	 If any	number of #include <foo.h> lines are found at the start	of a
	 verbatim paragraph, they're rendered with `In'.

     +o	 Other lines starting with `#' are rendered with `Fd'.

     +o	 Function declarations are rendered with `Ft', `Fo', and `Fa'.

     +o	 An initial B<>	format code is rendered	as `Nm'.

     +o	 Subsequent B<>	format codes are rendered as `Ar'.  However, if	the
	 leading character of a	B<> format code	is `-',	it is rendered as
	 `Fl'.	Subsequent space-separated terms without leading hyphens,
	 e.g., B<-foo bar>, are	rendered as `Ar'.

     +o	 Matching [ and	] pairs	are rendered as	`Oo' and `Oc'.

     Thus, the input B<foo> [B<-bar baz>] is rendered as follows:

     .Nm foo
     .Oo
     .Fl bar Ar	baz
     .Oc

     In	the NAME section, `Nm' and `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,	B<foo> - bar will be rendered as follows:

     .Nm foo
     .Nd bar

     Multiple names separated by a comma are properly handled.

     In	any section, the L<> format code is considered a `Lk' link if begin-
     ning with http:, https:, ftp:, sftp:, smb:, or afs:.  If beginning	with
     mailto:, it is considered a `Mt' link.  Otherwise,	it is considered a
     `Xr' manpage in section 3P	if containing double-colons or section 1 oth-
     erwise.  The section may be overriden as L<foo(5)>.  If only a section
     appears, such as in </section>, the link is rendered with `Sx'.

     Words followed by "()" that match function	names listed in	the SYNOPSIS
     section are marked	up with	`Fn'.  If they don't match, they are marked up
     with `Xr'.	 Words not followed by "()" that match preprocessor macros
     #define'd in the SYNOPSIS section are marked up with `Dv'.

     If	the contents of	a B<> or I<> format code matches a type	name mentioned
     in	the SYNOPSIS section, it is rendered as	`Vt'.  If it matches a func-
     tion argument name	mentioned there, it is rendered	as `Fa'.

EXIT STATUS
     The pod2mdoc utility exits	0 on success, and >0 if	an error occurs.

EXAMPLES
     To	pipe a POD document foo.pod through mandoc(1) and a pager:

	   % pod2mdoc foo.pod |	mandoc | more

COMPATIBILITY
     If	-s is not specified and	the suffix for file is .pm, pod2mdoc infers a
     manual section of 3p, not 3 as stipulated in perlpod(1).  Furthermore,
     all links in the format of	L<Foo::Bar> are	assumed	to be in section 3p.

     If	pod2mdoc encounters an =item without the necessary =over, it will pre-
     tend that a prior =over was invoked.  However, it will do so silently and
     not, as pod2man(1)	does, append a POD ERRORS section in the output	man-
     page saying so.

SEE ALSO
     perlpod(1), pod2man(1), mdoc(7)

AUTHORS
     pod2mdoc was written by Kristaps Dzonsons <kristaps@bsd.lv>.

CAVEATS
     By	way of being a presentational language,	POD is not well-represented by
     mdoc(7).  Semantic	content	must be	inferred and may be wrong.

     pod2mdoc only supports the	named E<xxx> escapes.  HTML names and numbers
     are silently discarded.

     Although most white-space requests	in character encodings are properly
     carried to	output,	adjacent character escapes with	the specific white-
     space sequence "B<2>B< 3>"	will cause the second space to be lost.

     The S<> escape is discarded.

     Unless solely a section link, the text and	section	parts of
     L<text|link/section> are discarded.

FreeBSD	13.0			 May 19, 2015			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | EXIT STATUS | EXAMPLES | COMPATIBILITY | SEE ALSO | AUTHORS | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pod2mdoc&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help