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

FreeBSD Manual Pages

  
 
  

home | help
POD2MAN(1)	       Perl Programmers	Reference Guide		    POD2MAN(1)

NAME
       pod2man - Convert POD data to formatted *roff input

SYNOPSIS
       pod2man [--center=string] [--date=string] [--errors=style]
	   [--fixed=font] [--fixedbold=font] [--fixeditalic=font]
	   [--fixedbolditalic=font] [--name=name] [--nourls]
	   [--official]	[--release=version] [--section=manext]
	   [--quotes=quotes] [--lquote=quote] [--rquote=quote]
	   [--stderr] [--utf8] [--verbose] [input [output] ...]

       pod2man --help

DESCRIPTION
       pod2man is a front-end for Pod::Man, using it to	generate *roff input
       from POD	source.	 The resulting *roff code is suitable for display on a
       terminal	using nroff(1),	normally via man(1), or	printing using
       troff(1).

       input is	the file to read for POD source	(the POD can be	embedded in
       code).  If input	isn't given, it	defaults to "STDIN".  output, if
       given, is the file to which to write the	formatted output.  If output
       isn't given, the	formatted output is written to "STDOUT".  Several POD
       files can be processed in the same pod2man invocation (saving module
       load and	compile	times) by providing multiple pairs of input and	output
       files on	the command line.

       --section, --release, --center, --date, and --official can be used to
       set the headers and footers to use; if not given, Pod::Man will assume
       various defaults.  See below or Pod::Man	for details.

       pod2man assumes that your *roff formatters have a fixed-width font
       named "CW".  If yours is	called something else (like "CR"), use --fixed
       to specify it.  This generally only matters for troff output for
       printing.  Similarly, you can set the fonts used	for bold, italic, and
       bold italic fixed-width output.

       Besides the obvious pod conversions, Pod::Man, and therefore pod2man
       also takes care of formatting func(), func(n), and simple variable
       references like $foo or @bar so you don't have to use code escapes for
       them; complex expressions like $fred{'stuff'} will still	need to	be
       escaped,	though.	 It also translates dashes that	aren't used as hyphens
       into en dashes, makes long dashes--like this--into proper em dashes,
       fixes "paired quotes," and takes	care of	several	other troff-specific
       tweaks.	See Pod::Man for complete information.

OPTIONS
       -c string, --center=string
	   Sets	the centered page header for the ".TH" macro to	string.	 The
	   default is "User Contributed	Perl Documentation", but also see
	   --official below.

       -d string, --date=string
	   Set the left-hand footer string for the ".TH" macro to string.  By
	   default, the	modification date of the input file will be used, or
	   the current date if input comes from	"STDIN", and will be based on
	   UTC (so that	the output will	be reproducible	regardless of local
	   time	zone).

       --errors=style
	   Set the error handling style.  "die"	says to	throw an exception on
	   any POD formatting error.  "stderr" says to report errors on
	   standard error, but not to throw an exception.  "pod" says to
	   include a POD ERRORS	section	in the resulting documentation
	   summarizing the errors.  "none" ignores POD errors entirely,	as
	   much	as possible.

	   The default is "die".

       --fixed=font
	   The fixed-width font	to use for verbatim text and code.  Defaults
	   to "CW".  Some systems may want "CR"	instead.  Only matters for
	   troff(1) output.

       --fixedbold=font
	   Bold	version	of the fixed-width font.  Defaults to "CB".  Only
	   matters for troff(1)	output.

       --fixeditalic=font
	   Italic version of the fixed-width font (actually, something of a
	   misnomer, since most	fixed-width fonts only have an oblique
	   version, not	an italic version).  Defaults to "CI".	Only matters
	   for troff(1)	output.

       --fixedbolditalic=font
	   Bold	italic (probably actually oblique) version of the fixed-width
	   font.  Pod::Man doesn't assume you have this, and defaults to "CB".
	   Some	systems	(such as Solaris) have this font available as "CX".
	   Only	matters	for troff(1) output.

       -h, --help
	   Print out usage information.

       -l, --lax
	   No longer used.  pod2man used to check its input for	validity as a
	   manual page,	but this should	now be done by podchecker(1) instead.
	   Accepted for	backward compatibility;	this option no longer does
	   anything.

       --lquote=quote
       --rquote=quote
	   Sets	the quote marks	used to	surround C<> text.  --lquote sets the
	   left	quote mark and --rquote	sets the right quote mark.  Either may
	   also	be set to the special value "none", in which case no quote
	   mark	is added on that side of C<> text (but the font	is still
	   changed for troff output).

	   Also	see the	--quotes option, which can be used to set both quotes
	   at once.  If	both --quotes and one of the other options is set,
	   --lquote or --rquote	overrides --quotes.

       -n name,	--name=name
	   Set the name	of the manual page for the ".TH" macro to name.
	   Without this	option,	the manual name	is set to the uppercased base
	   name	of the file being converted unless the manual section is 3, in
	   which case the path is parsed to see	if it is a Perl	module path.
	   If it is, a path like ".../lib/Pod/Man.pm" is converted into	a name
	   like	"Pod::Man".  This option, if given, overrides any automatic
	   determination of the	name.

	   Although one	does not have to follow	this convention, be aware that
	   the convention for UNIX man pages for commands is for the man page
	   title to be in all-uppercase, even if the command isn't.

	   This	option is probably not useful when converting multiple POD
	   files at once.

	   When	converting POD source from standard input, the name will be
	   set to "STDIN" if this option is not	provided.  Providing this
	   option is strongly recommended to set a meaningful manual page
	   name.

       --nourls
	   Normally, L<> formatting codes with a URL but anchor	text are
	   formatted to	show both the anchor text and the URL.	In other
	   words:

	       L<foo|http://example.com/>

	   is formatted	as:

	       foo <http://example.com/>

	   This	flag, if given,	suppresses the URL when	anchor text is given,
	   so this example would be formatted as just "foo".  This can produce
	   less	cluttered output in cases where	the URLs are not particularly
	   important.

       -o, --official
	   Set the default header to indicate that this	page is	part of	the
	   standard Perl release, if --center is not also given.

       -q quotes, --quotes=quotes
	   Sets	the quote marks	used to	surround C<> text to quotes.  If
	   quotes is a single character, it is used as both the	left and right
	   quote.  Otherwise, it is split in half, and the first half of the
	   string is used as the left quote and	the second is used as the
	   right quote.

	   quotes may also be set to the special value "none", in which	case
	   no quote marks are added around C<> text (but the font is still
	   changed for troff output).

	   Also	see the	--lquote and --rquote options, which can be used to
	   set the left	and right quotes independently.	 If both --quotes and
	   one of the other options is set, --lquote or	--rquote overrides
	   --quotes.

       -r version, --release=version
	   Set the centered footer for the ".TH" macro to version.  By
	   default, this is set	to the version of Perl you run pod2man under.
	   Setting this	to the empty string will cause some *roff
	   implementations to use the system default value.

	   Note	that some system "an" macro sets assume	that the centered
	   footer will be a modification date and will prepend something like
	   "Last modified: ".  If this is the case for your target system, you
	   may want to set --release to	the last modified date and --date to
	   the version number.

       -s string, --section=string
	   Set the section for the ".TH" macro.	 The standard section
	   numbering convention	is to use 1 for	user commands, 2 for system
	   calls, 3 for	functions, 4 for devices, 5 for	file formats, 6	for
	   games, 7 for	miscellaneous information, and 8 for administrator
	   commands.  There is a lot of	variation here,	however; some systems
	   (like Solaris) use 4	for file formats, 5 for	miscellaneous
	   information,	and 7 for devices.  Still others use 1m	instead	of 8,
	   or some mix of both.	 About the only	section	numbers	that are
	   reliably consistent are 1, 2, and 3.

	   By default, section 1 will be used unless the file ends in ".pm",
	   in which case section 3 will	be selected.

       --stderr
	   By default, pod2man dies if any errors are detected in the POD
	   input.  If --stderr is given	and no --errors	flag is	present,
	   errors are sent to standard error, but pod2man does not abort.
	   This	is equivalent to "--errors=stderr" and is supported for
	   backward compatibility.

       -u, --utf8
	   By default, pod2man produces	the most conservative possible *roff
	   output to try to ensure that	it will	work with as many different
	   *roff implementations as possible.  Many *roff implementations
	   cannot handle non-ASCII characters, so this means all non-ASCII
	   characters are converted either to a	*roff escape sequence that
	   tries to create a properly accented character (at least for troff
	   output) or to "X".

	   This	option says to instead output literal UTF-8 characters.	 If
	   your	*roff implementation can handle	it, this is the	best output
	   format to use and avoids corruption of documents containing non-
	   ASCII characters.  However, be warned that *roff source with
	   literal UTF-8 characters is not supported by	many implementations
	   and may even	result in segfaults and	other bad behavior.

	   Be aware that, when using this option, the input encoding of	your
	   POD source should be	properly declared unless it's US-ASCII.
	   Pod::Simple will attempt to guess the encoding and may be
	   successful if it's Latin-1 or UTF-8,	but it will warn, which	by
	   default results in a	pod2man	failure.  Use the "=encoding" command
	   to declare the encoding.  See perlpod(1) for	more information.

       -v, --verbose
	   Print out the name of each output file as it	is being generated.

EXIT STATUS
       As long as all documents	processed result in some output, even if that
       output includes errata (a "POD ERRORS" section generated	with
       "--errors=pod"),	pod2man	will exit with status 0.  If any of the
       documents being processed do not	result in an output document, pod2man
       will exit with status 1.	 If there are syntax errors in a POD document
       being processed and the error handling style is set to the default of
       "die", pod2man will abort immediately with exit status 255.

DIAGNOSTICS
       If pod2man fails	with errors, see Pod::Man and Pod::Simple for
       information about what those errors might mean.

EXAMPLES
	   pod2man program > program.1
	   pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
	   pod2man --section=7 note.pod	> note.7

       If you would like to print out a	lot of man page	continuously, you
       probably	want to	set the	C and D	registers to set contiguous page
       numbering and even/odd paging, at least on some versions	of man(7).

	   troff -man -rC1 -rD1	perl.1 perldata.1 perlsyn.1 ...

       To get index entries on "STDERR", turn on the F register, as in:

	   troff -man -rF1 perl.1

       The indexing merely outputs messages via	".tm" for each major page,
       section,	subsection, item, and any "X<>"	directives.  See Pod::Man for
       more details.

BUGS
       Lots of this documentation is duplicated	from Pod::Man.

SEE ALSO
       Pod::Man, Pod::Simple, man(1), nroff(1),	perlpod(1), podchecker(1),
       perlpodstyle(1),	troff(1), man(7)

       The man page documenting	the an macro set may be	man(5) instead of
       man(7) on your system.

       The current version of this script is always available from its web
       site at <http://www.eyrie.org/~eagle/software/podlators/>.  It is also
       part of the Perl	core distribution as of	5.6.0.

AUTHOR
       Russ Allbery <rra@cpan.org>, based very heavily on the original pod2man
       by Larry	Wall and Tom Christiansen.

COPYRIGHT AND LICENSE
       Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013, 2014,
       2015, 2016 Russ Allbery <rra@cpan.org>

       This program is free software; you may redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.26.0			  2017-07-03			    POD2MAN(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXIT STATUS | DIAGNOSTICS | EXAMPLES | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

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

home | help