*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> pod2man (1)              



POD2MAN(1)							    POD2MAN(1)

NAME    [Toc]    [Back]

     pod2man - translate embedded Perl pod directives into man pages

SYNOPSIS    [Toc]    [Back]

     pod2man [ --section=manext	] [ --release=relpatch ] [ --center=string ] [
     --date=string ] [ --fixed=font ] [	--official ] [ --lax ] inputfile

DESCRIPTION    [Toc]    [Back]

     pod2man converts its input	file containing	embedded pod directives	(see
     the perlpod manpage) into nroff source suitable for viewing with nrof
 using the man(7) macro	set.

     Besides the obvious pod conversions, pod2man also takes care of 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.  Other nagging
     little roffish things that	it catches include translating the minus in
     something like foo-bar, making a long dash--like this--into a real	em
     dash, fixing up "paired quotes", putting a	little space after the parens
     in	something like func(), making C++ and pi look right, making double
     underbars have a little tiny space	between	them, making ALLCAPS a teeny
     bit smaller in troff(1), and escaping backslashes so you don't have to.

OPTIONS    [Toc]    [Back]

     center  Set the centered header to	a specific string.  The	default	is
	     "User Contributed Perl Documentation", unless the --official flag
	     is	given, in which	case the default is "Perl Programmers
	     Reference Guide".

     date    Set the left-hand footer string to	this value.  By	default, the
	     modification date of the input file will be used.

     fixed   The fixed font to use for code refs.  Defaults to CW.

	     Set the default header to indicate	that this page is of the
	     standard release in case --center is not given.

     release Set the centered footer.  By default, this	is the current perl

     section Set the section for the .TH macro.	 The standard conventions on
	     sections are 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.
	     This works	best if	you put	your Perl man pages in a separate
	     tree, like	/usr/local/perl/man/.  By default, section 1 will be
	     used unless the file ends in .pm in which case section 3 will be

									Page 1

POD2MAN(1)							    POD2MAN(1)

     lax     Don't complain when required sections aren't present.

Anatomy	of a Proper Man	Page
     For those not sure	of the proper layout of	a man page, here's an example
     of	the skeleton of	a proper man page.  Head of the	major headers should
     be	setout as a =head1 directive, and are historically written in the
     rather startling ALL UPPER	CASE format, although this is not mandatory.
     Minor headers may be included using =head2, and are typically in mixed

     NAME      Mandatory section; should be a comma-separated list of programs
	       or functions documented by this podpage,	such as:

		   foo,	bar - programs to do something

     SYNOPSIS  A short usage summary for programs and functions, which may
	       someday be deemed mandatory.

	       Long drawn out discussion of the	program.  It's a good idea to
	       break this up into subsections using the	=head2 directives,

		   =head2 A Sample Subection

		   =head2 Yet Another Sample Subection

     OPTIONS   Some people make	this separate from the description.

	       What the	program	or function returns if successful.

     ERRORS    Exceptions, return codes, exit stati, and errno settings.

     EXAMPLES  Give some example uses of the program.

	       Envariables this	program	might care about.

     FILES     All files used by the program.  You should probably use the F<>
	       for these.

     SEE ALSO  Other man pages to check	out, like man(1), man(7),
	       makewhatis(8), or catman(8).

     NOTES     Miscellaneous commentary.

     CAVEATS   Things to take special care with; sometimes called WARNINGS.

									Page 2

POD2MAN(1)							    POD2MAN(1)

	       All possible messages the program can print out--and what they

     BUGS      Things that are broken or just don't work quite right.

	       Bugs you	don't plan to fix :-)

     AUTHOR    Who wrote it (or	AUTHORS	if multiple).

     HISTORY   Programs	derived	from other sources sometimes have this,	or you
	       might keep a modification log here.

EXAMPLES    [Toc]    [Back]

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

DIAGNOSTICS    [Toc]    [Back]

     The following diagnostics are generated by	pod2man.  Items	marked "(W)"
     are non-fatal, whereas the	"(F)" errors will cause	pod2man	to immediately
     exit with a non-zero status.

     bad option	in paragraph %d	of %s: ``%s'' should be	[%s]<%s>
	 (W) If	you start include an option, you should	set it off as bold,
	 italic, or code.

     can't open	%s: %s
	 (F) The input file wasn't available for the given reason.

     Improper man page - no dash in NAME header	in paragraph %d	of %s
	 (W) The NAME header did not have an isolated dash in it.  This	is
	 considered important.

     Invalid man page -	no NAME	line in	%s
	 (F) You did not include a NAME	header,	which is essential.

     roff font should be 1 or 2	chars, not `%s'	 (F)
	 (F) The font specified	with the --fixed option	was not	a one- or
	 two-digit roff	font.

     %s	is missing required section: %s
	 (W) Required sections include NAME, DESCRIPTION, and if you're	using
	 a section starting with a 3, also a SYNOPSIS.	Actually, not having a
	 NAME is a fatal.

     Unknown escape: %s	in %s
	 (W) An	unknown	HTML entity (probably for an 8-bit character) was
	 given via a E<> directive.  Besides amp, lt, gt, and quot, recognized
	 entities are Aacute, aacute, Acirc, acirc, AElig, aelig, Agrave,

									Page 3

POD2MAN(1)							    POD2MAN(1)

	 agrave, Aring,	aring, Atilde, atilde, Auml, auml, Ccedil, ccedil,
	 Eacute, eacute, Ecirc,	ecirc, Egrave, egrave, ETH, eth, Euml, euml,
	 Iacute, iacute, Icirc,	icirc, Igrave, igrave, Iuml, iuml, Ntilde,
	 ntilde, Oacute, oacute, Ocirc,	ocirc, Ograve, ograve, Oslash, oslash,
	 Otilde, otilde, Ouml, ouml, szlig, THORN, thorn, Uacute, uacute,
	 Ucirc,	ucirc, Ugrave, ugrave, Uuml, uuml, Yacute, yacute, and yuml.

     Unmatched =back
	 (W) You have a	=back without a	corresponding =over.

     Unrecognized pod directive: %s
	 (W) You specified a pod directive that	isn't in the known list	of
	 =head1, =head2, =item,	=over, =back, or =cut.

NOTES    [Toc]    [Back]

     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).
     Settting the F register will get you some additional experimental

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

     The indexing merely outputs messages via .tm for each major page,
     section, subsection, item,	and any	X<> directives.

RESTRICTIONS    [Toc]    [Back]

     None at this time.

BUGS    [Toc]    [Back]

     The =over and =back directives don't really work right.  They take
     absolute positions	instead	of offsets, don't nest well, and making	people
     count is suboptimal in any	event.

AUTHORS    [Toc]    [Back]

     Original prototype	by Larry Wall, but so massively	hacked over by Tom
     Christiansen such that Larry probably doesn't recognize it	anymore.

									Page 4

POD2MAN(1)							    POD2MAN(1)

									PPPPaaaaggggeeee 5555
[ Back ]
 Similar pages
Name OS Title
find2perl OpenBSD translate find command lines to Perl code
find2perl Linux translate find command lines to Perl code
perljp OpenBSD AEuEU,i Perl Y~YxYE `A^a`I`A Perl xIAx3|xOxex|x3x1/2! Perl 5.8.0 xexeicUni- _ codeYuYYi1/4YEx~AcEyxE...
esp IRIX Embedded Support Partner
tt_pattern_barg_add HP-UX add an argument with a value that contains embedded nulls to a pattern
pnpbios FreeBSD support for embedded devices on the motherboard
espquery IRIX Database query for Embedded Support Partner
esparchive IRIX archiving utility for Embedded Support Partner
check_for_syscalls IRIX check for embedded syscalls in an object file.
launchESPartner IRIX start Embedded Support Partner User Interface
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service