[p5sagit/p5-mst-13.2.git] / pod / perlpod.pod

=head1 NAME

perlpod - plain old documentation

=head1 DESCRIPTION

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 paragraphs:

=over 4

=item *

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.

=item *

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
    =back
    =cut
    =pod

The "=pod" directive does nothing beyond telling the compiler to lay
off of 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 on
the same paragraph as "=headn" 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.  

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

Some examples of lists include:

 =over 4

 =item *

 First item

 =item *

 Second item

 =back

 =over 4

 =item Foo()

 Description of Foo function

 =item Bar()

 Description of Bar function

 =back

=item *

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>   An HTML escape
		    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
    	    	    E<html>		Some non-numeric HTML entity, such
					as E<Agrave>

=back

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 B<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 print out, er, verbatim.  And presumably in a
constant width font.

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

    Perl
    FILEHANDLE
    $variable
    function()
    manpage(3r)

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 B<pod2man>  (that's for nroff(1) and troff(1)),
B<pod2html>, B<pod2latex>, and B<pod2fm>.

=head1 Embedding Pods in Perl Modules

You can embed pod documentation in your Perl scripts.  Start your
documentation with a =head1 command at the beg, and end it with 
an =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 a blank line there before
the first pod directive.

    __END__

    =head1 NAME

    modern - I am a modern module

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

=head1 Common Pod Pitfalls

=over 4

=item *

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

=item *

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

=item *

The script F<pod/checkpods.PL> in the Perl source distribution
provides skeletal checking for lines that look blank but aren't
B<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 may or may not wish to work around.

=back

=head1 SEE ALSO

L<pod2man> and L<perlsyn/"PODs: Embedded Documentation">

=head1 AUTHOR

Larry Wall
Commit	Line	Data
a0d0e21e	1	=head1 NAME
a0d0e21e	2
cb1a09d0	3	perlpod - plain old documentation
a0d0e21e	4
	5	=head1 DESCRIPTION
	6
	7	A pod-to-whatever translator reads a pod file paragraph by paragraph,
	8	and translates it to the appropriate output format. There are
	9	three kinds of paragraphs:
	10
	11	=over 4
	12
	13	=item *
	14
	15	A verbatim paragraph, distinguished by being indented (that is,
	16	it starts with space or tab). It should be reproduced exactly,
	17	with tabs assumed to be on 8-column boundaries. There are no
	18	special formatting escapes, so you can't italicize or anything
	19	like that. A \ means \, and nothing else.
	20
	21	=item *
	22
	23	A command. All command paragraphs start with "=", followed by an
	24	identifier, followed by arbitrary text that the command can
	25	use however it pleases. Currently recognized commands are
	26
	27	=head1 heading
	28	=head2 heading
	29	=item text
	30	=over N
	31	=back
4633a7c4	32	=cut
cb1a09d0	33	=pod
	34
	35	The "=pod" directive does nothing beyond telling the compiler to lay
	36	off of through the next "=cut". It's useful for adding another
	37	paragraph to the doc if you're mixing up code and pod a lot.
	38
	39	Head1 and head2 produce first and second level headings, with the text on
	40	the same paragraph as "=headn" forming the heading description.
	41
	42	Item, over, and back require a little more explanation: Over starts a
	43	section specifically for the generation of a list using =item commands. At
	44	the end of your list, use =back to end it. You will probably want to give
184e9718	45	"4" as the number to =over, as some formatters will use this for indentation.
cb1a09d0	46	This should probably be a default. Note also that there are some basic rules
	47	to using =item: don't use them outside of an =over/=back block, use at least
	48	one inside an =over/=back block, you don't _have_ to include the =back if
	49	the list just runs off the document, and perhaps most importantly, keep the
	50	items consistent: either use "=item *" for all of them, to produce bullets,
	51	or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use
	52	"=item foo", "=item bar", etc., i.e., things that looks nothing like bullets
	53	or numbers. If you start with bullets or numbers, stick with them, as many
184e9718	54	formatters use the first =item type to decide how to format the list.
cb1a09d0	55
	56	And don't forget, when using any command, that that command lasts up until
	57	the end of the B<paragraph>, not the line. Hence in the examples below, you
184e9718	58	can see the blank lines after each command to end its paragraph.
cb1a09d0	59
	60	Some examples of lists include:
	61
	62	=over 4
	63
	64	=item *
	65
	66	First item
	67
	68	=item *
	69
	70	Second item
	71
	72	=back
	73
	74	=over 4
	75
	76	=item Foo()
	77
	78	Description of Foo function
	79
	80	=item Bar()
	81
	82	Description of Bar function
	83
	84	=back
a0d0e21e	85
	86	=item *
	87
	88	An ordinary block of text. It will be filled, and maybe even
	89	justified. Certain interior sequences are recognized both
	90	here and in commands:
	91
	92	I<text> italicize text, used for emphasis or variables
	93	B<text> embolden text, used for switches and programs
	94	S<text> text contains non-breaking spaces
	95	C<code> literal code
	96	L<name> A link (cross reference) to name
5f05dabc	97	L<name> manual page
	98	L<name/ident> item in manual page
	99	L<name/"sec"> section in other manual page
	100	L<"sec"> section in this manual page
a0d0e21e	101	(the quotes are optional)
cb1a09d0	102	L</"sec"> ditto
a0d0e21e	103	F<file> Used for filenames
cb1a09d0	104	X<index> An index entry
a0d0e21e	105	Z<> A zero-width character
1294c5d8	106	E<escape> An HTML escape
	107	E<lt> A literal <
	108	E<gt> A literal >
	109	(these are optional except in other interior
	110	sequences and when preceded by a capital letter)
7f3dfc00	111	E<n> Character number n
	112	E<html> Some non-numeric HTML entity, such
	113	as E<Agrave>
a0d0e21e	114
3141265f	115	=back
3141265f	116
a0d0e21e	117	That's it. The intent is simplicity, not power. I wanted paragraphs
	118	to look like paragraphs (block format), so that they stand out
	119	visually, and so that I could run them through fmt easily to reformat
	120	them (that's F7 in my version of B<vi>). I wanted the translator (and not
	121	me) to worry about whether " or ' is a left quote or a right quote
5f05dabc	122	within filled text, and I wanted it to leave the quotes alone, dammit, in
a0d0e21e	123	verbatim mode, so I could slurp in a working program, shift it over 4
	124	spaces, and have it print out, er, verbatim. And presumably in a
	125	constant width font.
	126
	127	In particular, you can leave things like this verbatim in your text:
	128
	129	Perl
	130	FILEHANDLE
	131	$variable
	132	function()
	133	manpage(3r)
	134
	135	Doubtless a few other commands or sequences will need to be added along
	136	the way, but I've gotten along surprisingly well with just these.
	137
	138	Note that I'm not at all claiming this to be sufficient for producing a
	139	book. I'm just trying to make an idiot-proof common source for nroff,
	140	TeX, and other markup languages, as used for online documentation.
cb1a09d0	141	Translators exist for B<pod2man> (that's for nroff(1) and troff(1)),
cb1a09d0	142	B<pod2html>, B<pod2latex>, and B<pod2fm>.
a0d0e21e	143
4633a7c4	144	=head1 Embedding Pods in Perl Modules
	145
	146	You can embed pod documentation in your Perl scripts. Start your
	147	documentation with a =head1 command at the beg, and end it with
	148	an =cut command. Perl will ignore the pod text. See any of the
cb1a09d0	149	supplied library modules for examples. If you're going to put
	150	your pods at the end of the file, and you're using an __END__
	151	or __DATA__ cut mark, make sure to put a blank line there before
	152	the first pod directive.
	153
	154	__END__
	155
	156	=head1 NAME
	157
	158	modern - I am a modern module
	159
	160	If you had not had that blank line there, then the translators wouldn't
	161	have seen it.
	162
1294c5d8	163	=head1 Common Pod Pitfalls
	164
	165	=over 4
	166
	167	=item *
	168
	169	Pod translators usually will require paragraphs to be separated by
	170	completely empty lines. If you have an apparently blank line with
	171	some spaces on it, this can cause odd formatting.
	172
	173	=item *
	174
	175	Translators will mostly add wording around a LE<lt>E<gt> link, so that
	176	C<LE<lt>foo(1)E<gt>> becomes "the I<foo>(1) manpage", for example (see
	177	B<pod2man> for details). Thus, you shouldn't write things like C<the
	178	LE<lt>fooE<gt> manpage>, if you want the translated document to read
	179	sensibly.
	180
	181	=item *
	182
	183	The script F<pod/checkpods.PL> in the Perl source distribution
	184	provides skeletal checking for lines that look blank but aren't
	185	B<only>, but is there as a placeholder until someone writes
	186	Pod::Checker. The best way to check your pod is to pass it through
	187	one or more translators and proofread the result, or print out the
	188	result and proofread that. Some of the problems found may be bugs in
	189	the translators, which you may or may not wish to work around.
	190
	191	=back
	192
cb1a09d0	193	=head1 SEE ALSO
	194
	195	L<pod2man> and L<perlsyn/"PODs: Embedded Documentation">
4633a7c4	196
cb1a09d0	197	=head1 AUTHOR
a0d0e21e	198
	199	Larry Wall
	200