1Pod::PseudoPod::TutoriaUls(e3r)Contributed Perl DocumentPaotdi:o:nPseudoPod::Tutorial(3)
2
6 A Pod Extension for Authoring Large Documents
7 Introduction
9 Perl's "Plain Old Documentation" format (Pod) is not, by any means, a
10 perfect markup language. It lacks XML's robust features of well-
11 formedness and unambiguous syntax. In fact, it was never intended to be
12 anything more than a simple format for embedding documentation inside
13 programs, as Larry Wall's comment in the perlpod man page alludes:
14 "...I'm not at all claiming this to be sufficient for producing a
16 book."
17 Yet many Pod People -- er, I mean, authors -- want to do just that.
19 Pod is, after all, the darling of Perl hackers everywhere. O'Reilly
20 decided to extend it into the realm of large, complex documents, such
21 as the typical book. This extension, called PseudoPod (thanks to Jason
22 McIntosh for the excellent name), adds some inline tags, block
23 structures, and rules to make processing work smoothly.
24 Before you go any further, you should go and read the perlpod man page,
26 if you haven't already. It lays the foundation for PseudoPod,
27 establishing some important rules for syntax and semantics that we rely
28 on.
29 Terminology
31 Before we dive into the nitty-gritty details of PseudoPod, we should
32 recap the basic concepts of Pod. The following table covers just about
33 everything:
34 Block
36 A region of text that contains one or more lines, such as a
37 paragraph, head, code listing, or figure.
38 =begin foo
40 Fa la la la la.
42 =end foo
44 Inline Segment
46 A region of text that contained inside a block, usually within one
47 line, with localized style properties or semantics.
48 I I<loved>
50 Proust's T<Remembance of Things Past>.
51 Simple Paragraph
53 Just a plain, ordinary block of text. Always unindented.
54 Hello there.
56 Verbatim Paragraph
58 A section of code, screen output, or an equation whose space and
59 characters need to be preserved, verbatim. Always indented.
60 x + y = z
62 Command Paragraph
64 Start a new block style of one or more lines. Multi-line commands
65 may require another command to end the block.
66 =head1 What I Did On My Summer Vacation
68 Begin Block
70 A block that contains other blocks, usually to create a special
71 structure, such as a figure or sidebar.
72 =begin note
74 It's not a good idea to stick metal objects
76 into a wall socket.
77 =end note
79 For Block
81 A block that denotes a special style or semantic, for example to
82 generate a visible comment in text.
83 =for production
85 In the following paragraph, please use the
87 Mayan petroglyph for corn in place of [corn].
88 =end for
90 Simple Paragraphs
92 Simple paragraphs are well-named, for they have no special formatting
93 requirements other than to separate them with a blank line. Here are
94 two simple paras living together in a file:
95 A bland, uninteresting, boring,
97 garden-variety, nondescript, rudimentary,
98 common, run-of-the-mill, low-key,
99 unassuming, plain old paragraph.
100 Another bland, uninteresting, boring,
102 garden-variety, nondescript, rudimentary,
103 common, run-of-the-mill, low-key,
104 unassuming, plain old paragraph.
105 Simple paragraphs will not preserve special spacing. Pod formatters are
107 allowed to throw away line breaks, adjust line width, and make any
108 other changes to beautify the paragraphs. If you need to preserve
109 spacing for any reason, you should use a verbatim paragraph.
110 Note that simple paragraphs may not be indented. Any indented line will
112 be treated as a line of code in a separate block.
113 Verbatim Paragraphs
115 A verbatim paragraph will, unlike the simple paragraph type, preserve
116 all spaces and linebreaks. It's distinguished by indenting every line
117 at least one space. The amount doesn't matter, as long as subsequent
118 lines are indented as least as much as the first line. The Pod parser
119 will measure the first line's indentation and subtract it from
120 following lines.
121 Here's an example:
123 # generate a magic number
125 sub floopy {
126 my $x = shift;
127 if( $x >= 9 ) {
129 return ($x << 3) * 7;
130 } else {
131 return 0;
132 }
133 }
134 Blank lines in code are okay. The verbatim block will continue until a
136 simple paragraph or command paragraph interrupt it.
137 Please do not use tabs! Tab characters are unpredictible. We will try
139 to convert them into strings of 8 spaces, but that might not be what
140 you want. So, to be unambiguous about it, please only use spaces.
141 Command Paragraphs
143 Command paragraphs are used for all other structures in Pod. The
144 command takes the form of an equals sign (=) followed by some string of
145 alphabetic characters and either a newline or a space and an optional
146 string of data. It looks like this:
147 =COMMAND DATA
149 The equals sign must be the first character on the line or it will be
151 interpreted as something else. If you need to place an equals sign at
152 the beginning of a line, you should use an inline tag like "=" to
153 encapsulate it. It's good style, but not required, to precede and
154 follow a command paragraph with blank lines.
155 The data can be anything, and it depends on the context what will be
157 done with it. A =head1 command would use data as a section title. This
158 line would begin a table and use everything after the word "graphic" as
159 the title of the table:
160 =begin table graphic Using array references.
162 So the data may contain other commands with data, several levels deep.
164 In general, we try to keep it pretty simple, however.
165 Heads and Document Structure
167 The most common command paragraph type is the head. A head takes the
168 form of =headN TITLE where N is a single digit from 0 to 4, inversely
169 proportional to its level of significance and TITLE is the text to be
170 used in the head. Level 0 is for the title of a chapter, while level 4
171 is a sub-sub-sub-section (also called a D-head). An A-head, or level 1
172 section, would look like this:
173 =head1 Lizard Feeding Tips
175 Pod books typically are split up into multiple files, each containing a
177 single chapter, appendix, or part page (intro to a part of the book).
178 Every PseudoPod file should follow this pattern:
179 =head0 CHAPTER TITLE
181 INTRO PARAGRAPH.
183 =head1 SECTION TITLE
185 INTRO PARAGRAPH.
187 =head2 SUBSECTION TITLE
189 INTRO PARAGRAPH.
191 PARAGRAPH.
193 line of code
195 line of code
196 line of code
197 line of code
198 line of code
199 ...
201 The file should always start with a =head0 which corresponds to a
203 chapter or appendix title. There should be only one per file.
204 Following that is a =head1 which starts a new section. This may be
205 followed by a =head2 and so on down to =head4, but no further than
206 that. Please be careful to nest section levels properly. It's an error
207 to have something line this:
208 =head1 A Happy Section
210 Blah blah blah blah.
212 =head3 A Misplaced Section!
214 This section doesn't belong here.
216 So never let a =head3 follow a =head1 without an intervening =head2 or
218 the parser will likely burst into flames. And it's bad style too.
219 Inline Character Tagging
221 Inline character tags, also known as interior sequences in Pod
222 parlance, are a special syntactic form that delineates special
223 treatment for character sequences inside a block. For example, to mark
224 a word so that it has italic font style, you would do this:
225 This I<word> should be italicized.
227 In this example, the word "word" will be rendered in italics, while all
229 the other words will be treated normally.
230 The general form of an inline tag is a single character (A-Z are
232 currently supported), followed by a start delimiter and end delimiter.
233 The simplest delimiters are angle brackets (< and >). But sometimes
234 these aren't enough. If you need to enclose the character >, for
235 example, then you have to use an alternate delimiter set so the parser
236 won't be confused. In that case, you can use multiples of < and >, as
237 long as the number of braces on the left match the number on the right.
238 You can also add space between brackets and data, which will be
239 stripped. These all do the same thing:
240 C<foo>
242 C<<foo>>
243 C<< foo >>
244 C<<<<< foo >>>>>
245 We have tried to preserve all the inline tags defined in the original
247 Pod spec. The set used by PseudoPod adds a bunch more. The following
248 table lays out the tags and their meanings:
249 Tag Meaning Example
251 A, L Cross reference to an end See A<sect-fooby>.
252 point declared with Z<>
253 B Bold You make me B<very>
255 angry.
256 C Constant Width Set the data using the
258 method C<setData()>.
259 E Entity reference The product is x
261 E<times> y.
262 F Filename Edit the file F<.cshrc>.
264 G Superscript E = MCG<2>
266 H Subscript HH<2>O
268 I Italic Do I<not> eat that.
270 M First occuring term This phenomenon is
272 called M<granulation>.
273 N Footnote TheoreticallyN<Meaning,
275 "not really>, it's possible.
276 R Replaceable thing C< R<n> + 2 >, where
278 R<n> is the number of pages
279 S Text with non-breaking spaces
281 T Citation Read my book, T<Eating Meat
283 and Loving It>.
284 U URL Download the module from
286 U<http://www.cpan.org/>.
287 X Index term X<chicken, recipes for>
289 Z A cross reference endpoint =begin figure My Bedroom
291 Z<fig-br>
292 Some notes about the above table:
294 1. The "A" tag will be replaced with some generated text that
296 references another object. Its data is a unique indentifier string
297 that matches a "Z" tag elsewhere in the document. So, if there is
298 an A head followed by a "Z<floof>", then you can insert "A<floof>"
299 anywhere in the document. It will be replaced with something like
300 "Section 3.4, 'Gloppy Drainpipes'" or whatever makes sense in that
301 context. This will work with sections, chapters, tables, examples,
302 or figures.
303 2. In standard Pod, "E" means any escaped character, but we have taken
305 this further. In PseudoPod, the data in "E" is the name of an XML
306 entity, as defined in ISO-8879. So, translated into XML it would
307 wind up as × and when translated into Unicode, it would
308 become the multiplication symbol X. For a complete list of these
309 entities, consult DocBook, The Definitive Guide by Walsh and
310 Muellner, which contains a handy table in an appendix.
311 3. As is also true for all other inlines, the "N" tag, for footnotes,
313 cannot contain multiple paragraphs.
314 4. The "X" tag will not be displayed where it's invoked. Instead, the
316 parser will stash it away to use in building the index later.
317 (Technically, it will still be located there after conversion, but
318 in another form that is also invisible.) Separate primary,
319 secondary, and tertiary terms with a comma. Start the data with the
320 words "See" or "See also" to create an index entry that redirects
321 to another term. Only one "X" tag per entry is allowed.
322 5. The "Z" tag always follows a command paragraph to which it lends
324 its data as an identifier. Elsewhere in the file, an "A" tag will
325 contain the same data, setting up a cross reference to that
326 structure.
327 The most common type of error we see in Pod files is imbalanced
329 delimiters in inline tags. Be wary of this! These are all errors:
330 C<>>
332 C<< x - y > z >
333 T<The Marsupial Handbook, by Joeseph Skrim, is a great...
334 Cross References
336 Cross references are easy, if you remember where to put the link
337 endpoints. We've named the two inline tag types for internal cross
338 references to be easy to remember. Just think, "from A to Z".
339 "A<DATA>" starts a cross reference to an object with an identifer
340 "DATA". It can appear inside any simple paragraph or list. "Z<DATA>"
341 completes a cross reference by labelling the object that contains it
342 "DATA". It always appears inside a structure, right after the command
343 paragraph that starts it, like a figure or section.
344 The following is an example, with a paragraph containing a cross
346 reference that points to a figure:
347 Our escape route takes us underneath the prison wall, out into an
349 old apple orchard. The map is detailed in A<escape-route>.
350 =begin figure picture Tunnel Trajectory
352 Z<escape-route>
354 ... picture here ...
355 =end figure
357 It doesn't matter if the "A" tag comes before or after the "Z" tag, nor
359 how many times the "Z" is referenced. However, every "A" must reference
360 an existing "Z", and no two "Z" tags can contain the same identifier.
361 It's not a fatal error, but will cause the parser to complain and be
362 unable to complete the link.
363 If you want to reference something in another file, it works the same
365 way. However, all the files share the same namespace for identifiers.
366 Make sure that you don't use the same identifier twice in different
367 files or cross references will behave unpredictibly.
368 Lists
370 A list always begins with a =over command and ends with a =back
371 command. List items start with =item and can take several forms,
372 depending on the kind of list:
373 bulleted list
375 Place a star after the =item like this:
376 =over
378 =item * popsicle
380 =item *
382 ice cream
383 =back
385 Note that it doesn't matter if the item text continues on the same
387 line as the star or begins on a new line.
388 numbered list
390 Place a number after the =item. The actual value doesn't matter, as
391 the formatter will number items automatically, so typically people
392 just use the number "1":
393 =over
395 =item 1 mount bicycle
397 =item 1
399 balance on seat
400 =item 1 put feet on pedals
402 =item 1 pedal quickly so you don't fall over
404 =back
406 Again, it doesn't matter if you continue on the same line with item
408 text. Longer paras will probably be more readable if you use a new
409 line.
410 term-definition list
412 The term immediately follows the =item command, with definition on
413 a new line:
414 =over
416 =item food
418 A thing to ingest that gives you energy and tastes yummy.
420 =item mud
422 A thing you play with and makes your clothes all dirty.
424 =back
426 Lists can be nested, and each list item can hold multiple paragraphs.
428 But please, no tables or figures inside lists. They're icky and make
429 the parser sad. Here's a complex example:
430 If you need sugar in a hurry, this list will provide some
432 suggestions:
433 =over
435 =item 1 Donuts
437 There are three principle varieties of this confection:
439 =over
441 =item 1 Crullers
443 =item 1 Roundies
445 =item 1 Jellies
447 =back
449 =item 1 Candy bars
451 Even more carbohydrates packed into a convenient, tiny package. Some
453 of my favorites are:
454 =over
456 =item 1 Payday (nutty)
458 =item 1 Snickers (nougaty)
460 =item 1 Zagnut (coconutty)
462 =back
464 =back
466 Examples
468 An example is simply a wrapper for something to give it a title and
469 hook for cross references. The usual candidate for inclusion is a code
470 listing. Here's an example:
471 =begin listing A Frightening Subroutine
473 Z<ex-scary>
475 for( my $i=0; $i<10; $i++ ) {
477 print "BOO!\n";
478 }
479 =end listing
481 Tables
483 A table is a great way to convey complex information in a compact way.
484 Unfortunately, tables are themselves complex when it comes to markup.
485 We realize that authors don't like to be constrained in complex markup
486 scenarios, so we offer three ways to markup tables:
487 • As a Pod formatted table
489 • As verbatim text
491 • As an HTML-tagged table
493 Here's the basic form of a table:
495 =begin table TYPE TITLE
497 Z<IDENTIFIER>
499 CONTENT
501 =end table
503 The preferred method is the PseudoPod table format which has =row and
505 =cell tags, as well as =headrow to mark the heading row and =bodyrows
506 to mark the start of the main body of the table:
507 =begin table An Example Table
509 =headrow
511 =row
513 =cell Header for first column (row 1, col 1)
515 =cell Header for 2nd column (row 1, col 2)
517 =bodyrows
519 =row
521 =cell Cell for row 2, col 1
523 =cell Cell for row 2, col 2
525 =row
527 =cell Cell for row 3, col 1
529 =cell Cell for row 3, col 2
531 =end table
533 The second method is a freestyle, anything-goes format. Make your own
535 columns and headers any way you want. The plus side is: infinite
536 creativity! The downside is: we will end up recoding the whole table
537 ourselves in production which slows us down a bit. Just try to make it
538 clear what is in which column and on what row, and it will be okay with
539 us.
540 The table markup is a wrapper, similar to examples, but with an extra
542 keyword, TYPE, to denote the kind of table. If the keyword is "html",
543 our parser will read it like an HTML table. If it's anything else, like
544 "graphic" or "picture", it will be treated as an ASCII rendering. For
545 example:
546 =begin table picture Comparing Camels to Horses.
548 Z<camel-horse-chart>
550 CAMEL HORSE
552 Lives in desert Lives in grassland
553 Bumpy Smooth
554 Spits Kicks
555 =end table
557 Figures
559 A figure holds some kind of picture, whether an imported graphic or an
560 ASCII masterpiece you paint yourself. The general form is similar to a
561 table's:
562 =begin figure TYPE TITLE
564 Z<IDENTIFIER>
566 CONTENT
568 =end figure
570 If the TYPE is "graphic", then the parser will expect to see a
572 reference to an external file, the name of a graphic to import. For
573 example:
574 =begin figure graphic My Hairstyle
576 Z<fig-hair>
578 F<figs/myhair.gif>
580 =end figure
582 For any other value of TYPE, the parser assumes you drew your own
584 lovely diagram in text:
585 =begin figure pikchur My Hairstyle
587 Z<fig-hair>
589 \ | / //
591 \ \ - / \
592 \ | /
593 (o o) I look like a pineapple!
594 ( < )
595 (===)
596 =end figure
598 Other Structures
600 The rest of this tutorial is a mixed bag of oddball stuff you can drop
601 in your book.
602 Comments
604 If you want to leave a comment in the manuscript for somebody to see,
606 you can use the =for command. The data in the command specifies who the
607 comment is for. Typical designations include "production", "author",
608 and "editor". For instance:
609 =for editors
611 My misspelling of 'antidisestablishmentarianism' in the following
613 paragraph is intentional.
614 =end for
616 Literal Layouts
618 If you want something to be treated like a verbatim paragraph, but not
620 rendered in constant width font, then use =begin literal. Here's a bit
621 of poetry done up like that:
622 =begin literal
624 As I was going up the stair,
626 I met a man who was not there.
627 He wasn't there again today;
628 I wish that man would go away.
629 =end literal
631 Footnotes
633 Footnotes use the "N" inline tag to locate them inside blocks.
635 Strangely, they also function like blocks in that they can be many
636 lines long. The following example shows how you might use them:
637 O'Reilly books often contain footnotes,N<Perl books especially, it
639 would seemN<Though I wouldn't go so far as to say they I<overdo>
640 it.>.> though I believe that house style limits them to three per
641 page.N<Uh oh.>
642 Epigraphs
644 For an epigraph, just wrap it up in a =begin epigraph command like
646 this:
647 =begin epigraph
649 Great art must be licked.
651 --Jas W Felter, Mail Artist
652 =end epigraph
654 Author Information
656 If you need to specify the author's name for a particular chapter or
658 article, use the =author command:
659 =author Ferdinand Buscaglia
661 History
663 PseudoPod was originally the brainchild of Jason "J-mac" McIntosh who
664 worked for O'Reilly's Publishing Tools Group. It was used for many
665 venerable Perl books, including several revisions of the Camel and
666 Llama. The Pod::PseudoPod modules were developed by Allison Randal
667 while writing a book for O'Reilly as an easy-to-use and easy-to-install
668 alternative to O'Reilly's internal PseudoPod parsing and formatting
669 tools, to allow authors to check their formatting before submitting
670 files.
671 As of 2007, PsuedoPod is no longer used or maintained by O'Reilly,
673 after they switched all their manuscripts to DocBook. Pod::PseudoPod is
674 now the primary parser for PseudoPod, and includes
675 Pod::PseudoPod::DocBook to generate DocBook output suitable for
676 submission to O'Reilly.
677
679 Hey! The above document had some coding errors, which are explained
680 below:
681 Around line 334:
683 Non-ASCII character seen before =encoding in 'X.'. Assuming CP1252
684perl v5.32.1 2021-01-27 Pod::PseudoPod::Tutorial(3)