1Pod::PseudoPod::TutoriaUls(e3r)Contributed Perl DocumentPaotdi:o:nPseudoPod::Tutorial(3)
2
3
4

PseudoPod

6       A Pod Extension for Authoring Large Documents
7
8   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
15         "...I'm not at all claiming this to be sufficient for producing a
16         book."
17
18       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
25       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
30   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
35       Block
36           A region of text that contains one or more lines, such as a
37           paragraph, head, code listing, or figure.
38
39             =begin foo
40
41             Fa la la la la.
42
43             =end foo
44
45       Inline Segment
46           A region of text that contained inside a block, usually within one
47           line, with localized style properties or semantics.
48
49             I I<loved>
50             Proust's T<Remembance of Things Past>.
51
52       Simple Paragraph
53           Just a plain, ordinary block of text. Always unindented.
54
55             Hello there.
56
57       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
61                 x + y = z
62
63       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
67             =head1 What I Did On My Summer Vacation
68
69       Begin Block
70           A block that contains other blocks, usually to create a special
71           structure, such as a figure or sidebar.
72
73             =begin note
74
75             It's not a good idea to stick metal objects
76             into a wall socket.
77
78             =end note
79
80       For Block
81           A block that denotes a special style or semantic, for example to
82           generate a visible comment in text.
83
84             =for production
85
86             In the following paragraph, please use the
87             Mayan petroglyph for corn in place of [corn].
88
89             =end for
90
91   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
96         A bland, uninteresting, boring,
97         garden-variety, nondescript, rudimentary,
98         common, run-of-the-mill, low-key,
99         unassuming, plain old paragraph.
100
101         Another bland, uninteresting, boring,
102         garden-variety, nondescript, rudimentary,
103         common, run-of-the-mill, low-key,
104         unassuming, plain old paragraph.
105
106       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
111       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
114   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
122       Here's an example:
123
124         # generate a magic number
125         sub floopy {
126           my $x = shift;
127
128           if( $x >= 9 ) {
129             return ($x << 3) * 7;
130           } else {
131             return 0;
132           }
133         }
134
135       Blank lines in code are okay. The verbatim block will continue until a
136       simple paragraph or command paragraph interrupt it.
137
138       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
142   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
148         =COMMAND DATA
149
150       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
156       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
161         =begin table graphic Using array references.
162
163       So the data may contain other commands with data, several levels deep.
164       In general, we try to keep it pretty simple, however.
165
166   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
174         =head1 Lizard Feeding Tips
175
176       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
180         =head0 CHAPTER TITLE
181
182         INTRO PARAGRAPH.
183
184         =head1 SECTION TITLE
185
186         INTRO PARAGRAPH.
187
188         =head2 SUBSECTION TITLE
189
190         INTRO PARAGRAPH.
191
192         PARAGRAPH.
193
194           line of code
195             line of code
196               line of code
197             line of code
198           line of code
199
200         ...
201
202       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
209         =head1 A Happy Section
210
211         Blah blah blah blah.
212
213         =head3 A Misplaced Section!
214
215         This section doesn't belong here.
216
217       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
220   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
226         This I<word> should be italicized.
227
228       In this example, the word "word" will be rendered in italics, while all
229       the other words will be treated normally.
230
231       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
241         C<foo>
242         C<<foo>>
243         C<< foo >>
244         C<<<<< foo >>>>>
245
246       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
250          Tag  Meaning                        Example
251          A, L Cross reference to an end      See A<sect-fooby>.
252               point declared with Z<>
253
254          B    Bold                           You make me B<very>
255                                              angry.
256
257          C    Constant Width                 Set the data using the
258                                              method C<setData()>.
259
260          E    Entity reference               The product is x
261                                              E<times> y.
262
263          F    Filename                       Edit the file F<.cshrc>.
264
265          G    Superscript                    E = MCG<2>
266
267          H    Subscript                      HH<2>O
268
269          I    Italic                         Do I<not> eat that.
270
271          M    First occuring term            This phenomenon is
272                                              called M<granulation>.
273
274          N    Footnote                       TheoreticallyN<Meaning,
275                                              "not really>, it's possible.
276
277          R    Replaceable thing              C< R<n> + 2 >, where
278                                              R<n> is the number of pages
279
280          S    Text with non-breaking spaces
281
282          T    Citation                       Read my book, T<Eating Meat
283                                              and Loving It>.
284
285          U    URL                            Download the module from
286                                              U<http://www.cpan.org/>.
287
288          X    Index term                     X<chicken, recipes for>
289
290          Z    A cross reference endpoint     =begin figure My Bedroom
291                                              Z<fig-br>
292
293       Some notes about the above table:
294
295       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
304       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 &times; 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
312       3.  As is also true for all other inlines, the "N" tag, for footnotes,
313           cannot contain multiple paragraphs.
314
315       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
323       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
328       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
331         C<>>
332         C<< x - y > z >
333         T<The Marsupial Handbook, by Joeseph Skrim, is a great...
334
335   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
345       The following is an example, with a paragraph containing a cross
346       reference that points to a figure:
347
348         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
351         =begin figure picture Tunnel Trajectory
352
353         Z<escape-route>
354           ... picture here ...
355
356         =end figure
357
358       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
364       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
369   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
374       bulleted list
375           Place a star after the =item like this:
376
377             =over
378
379             =item * popsicle
380
381             =item *
382             ice cream
383
384             =back
385
386           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
389       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
394             =over
395
396             =item 1 mount bicycle
397
398             =item 1
399             balance on seat
400
401             =item 1 put feet on pedals
402
403             =item 1 pedal quickly so you don't fall over
404
405             =back
406
407           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
411       term-definition list
412           The term immediately follows the =item command, with definition on
413           a new line:
414
415             =over
416
417             =item food
418
419             A thing to ingest that gives you energy and tastes yummy.
420
421             =item mud
422
423             A thing you play with and makes your clothes all dirty.
424
425             =back
426
427       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
431         If you need sugar in a hurry, this list will provide some
432         suggestions:
433
434         =over
435
436         =item 1 Donuts
437
438         There are three principle varieties of this confection:
439
440         =over
441
442         =item 1 Crullers
443
444         =item 1 Roundies
445
446         =item 1 Jellies
447
448         =back
449
450         =item 1 Candy bars
451
452         Even more carbohydrates packed into a convenient, tiny package. Some
453         of my favorites are:
454
455         =over
456
457         =item 1 Payday (nutty)
458
459         =item 1 Snickers (nougaty)
460
461         =item 1 Zagnut (coconutty)
462
463         =back
464
465         =back
466
467   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
472         =begin listing A Frightening Subroutine
473
474         Z<ex-scary>
475
476           for( my $i=0; $i<10; $i++ ) {
477             print "BOO!\n";
478           }
479
480         =end listing
481
482   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
488       •   As a Pod formatted table
489
490       •   As verbatim text
491
492       •   As an HTML-tagged table
493
494       Here's the basic form of a table:
495
496         =begin table TYPE TITLE
497
498         Z<IDENTIFIER>
499
500         CONTENT
501
502         =end table
503
504       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
508         =begin table An Example Table
509
510         =headrow
511
512         =row
513
514         =cell Header for first column (row 1, col 1)
515
516         =cell Header for 2nd column (row 1, col 2)
517
518         =bodyrows
519
520         =row
521
522         =cell Cell for row 2, col 1
523
524         =cell Cell for row 2, col 2
525
526         =row
527
528         =cell Cell for row 3, col 1
529
530         =cell Cell for row 3, col 2
531
532         =end table
533
534       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
541       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
547         =begin table picture Comparing Camels to Horses.
548
549         Z<camel-horse-chart>
550
551           CAMEL                HORSE
552           Lives in desert      Lives in grassland
553           Bumpy                Smooth
554           Spits                Kicks
555
556         =end table
557
558   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
563         =begin figure TYPE TITLE
564
565         Z<IDENTIFIER>
566
567         CONTENT
568
569         =end figure
570
571       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
575         =begin figure graphic My Hairstyle
576
577         Z<fig-hair>
578
579         F<figs/myhair.gif>
580
581         =end figure
582
583       For any other value of TYPE, the parser assumes you drew your own
584       lovely diagram in text:
585
586         =begin figure pikchur My Hairstyle
587
588         Z<fig-hair>
589
590             \  | / //
591             \ \ - / \
592              \ | /
593              (o o)      I look like a pineapple!
594              ( < )
595              (===)
596
597         =end figure
598
599   Other Structures
600       The rest of this tutorial is a mixed bag of oddball stuff you can drop
601       in your book.
602
603       Comments
604
605       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
610         =for editors
611
612         My misspelling of 'antidisestablishmentarianism' in the following
613         paragraph is intentional.
614
615         =end for
616
617       Literal Layouts
618
619       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
623         =begin literal
624
625         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
630         =end literal
631
632       Footnotes
633
634       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
638         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
643       Epigraphs
644
645       For an epigraph, just wrap it up in a =begin epigraph command like
646       this:
647
648         =begin epigraph
649
650         Great art must be licked.
651         --Jas W Felter, Mail Artist
652
653         =end epigraph
654
655       Author Information
656
657       If you need to specify the author's name for a particular chapter or
658       article, use the =author command:
659
660         =author Ferdinand Buscaglia
661
662   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
672       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

POD ERRORS

679       Hey! The above document had some coding errors, which are explained
680       below:
681
682       Around line 334:
683           Non-ASCII character seen before =encoding in 'X.'. Assuming CP1252
684
685
686
687perl v5.32.1                      2021-01-27       Pod::PseudoPod::Tutorial(3)
Impressum