Debian Codegraph @

README

raw
1 NAME
2 Pod::2::DocBook - Convert Pod data to DocBook SGML
3
4 SYNOPSIS
5 use Pod::2::DocBook;
6 my $parser = Pod::2::DocBook->new(
7 title => 'My Article',
8 doctype => 'article',
9 base_id => 'article42'
10 fix_double_quotes => 1,
11 spaces => 3,
12 id_version => 2,
13 );
14
15 $parser->parse_from_file ('my_article.pod', 'my_article.sgml');
16
17 DESCRIPTION
18 Pod::2::DocBook is a module for translating Pod-formatted documents to
19 DocBook 4.2 SGML (see <http://www.docbook.org/>). It is primarily a back
20 end for pod2docbook, but, as a Pod::Parser subclass, it can be used on
21 its own. The only public extensions to the Pod::Parser interface are
22 options available to "new()":
23
24 doctype
25 This option sets the output document's doctype. The currently
26 supported types are article, chapter, refentry and section. Special
27 processing is performed when the doctype is set to refentry (see
28 "Document Types"). You *must* set this option in order to get valid
29 DocBook output.
30
31 fix_double_quotes
32 If this option is set to a true value, pairs of double quote
33 characters ('"') in ordinary paragraphs will be replaced with
34 <quote> and </quote>. See "Ordinary Paragraphs" for details.
35
36 header
37 If this option is set to a true value, Pod::2::DocBook will emit a
38 DOCTYPE as the first line of output.
39
40 spaces
41 Pod::2::DocBook produces pretty-printed output. This option sets the
42 number of spaces per level of indentation in the output.
43
44 title
45 This option sets the output document's title.
46
47 The rest of this document only describes issues specific to
48 Pod::2::DocBook; for details on invoking the parser, specifically the
49 "new()", "parse_from_file()" and "parse_from_filehandle()" methods, see
50 Pod::Parser.
51
52 METHODS
53 use base 'Pod::Parser';
54
55 initialize()
56 Initialize parser.
57
58 begin_pod()
59 Output docbook header stuff.
60
61 end_pod()
62 Output docbook footer. Will print also errors if any in a comment block.
63
64 commans($command, $paragraph, $line_num)
65 Process POD commands.
66
67 textblock ($paragraph, $line_num)
68 Process text block.
69
70 verbatim($paragraph, $line_num)
71 Process verbatim text block.
72
73 interior_sequence($command, $argument, $seq)
74 Process formatting commands.
75
76 error_msg
77 Returns parser error message(s) if any occured.
78
79 make_id($text)
80 default id format -
81
82 Function will construct an element id string. Id string is composed of
83 "join (':', $parser->{base_id}, $text)", where $text in most cases is
84 the pod heading text.
85
86 version 2 id format -
87
88 having ':' in id was not a best choice. (Xerces complains - Attribute
89 value "lib.Moose.Manual.pod:NAME" of type ID must be an NCName when
90 namespaces are enabled.) To not break backwards compatibity switch with
91 <id_version = 2>> in constructor for using '-' instead.
92
93 The xml id string has strict format. Checkout "cleanup_id" function for
94 specification.
95
96 make_uniq_id($text)
97 Calls "$parser->make_id($text)" and checks if such id was already
98 generated. If so, generates new one by adding _i1 (or _i2, i3, ...) to
99 the id string. Return value is new uniq id string.
100
101 cleanup_id($id_string)
102 This function is used internally to remove/change any illegal characters
103 from the elements id string. (see
104 http://www.w3.org/TR/2000/REC-xml-20001006#NT-Name for the id string
105 specification)
106
107 $id_string =~ s/<!\[CDATA\[(.+?)\]\]>/$1/g; # keep just inside of CDATA
108 $id_string =~ s/<.+?>//g; # remove tags
109 $id_string =~ s/^\s*//; # ltrim spaces
110 $id_string =~ s/\s*$//; # rtrim spaces
111 $id_string =~ tr{/ }{._}; # replace / with . and spaces with _
112 $id_string =~ s/[^\-_a-zA-Z0-9\.: ]//g; # closed set of characters allowed in id string
113
114 In the worst case when the $id_string after clean up will not conform
115 with the specification, warning will be printed out and random number
116 with leading colon will be used.
117
118 POD TO DOCBOOK TRANSLATION
119 Pod is a deceptively simple format; it is easy to learn and very
120 straightforward to use, but it is suprisingly expressive. Nevertheless,
121 it is not nearly as expressive or complex as DocBook. In most cases,
122 given some Pod, the analogous DocBook markup is obvious, but not always.
123 This section describes how Pod::2::DocBook treats Pod input so that Pod
124 authors may make informed choices. In every case, Pod::2::DocBook
125 strives to make easy things easy and hard things possible.
126
127 The primary motivation behind Pod::2::DocBook is to facilitate
128 single-source publishing. That is, you should be able to generate man
129 pages, web pages, PDF and PostScript documents, or any other format your
130 SGML and/or Pod tools can produce, from the same Pod source, without the
131 need for hand-editing any intermediate files. This may not always be
132 possible, or you may simply choose to render Pod to DocBook and use that
133 as your single source. To satisfy the first requirement, Pod::2::DocBook
134 always processes the entire Pod source and tries very hard to produce
135 valid DocBook markup, even in the presence of malformed Pod (see
136 "DIAGNOSTICS"). To satisfy the second requirement (and to be a little
137 nifty), Pod::2::DocBook pretty-prints its output. If you're curious
138 about what specific output to expect, read on.
139
140 Document Types
141 DocBook's structure is very modular; many of its document types can be
142 embedded directly into other documents. Accordingly, Pod::2::DocBook
143 will generate four different document types: article, chapter, refentry,
144 and section. This makes it easy, for instance, to write all the chapters
145 of a book in separate Pod documents, translate them into DocBook markup
146 and later glue them together before processing the entire book. You
147 could do the same with each section in an article, or you could write
148 the entire article in a single Pod document. Other document types, such
149 as book and set, do not map easily from Pod, because they require
150 structure for which there is no Pod equivalent. But given sections and
151 chapters, making larger documents becomes much simpler.
152
153 The refentry document type is a little different from the others.
154 Sections, articles, and chapters are essentially composed of nested
155 sections. But a refentry has specialized elements for the *NAME* and
156 *SYNOPSIS* sections. To accommodate this, Pod::2::DocBook performs extra
157 processing on the Pod source when the doctype is set to refentry. You
158 probably don't have to do anything to your document to assist the
159 processing; typical man page conventions cover the requirements. Just
160 make sure that the *NAME* and *SYNOPSIS* headers are both =head1s, that
161 "NAME" and "SYNOPSIS" are both uppercase, and that =head1 NAME is the
162 first line of Pod source.
163
164 Ordinary Paragraphs
165 Ordinary paragraphs in a Pod document translate naturally to DocBook
166 paragraphs. Specifically, after any formatting codes are processed, the
167 characters "<", ">" and "&" are translated to their respective SGML
168 character entities, and the paragraph is wrapped in <para> and </para>.
169
170 For example, given this Pod paragraph:
171
172 Here is some text with I<italics> & an ampersand.
173
174 Pod::2::DocBook would produce DocBook markup similar to this:
175
176 <para>
177 Here is some text with <emphasis role="italic">italics</emphasis>
178 &amp; an ampersand.
179 </para>
180
181 Depending on your final output format, you may sometimes want double
182 quotes in ordinary paragraphs to show up ultimately as "smart quotes"
183 (little 66s and 99s). Pod::2::DocBook offers a convenient mechanism for
184 handling double quotes in ordinary paragraphs and letting your SGML
185 toolchain manage their presentation: the fix_double_quotes option to
186 "new()". If this option is set to a true value, Pod::2::DocBook will
187 replace pairs of double quotes in ordinary paragraphs (and *only* in
188 ordinary paragraphs) with <quote> and </quote>.
189
190 For example, given this Pod paragraph:
191
192 Here is some text with I<italics> & an "ampersand".
193
194 Pod::2::DocBook, with fix_double_quotes set, would produce DocBook
195 markup similar to this:
196
197 <para>
198 Here is some text with <emphasis role="italic">italics</emphasis>
199 &amp; an <quote>ampersand</quote>.
200 </para>
201
202 If you have a paragraph with an odd number of double quotes, the last
203 one will be left untouched, which may or may not be what you want. If
204 you have such a document, replace the unpaired double quote character
205 with E<quot>, and Pod::2::DocBook should be able to give you the output
206 you expect. Also, if you have any =begin docbook ... =end docbook
207 regions (see "Embedded DocBook Markup") in your Pod, you are responsible
208 for managing your own quotes in those regions.
209
210 Verbatim Paragraphs
211 Verbatim paragraphs translate even more naturally; perlpodspec mandates
212 that absolutely no processing should be performed on them. So
213 Pod::2::DocBook simply marks them as CDATA and wraps them in <screen>
214 and </screen>. They are not indented the way ordinary paragraphs are,
215 because they treat whitespace as significant.
216
217 For example, given this verbatim paragraph (imagine there's leading
218 whitespace in the source):
219
220 my $i = 10;
221 while (<> && $i--) {
222 print "$i: $_";
223 }
224
225 Pod::2::DocBook would produce DocBook markup similar to this:
226
227 <screen><![CDATA[my $i = 10;
228 while (<> && $i--) {
229 print "$i: $_";
230 }]] ></screen>
231
232 Multiple contiguous verbatim paragraphs are treated as a single *screen*
233 element, with blank lines separating the paragraphs, as dictated by
234 perlpodspec.
235
236 Command Paragraphs
237 "=head1 Heading Text"
238 "=head2 Heading Text"
239 "=head3 Heading Text"
240 "=head4 Heading Text"
241 All of the Pod heading commands produce DocBook *section* elements,
242 with the heading text as titles. Pod::2::DocBook (perlpod) only
243 allows for 4 heading levels, but DocBook allows arbitrary nesting;
244 see "Embedded DocBook Markup" if you need more than 4 levels.
245 Pod::2::DocBook only looks at relative heading levels to determine
246 nesting. For example, this bit of Pod:
247
248 =head1 1
249
250 Contents of section 1
251
252 =head2 1.1
253
254 Contents of section 1.1
255
256 and this bit of Pod:
257
258 =head1 1
259
260 Contents of section 1
261
262 =head3 1.1
263
264 Contents of section 1.1
265
266 both produce the same DocBook markup, which will look something like
267 this:
268
269 <section id="article-My-Article-1"><title>1</title>
270 <para>
271 Contents of section 1
272 </para>
273 <section id="article-My-Article-1-1"><title>1.1</title>
274 <para>
275 Contents of section 1.1
276 </para>
277 </section>
278 </section>
279
280 Note that Pod::2::DocBook automatically generates section
281 identifiers from your doctype, document title and section title. It
282 does the same when you make internal links (see "Formatting Codes",
283 ensuring that if you supply the same link text as you did for the
284 section title, the resulting identifiers will be the same.
285
286 "=over indentlevel"
287 "=item stuff..."
288 "=back"
289 "=over" ... "=back" regions are somewhat complex, in that they can
290 lead to a variety of DocBook constructs. In every case,
291 *indentlevel* is ignored by Pod::2::DocBook, since that's best left
292 to your stylesheets.
293
294 An "=over" ... "=back" region with no "=item"s represents indented
295 text and maps directly to a DocBook *blockquote* element. Given this
296 source:
297
298 =over 4
299
300 This text should be indented.
301
302 =back
303
304 Pod::2::DocBook will produce DocBook markup similar to this:
305
306 <blockquote>
307 <para>
308 This text should be indented.
309 </para>
310 </blockquote>
311
312 Inside an "=over" ... "=back" region, "=item" commands generate
313 lists. The text that follows the first "=item" determines the type
314 of list that will be output:
315
316 * "*" (an asterisk) produces <itemizedlist>
317
318 * "1" or "1." produces <orderedlist numeration="arabic">
319
320 * "a" or "a." produces <orderedlist numeration="loweralpha">
321
322 * "A" or "A." produces <orderedlist numeration="upperalpha">
323
324 * "i" or "i." produces <orderedlist numeration="lowerroman">
325
326 * "I" or "I." produces <orderedlist numeration="upperroman">
327
328 * anything else produces <variablelist>
329
330 Since the output from each of these is relatively verbose, the best
331 way to see examples is to actually render some Pod into DocBook.
332
333 "=pod"
334 "=cut"
335 Pod::Parser recognizes these commands, and, therefore, so does
336 Pod::2::DocBook, but they don't produce any output.
337
338 "=begin formatname"
339 "=end formatname"
340 "=for formatname text..."
341 Pod::2::DocBook supports two formats: docbook, explained in
342 "Embedded DocBook Markup", and table, explained in "Simple Tables".
343
344 "=encoding encodingname"
345 This command is currently not supported. If Pod::2::DocBook
346 encounters a document that contains "=encoding", it will ignore the
347 command and report an error ("unknown command `%s' at line %d in
348 file %s").
349
350 Embedded DocBook Markup
351 There are a wide range of DocBook structures for which there is no Pod
352 equivalent. For these, you will have to provide your own markup using
353 =begin docbook ... =end docbook or =for docbook .... Pod::2::DocBook
354 will directly output whatever text you provide, unprocessed, so it's up
355 to you to ensure that it's valid DocBook.
356
357 Images, footnotes and many inline elements are obvious candidates for
358 embedded markup. Another possible use is nesting sections more than
359 four-deep. For example, given this source:
360
361 =head1 1
362
363 This is Section 1
364
365 =head2 1.1
366
367 This is Section 1.1
368
369 =head3 1.1.1
370
371 This is Section 1.1.1
372
373 =head4 1.1.1.1
374
375 This is Section 1.1.1.1
376
377 =begin docbook
378
379 <section>
380 <title>1.1.1.1.1</title>
381 <para>This is Section 1.1.1.1.1</para>
382 </section>
383
384 =end docbook
385
386 Pod::2::DocBook will generate DocBook markup similar to this:
387
388 <section id="article-My-Article-1"><title>1</title>
389 <para>
390 This is Section 1
391 </para>
392 <section id="article-My-Article-1-1"><title>1.1</title>
393 <para>
394 This is Section 1.1
395 </para>
396 <section id="article-My-Article-1-1-1"><title>1.1.1</title>
397 <para>
398 This is Section 1.1.1
399 </para>
400 <section id="article-My-Article-1-1-1-1"><title>1.1.1.1</title>
401 <para>
402 This is Section 1.1.1.1
403 </para>
404 <section>
405 <title>1.1.1.1.1</title>
406 <para>This is Section 1.1.1.1.1</para>
407 </section>
408 </section>
409 </section>
410 </section>
411 </section>
412
413 Simple Tables
414 Pod::2::DocBook also provides a mechanism for generating basic tables
415 with =begin table and =end docbook. If you have simple tabular data or a
416 CSV file exported from some application, Pod::2::DocBook makes it easy
417 to generate a table from your data. The syntax is intended to be simple,
418 so DocBook's entire table feature set is not represented, but even if
419 you do need more complex table markup than Pod::2::DocBook produces, you
420 can rapidly produce some markup which you can hand-edit and then embed
421 directly in your Pod with =begin docbook ... =end docbook. Each table
422 definition spans multiple lines, so there is no equivalent =for table
423 command.
424
425 The first line of a table definition gives the table's title. The second
426 line gives a list of comma-separated column specifications (really just
427 column alignments), each of which can be left, center or right. The
428 third line is a list of comma-separated column headings, and every
429 subsequent line consists of comma-separated row data. If any of your
430 data actually contain commas, you can enclose them in double quotes; if
431 they also contain double quotes, you must escape the inner quotes with
432 backslashes (typical CSV stuff).
433
434 Here's an example:
435
436 =begin table
437
438 Sample Table
439 left,center,right
440 Powers of Ten,Planets,Dollars
441 10,Earth,$1
442 100,Mercury,$5
443 1000,Mars,$10
444 10000,Venus,$20
445 100000,"Jupiter, Saturn",$50
446
447 =end table
448
449 And here's what Pod::2::DocBook would do with it:
450
451 <table>
452 <title>Sample Table</title>
453 <tgroup cols="3">
454 <colspec align="left">
455 <colspec align="center">
456 <colspec align="right">
457 <thead>
458 <row>
459 <entry>Powers of Ten</entry>
460 <entry>Planets</entry>
461 <entry>Dollars</entry>
462 </row>
463 </thead>
464 <tbody>
465 <row>
466 <entry>10</entry>
467 <entry>Earth</entry>
468 <entry>$1</entry>
469 </row>
470 <row>
471 <entry>100</entry>
472 <entry>Mercury</entry>
473 <entry>$5</entry>
474 </row>
475 <row>
476 <entry>1000</entry>
477 <entry>Mars</entry>
478 <entry>$10</entry>
479 </row>
480 <row>
481 <entry>10000</entry>
482 <entry>Venus</entry>
483 <entry>$20</entry>
484 </row>
485 <row>
486 <entry>100000</entry>
487 <entry>Jupiter, Saturn</entry>
488 <entry>$50</entry>
489 </row>
490 </tbody>
491 </tgroup>
492 </table>
493
494 Formatting Codes
495 Pod formatting codes render directly into DocBook as inline elements:
496
497 * "I<text>"
498
499 <emphasis role="italic">text</emphasis>
500
501 * "B<text>"
502
503 <emphasis role="bold">text</emphasis>
504
505 * "C<code>"
506
507 <literal role="code"><![CDATA[code]] ></literal>
508
509 * "L<name>"
510
511 <citerefentry><refentrytitle>name</refentrytitle></citerefentry>
512
513 * "L<name(n)>"
514
515 <citerefentry><refentrytitle>name</refentrytitle>
516 <manvolnum>n</manvolnum></citerefentry>
517
518 * "L<name/"sec">" or "L<name/sec>"
519
520 <quote>sec</quote> in <citerefentry>
521 <refentrytitle>name</refentrytitle></citerefentry>
522
523 * "L<name(n)/"sec">" or "L<name(n)/sec>"
524
525 <quote>sec</quote> in <citerefentry>
526 <refentrytitle>name</refentrytitle><manvolnum>n</manvolnum>
527 </citerefentry>
528
529 * "L</"sec">" or "L</sec>" or "L<"sec">"
530
531 <link linkend="article-My-Article-sec"><quote>sec</quote></link>
532
533 * "L<text|name>"
534
535 text
536
537 * "L<text|name/"sec">" or "L<text|name/sec>"
538
539 text
540
541 * "L<text|/"sec">" or "L<text|/sec>" or "L<text|"sec">"
542
543 <link linkend="article-My-Article-sec"><quote>text</quote></link>
544
545 * "L<scheme:...>"
546
547 <ulink url="scheme:...">scheme:...</ulink>
548
549 * "E<verbar>"
550
551 |
552
553 * "E<sol>"
554
555 /
556
557 * "E<number>"
558
559 &#number;
560
561 * any other "E<escape>"
562
563 &escape;
564
565 * "F<filename>"
566
567 <filename>filename</filename>
568
569 * "S<text with spaces>"
570
571 text&nbsp;with&nbsp;spaces
572
573 * "X<topic name>"
574
575 <indexterm><primary>topic name</primary></indexterm>
576
577 DIAGNOSTICS
578 Pod::2::DocBook makes every possible effort to produce valid DocBook
579 markup, even with malformed POD source. Any processing errors will be
580 noted in comments at the end of the output document. Even when errors
581 occur, Pod::2::DocBook always reads the entire input document and never
582 exits with a non-zero status.
583
584 unknown command `%s' at line %d in file %s
585 See "Command Paragraph" in perlpod for a list of valid commands. The
586 command referenced in the error message was ignored.
587
588 formatting code `%s' nested within `%s' at line %d in file %s
589 See "Formatting Codes" in perlpod for details on which formatting
590 codes can be nested. The offending code was translated into the
591 output document as the raw text inside its angle brackets.
592
593 unknown formatting code `%s' at line in file %s
594 The input contained a formatting code not listed in perlpod; it was
595 translated into the output document as the raw text inside the angle
596 brackets.
597
598 empty L<> at line %d in file %s
599 Self-explanatory.
600
601 invalid escape `%s' at line %d in file %s
602 Self-explanatory; it was translated into the output document as the
603 raw text inside the angle brackets.
604
605 =item must be inside an =over ... =back section at line %d in file %s
606 Self-explanatory. The `=item' referenced in the error was ignored.
607
608 `=end %s' found but current region opened with `=begin %s'
609 The closest `=end' command to the referenced `=begin' didn't match;
610 processing continued as if the mismatched `=end' wasn't there.
611
612 no matching `=end' for `=begin %s'
613 Pod::2::DocBook reached the end of its input without finding an
614 `=end' command to match the `=begin' referenced in the error;
615 end-of-file processing continued.
616
617 unknown colspec `%s' in table at line %d in file %s
618 See "Simple Tables" for a list of supported column specifications.
619
620 encountered unknown state `%s' (this should never happen)
621 The state referred to is an internal variable used to properly
622 manage nested DocBook structures. You should indeed never see this
623 message, but if you do, you should contact the module's author.
624
625 SEE ALSO
626 pod2docbook, perlpod, Pod::DocBook, SVN repo -
627 <https://cle.sk/repos/pub/cpan/Pod-2-DocBook/>,
628 <http://www.ohloh.net/projects/pod-2-docbook>, doc/ +
629 examples/pod2docbook-docbook/ for Pod::2::DocBook DocBook documentation
630
631 DocBook related links: <http://www.docbook.org/>,
632 <http://www.sagehill.net/docbookxsl/>,
633 <http://developers.cogentrts.com/cogent/prepdoc/pd-axfrequentlyuseddocbo
634 oktags.html>
635
636 AUTHOR
637 Alligator Descartes <[email protected]> wrote a module called
638 Pod::2::DocBook, which was later maintained by Jan Iven
639 <[email protected]>. That module was based on the original pod2html by
640 Tom Christiansen <[email protected]>.
641
642 Nandu Shah <[email protected]> wrote Pod::DocBook, which is unrelated to
643 the previous module (even though they both perform the same function).
644 (<http://search.cpan.org/~nandu/Pod-DocBook-1.2/>)
645
646 Jozef Kutej <[email protected]> renamed the module to Pod::2::DocBook
647 because Nandus version was buried in the CPAN archive as an
648 "UNAUTHORIZED RELEASE".
649
650 COPYRIGHT
651 Copyright 2004, Nandu Shah <[email protected]>
652
653 Copyright 2008, Jozef Kutej <[email protected]>
654
655 This library is free software; you may redistribute it and/or modify it
656 under the same terms as Perl itself
657