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

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



PERLPOD(1)							    PERLPOD(1)

NAME    [Toc]    [Back]

     perlpod - plain old documentation

DESCRIPTION    [Toc]    [Back]

     A pod-to-whatever translator reads	a pod file paragraph by	paragraph, and
     translates	it to the appropriate output format.  There are	three kinds of

     o	 A verbatim paragraph, distinguished by	being indented (that is, it
	 starts	with space or tab).  It	should be reproduced exactly, with
	 tabs assumed to be on 8-column	boundaries.  There are no special
	 formatting escapes, so	you can't italicize or anything	like that.  A
	 \ means \, and	nothing	else.

     o	 A command.  All command paragraphs start with "=", followed by	an
	 identifier, followed by arbitrary text	that the command can use
	 however it pleases.  Currently	recognized commands are

	     =head1 heading
	     =head2 heading
	     =item text
	     =over N
	     =for X
	     =begin X
	     =end X

	 The "=pod" directive does nothing beyond telling the compiler to lay
	 off parsing code through the next "=cut".  It's useful	for adding
	 another paragraph to the doc if you're	mixing up code and pod a lot.

	 Head1 and head2 produce first and second level	headings, with the
	 text in the same paragraph as the "=headn" directive forming the
	 heading description.

	 Item, over, and back require a	little more explanation: "=over"
	 starts	a section specifically for the generation of a list using
	 "=item" commands. At the end of your list, use	"=back"	to end it. You
	 will probably want to give "4"	as the number to "=over", as some
	 formatters will use this for indentation.  This should	probably be a
	 default. Note also that there are some	basic rules to using =item:
	 don't use them	outside	of an =over/=back block, use at	least one
	 inside	an =over/=back block, you don't	_have_ to include the =back if
	 the list just runs off	the document, and perhaps most importantly,
	 keep the items	consistent: either use "=item *" for all of them, to
	 produce bullets, or use "=item	1.", "=item 2.", etc., to produce
	 numbered lists, or use	"=item foo", "=item bar", etc.,	i.e., things
	 that looks nothing like bullets or numbers. If	you start with bullets
	 or numbers, stick with	them, as many formatters use the first "=item"
	 type to decide	how to format the list.

									Page 1

PERLPOD(1)							    PERLPOD(1)

	 For, begin, and end let you include sections that are not interpreted
	 as pod	text, but passed directly to particular	formatters. A
	 formatter that	can utilize that format	will use the section,
	 otherwise it will be completely ignored.  The directive "=for"
	 specifies that	the entire next	paragraph is in	the format indicated
	 by the	first word after "=for", like this:

	  =for html <br>
	   <p> This is a raw HTML paragraph </p>

	 The paired commands "=begin" and "=end" work very similarly to
	 "=for", but instead of	only accepting a single	paragraph, all text
	 from "=begin" to a paragraph with a matching "=end" are treated as a
	 particular format.

	 Here are some examples	of how to use these:

	  =begin html

	  <br>Figure 1.<IMG SRC="figure1.png"><br>

	  =end html

	  =begin text

	    |  foo	  |
	    |	     bar  |

	  ^^^^ Figure 1. ^^^^

	  =end text

	 Some format names that	formatters currently are known to accept
	 include "roff", "man",	"latex", "tex",	"text",	and "html". (Some
	 formatters will treat some of these as	synonyms.)

	 And don't forget, when	using any command, that	the command lasts up
	 until the end of the paragraph, not the line. Hence in	the examples
	 below,	you can	see the	empty lines after each command to end its

	 Some examples of lists	include:

	  =over	4

	  =item	*

	  First	item

	  =item	*

									Page 2

PERLPOD(1)							    PERLPOD(1)

	  Second item


	  =over	4

	  =item	Foo()

	  Description of Foo function

	  =item	Bar()

	  Description of Bar function


     o	 An ordinary block of text.  It	will be	filled,	and maybe even
	 justified.  Certain interior sequences	are recognized both here and
	 in commands:

	     I<text>	 italicize text, used for emphasis or variables
	     B<text>	 embolden text,	used for switches and programs
	     S<text>	 text contains non-breaking spaces
	     C<code>	 literal code
	     L<name>	 A link	(cross reference) to name
			     L<name>		 manual	page
			     L<name/ident>	 item in manual	page
			     L<name/"sec">	 section in other manual page
			     L<"sec">		 section in this manual	page
						 (the quotes are optional)
			     L</"sec">		 ditto
	     F<file>	 Used for filenames
	     X<index>	 An index entry
	     Z<>	 A zero-width character
	     E<escape>	 A named character (very similar to HTML escapes)
			     E<lt>		 A literal <
			     E<gt>		 A literal >
			     (these are	optional except	in other interior
			      sequences	and when preceded by a capital letter)
			     E<n>		 Character number n (probably in ASCII)
			     E<html>		 Some non-numeric HTML entity, such
						 as E<Agrave>

     That's it.	 The intent is simplicity, not power.  I wanted	paragraphs to
     look like paragraphs (block format), so that they stand out visually, and
     so	that I could run them through fmt easily to reformat them (that's F7
     in	my version of vi).  I wanted the translator (and not me) to worry
     about whether " or	' is a left quote or a right quote within filled text,
     and I wanted it to	leave the quotes alone,	dammit,	in verbatim mode, so I
     could slurp in a working program, shift it	over 4 spaces, and have	it

									Page 3

PERLPOD(1)							    PERLPOD(1)

     print out,	er, verbatim.  And presumably in a constant width font.

     In	particular, you	can leave things like this verbatim in your text:


     Doubtless a few other commands or sequences will need to be added along
     the way, but I've gotten along surprisingly well with just	these.

     Note that I'm not at all claiming this to be sufficient for producing a
     book.  I'm	just trying to make an idiot-proof common source for nroff,
     TeX, and other markup languages, as used for online documentation.
     Translators exist for pod2man  (that's for	nrof
     pod2html, pod2latex, and pod2fm.

Embedding Pods in Perl Modules    [Toc]    [Back]

     You can embed pod documentation in	your Perl scripts.  Start your
     documentation with	a "=head1" command at the beginning, and end it	with a
     "=cut" command.  Perl will	ignore the pod text.  See any of the supplied
     library modules for examples.  If you're going to put your	pods at	the
     end of the	file, and you're using an __END__ or __DATA__ cut mark,	make
     sure to put an empty line there before the	first pod directive.


	 =head1	NAME

	 modern	- I am a modern	module

     If	you had	not had	that empty line	there, then the	translators wouldn't
     have seen it.

Common Pod Pitfalls    [Toc]    [Back]

     o	 Pod translators usually will require paragraphs to be separated by
	 completely empty lines.  If you have an apparently empty line with
	 some spaces on	it, this can cause odd formatting.

     o	 Translators will mostly add wording around a L<> link,	so that
	 L<foo(1)> becomes "the	foo(1) manpage", for example (see pod2man for
	 details).  Thus, you shouldn't	write things like the L<foo> manpage,
	 if you	want the translated document to	read sensibly.

     o	 The script pod/checkpods.PL in	the Perl source	distribution provides
	 skeletal checking for lines that look empty but aren't	only, but is
	 there as a placeholder	until someone writes Pod::Checker.  The	best
	 way to	check your pod is to pass it through one or more translators
	 and proofread the result, or print out	the result and proofread that.
	 Some of the problems found may	be bugs	in the translators, which you

									Page 4

PERLPOD(1)							    PERLPOD(1)

	 may or	may not	wish to	work around.

SEE ALSO    [Toc]    [Back]

     the pod2man manpage and the section on PODs: Embedded Documentation in
     the perlsyn manpage

AUTHOR    [Toc]    [Back]

     Larry Wall

									PPPPaaaaggggeeee 5555
[ Back ]
 Similar pages
Name OS Title
perlpod OpenBSD the Plain Old Documentation format
perlpodspec OpenBSD Plain Old Documentation: format specification and notes
gss_display_name Tru64 Convert internal form name to plain text.
manuals HP-UX list of HP-UX documentation
info OpenBSD readable online documentation
texinfo OpenBSD software documentation system
perldoc OpenBSD Look up Perl documentation in Pod format.
texinfo FreeBSD software documentation system
info FreeBSD readable online documentation
info Linux readable online documentation
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service