develooper Front page | perl.perl5.porters | Postings from August 2001

perlpod rewrite, draft 1

Thread Previous
From:
Sean M. Burke
Date:
August 11, 2001 03:35
Subject:
perlpod rewrite, draft 1
Message ID:
3.0.6.32.20010811043457.007b0100@mail.spinn.net
(CC any replies to pod-people@perl.org too; sorry if this is a repost.)

=head1 NAME

perlpod - Plain Old Documentation

=head1 DESCRIPTION

Pod is a simple markup language used for writing documentation for
Perl, Perl programs, and Perl modules.

A pod-to-whatever translator reads pod blocks in Perl files and
translates them paragraph by paragraph to the appropriate output
format.

There are three basic kinds of paragraphs:
L<verbatim|/"Verbatim Paragraph">,
L<command|/"Command Paragraph">, and
L<ordinary text|/"Ordinary Block of Text">.

=head2 Verbatim Paragraph

A verbatim paragraph is distinguished by having its first character be
a space or a tab.  (And commonly, all its lines begin with spaces
and/or tabs.)  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.  A verbatim paragraph, or a series of them, is most
commonly used for codeblocks.

=head2 Command Paragraph

All command paragraphs (which are typically only one line long) 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
    =head3 heading
    =head4 heading
    =over N
    =item text
    =back
    =cut
    =pod
    =for X
    =begin X
    =end X

=over 4

=item =head1

=item =head2

=item =head3

=item =head4

Head1 through head4 produce headings, head1 being the highest level.
The text in the rest of this paragraph is the content of the heading.
For example,

  =head2 Object Attributes

The text "Object Attributes" comprises the heading there.  (Note that
head3 and head4 are recent additions, not supported in older pod
translators.)

=item =over

=item =item

=item =back

Item, over, and back require a little more explanation: "=over" starts
a region 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 pod
translators will use this for indentation.  The unit of indentation is
optional; if you don't provide it, some decent default value will be
used.

Note also that there are some basic rules to using =item:

=over

=item *

Don't use them outside of an =over/=back block.

=item *

Use at least one inside an =over/=back block.

=item *

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. -- namely, things that look 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.

=back

=item =cut

To end a pod block, use a line beginning with "=cut".  This lets Perl
(and the pod formatter) know that this is where Perl code is resuming.

=item =pod

You usually start a pod block with an "=item" or a "=head1" or the
like; and a line beginning with a "=" and a word is sufficient to
signal that Perl code has stopped and pod has begun.  But if you just
wanted to have a pod block starting not with an item or a heading or
the like, but with an ordinary paragraph or a verbatim paragraph, just
preface it with a "=pod" command, and a blank line.  The "=pod"
command by itself doesn't do much of anything, but it signals to Perl
(and pod formatters) that a pod block starts here.

=item =for

=item =begin

=item =end

For, begin, and end let you include regions of text/code that are not
generally interpreted as pod text, but are passed directly to
particular formatters.  A formatter that can utilize that format will
use the region, 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 its B<paragraph>, not its line.  Hence in the
examples below, you can see the empty 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

=back

=head2 Ordinary Block of Text

It will be filled, and maybe even justified.  Certain B<interior
sequences> are recognized both here and in commands:

    I<text>     Italicize text, used for emphasis and variables
    B<text>     Embolden text, used for switches and programs
    S<text>     Text contains non-breaking spaces
    C<code>     Render code in a typewriter font, or give some other
                indication that this represents program text
    F<file>	Used for filenames

    L<name>     A link (cross reference) to name:
		  L<name>		manual page (e.g., L<Net::Ping>)
		  L<name/"sec">		section in other manual page
                   or L<name/sec>
		  L</"sec">		section in this manual page
                   or L</sec> or L<"sec">
                  (A section is started by the named heading or item.
                  For example, L<perlvar/$.> or L<perlvar/"$."> both
                  link to the section started by "=item $." in perlvar;
                  and L<perlsyn/For Loops> or L<perlsyn/"For Loops">
                  both link to the section started by "=head2 For Loops"
                  in perlsyn.

		Same as above, but only "text" is used for output:
		    L<text|name>
		    L<text|name/"sec"> or L<text|name/sec>
		    L<text|/"sec"> or L<text/sec> or L<text|"sec">
		
		(Text, name, and section cannot contain the characters
		'/' and '|', and any '<' or '>' should be matched.
		Moreover, name should not contain spaces.)
                
		L<scheme:...>       	link to an absolute URL
		   e.g., L<http://www.perl.org/>
		(There is no corresponding L<name|scheme:...> syntax,
		for various reasons.)

    X<topic>	An index entry  (ignored by most formatters; always
                 renders as empty-string)
    Z<>		A zero-width character  (rarely used)

    E<escape>   A named character (very similar to HTML escapes)
		  E<lt>		A literal <
		  E<gt>		A literal >
		  E<sol>	A literal /
		  E<verbar>	A literal |
		   (The above are optional except in other interior
		    sequences, notably L<>, and when preceded by a
		    capital letter)
		  E<0n>         ASCII character number n (octal)
		  E<n>		ASCII character number n (decimal)
		  E<0xn)        ASCII character number n (hex)
    	    	  E<html>       Some non-numeric HTML entity, such
				  as E<Agrave>
                (Older pod formatters might not recognize octal or
                hex numeric escapes.)

Most of the time, you will only need a single set of angle brackets to
delimit the beginning and end of interior sequences.  However,
sometimes you will want to put a right angle bracket (or greater-than
sign '>') inside of a sequence.  This is particularly common when
using a sequence to provide a different font-type for a snippet of
code.  As with all things in Perl, there is more than one way to do
it.  One way is to simply escape the closing bracket using an C<E>
sequence:

    C<$a E<lt>=E<gt> $b>

This will produce: "C<$a E<lt>=E<gt> $b>"

A more readable, and perhaps more "plain" way is to use an alternate
set of delimiters that doesn't require a ">" to be escaped.  As of
perl5.5.660, doubled angle brackets ("<<" and ">>") may be used I<if
and only if there is whitespace immediately following the opening
delimiter and immediately preceding the closing delimiter!> For
example, the following will do the trick:

    C<< $a <=> $b >>

In fact, you can use as many repeated angle-brackets as you like so
long as you have the same number of them in the opening and closing
delimiters, and make sure that whitespace immediately follows the last
'<' of the opening delimiter, and immediately precedes the first '>'
of the closing delimiter.  So the following will also work:

    C<<< $a <=> $b >>>
    C<<<< $a <=> $b >>>>

This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
and any other pod2xxx and any Pod::Xxxx translator that uses
Pod::Parser 1.093 or later.

=head2 The Intent

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.

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, HTML, TeX, and other markup languages, as used for online
documentation.  Translators exist for B<pod2man> (that's for nroff(1)
and troff(1)), B<pod2text>, B<pod2html>, B<pod2latex>, and B<pod2fm>.
Various others are available in CPAN.

=head2 Embedding Pods in Perl Modules

You can embed pod documentation in your Perl modules and scripts.
Start your documentation with an empty line, a "=head1" command at the
beginning, and end it with a "=cut" command and an empty line.  Perl
will ignore the pod text.  See any of the supplied library modules for
examples.  If you're going to put your pod 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.

    __END__

    =head1 NAME

    modern - I am a modern module

Without that empty line before the "=head1", many translators wouldn't
have recognized the "=head1" as starting a pod block.

=head2 Common Pod Pitfalls

=over 4

=item *

Many pod translators require the lines before every pod command and
after every pod command (including "=cut"!) to be a blank line.
Having something like this:

 # - - - - - - - - - - - -
 =item $firecracker->boom()
 
 This noisily detonates the firecracker object.
 =cut
 sub boom {
 ...

...will make many pod translators completely fail to see the pod block
at all.

Instead, have it like this:

 # - - - - - - - - - - - -
 
 =item $firecracker->boom()
 
 This noisily detonates the firecracker object.
 
 =cut
 
 sub boom {
 ...

=item *

Many pod translators require paragraphs (including command paragraphs
like "=head2 Functions") to be separated by I<completely> empty lines.
If you have an apparently empty line with some spaces on it, this
might not count as a separator for those translators, and that could
cause odd formatting.

=item *

Translators might add wording around a LE<lt>E<gt> link, so that
C<LE<lt>Foo::BarE<gt>> may become "the Foo::Bar manpage", for example.
So you shouldn't write things like C<the LE<lt>fooE<gt>
documentation>, if you want the translated document to read sensibly
-- instead write C<the LE<lt>Foo::Bar|Foo::BarE<gt> documentation> or
C<LE<lt>the Foo::Bar documentation|Foo::BarE<gt>>, to control how the
link comes out.

=item *

Going past the 70th column in a verbatim block might be ungracefully
wrapped by some formatters.

=item *

The B<podchecker> command is provided to check pod syntax for errors
and warnings.  For example, it checks for completely blank lines in
pod segments and for unknown escape sequences.  It is still advised 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<perlpodspec>, L<perlsyn/"PODs: Embedded Documentation">,
L<perlnewmod>, L<perldoc>, L<pod2man>, L<pod2html>, L<podchecker>.

=head1 AUTHOR

Larry Wall

=cut


--
Sean M. Burke    sburke@cpan.org    http://www.spinn.net/~sburke/

Thread Previous


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About