Bug #18191 for Pod-DocBook: Patch (1.2): Correction of =for blocks; Optional title tags

The following are two e-mails sent to Nandu late last year, and a patch against Pod-Docbook-1.2 (including documentation and tests) that corrects the issues discussed. *** Handling of '=for Docbook' sections *** G'day Nandu, Thank-you for the most excellent Pod::DocBook module. It's saved me hours of time in wrestling with docbook syntax. However, I have found one very small problem in processing. When processing '=for docbook' constructs, Pod::DocBook will escape SGML entries before emitting them. As such, code such as: =for docbook <emphasis>This is important</emphasis> will be emitted as: &lt;emphasis&gt;This is important&lt;emphasis&gt; This differs from the '=begin docbook' blocks and the current documentation, which states that for blocks should pass the text through without modification. Luckily this solution is easily fixed by having Pod::DocBook look for '=for' sections before escaping the text. I've attached a unified diff against Pod::DocBook 1.2 (as found on CPAN) that provides both a test that demonstrates the problem, and a patch to Pod/DocBook.pm that fixes it. Feedback and comments are appreciated. Once again, thank-you for a fantastic module. All the very best, Paul *** Supressing title generation *** G'day Nandu, I'm writing chapters in POD files that will be converted into DocBook using make, however I don't want the title of each chapter to be the filename, instead I want to embed it into the POD. Using Pod::DocBook this should be easy: =for docbook <title>My Chapter Title</title> However, Pod::DocBook always wishes to emit its own title tags, even if the title is an empty string. That means I end up with two titles in the output, which makes DocBook sad. The good news is that it was easy to change Pod::DocBook to not emit any title if an empty title is found. I've attached a patch that includes these changes as well as the contents of my previous patch that fixes for block, as well as tests and documentation updates. Note that we simply test for truth when determining if we should print a title. This allows pod2docbook to be called with a '--title=0' option to indicate that no title should be used. Any feedback, criticism, or comments are appreciated. All the very best, Paul -- Paul Fenwick <pjf@perltraining.com.au> | http://perltraining.com.au/ Director of Training | Ph: +61 3 9354 6001 Perl Training Australia | Fax: +61 3 9354 2681

Index: pod2docbook =================================================================== RCS file: /var/cvs/pod-docbook/pod2docbook,v retrieving revision 1.1.1.1 retrieving revision 1.2 diff -u -r1.1.1.1 -r1.2 --- pod2docbook 28 Sep 2005 01:54:19 -0000 1.1.1.1 +++ pod2docbook 28 Sep 2005 02:36:29 -0000 1.2 @@ -88,7 +88,9 @@ =item [B<--title>=I<title>] Specifies the document title. The default is I<infile>, if it is -supplied, or empty string otherwise. +supplied, or empty string otherwise. If the special title of +C<0> or the empty string is supplied, then title tags will not +be generated by pod2docbook. =item [B<--spaces>=I<# spaces per indent level>] Index: lib/Pod/DocBook.pm =================================================================== RCS file: /var/cvs/pod-docbook/lib/Pod/DocBook.pm,v retrieving revision 1.1.1.1 retrieving revision 1.4 diff -u -r1.1.1.1 -r1.4 --- lib/Pod/DocBook.pm 28 Sep 2005 01:54:19 -0000 1.1.1.1 +++ lib/Pod/DocBook.pm 28 Sep 2005 02:36:29 -0000 1.4 @@ -56,7 +56,10 @@ } else { - print $out_fh "<$parser->{doctype}><title>$parser->{title}</title>\n"; + print $out_fh "<$parser->{doctype}>"; + if ($parser->{title}) { + print $out_fh "<title>$parser->{title}</title>\n"; + } } } @@ -89,6 +92,22 @@ $paragraph =~ s/\s+$//s; $paragraph = $parser->interpolate ($paragraph, $line_num); + + # For blocks must be considered before we escape entries, otherwise + # docbook markup will get mangled. + + if ($command eq 'for') { + $parser->_transition ('for'); + if ($paragraph =~ /^(:\S+|docbook)/) { + $paragraph =~ s/$1\s+//; + print $out_fh $paragraph, "\n"; + return; + } + } + + # Now escape SGML-escape our text, and figure out what to do + # with it. + $paragraph = _fix_chars ($paragraph); if ($command =~ /^head[1-4]/) { @@ -105,14 +124,6 @@ $parser->_transition ("end $paragraph"); } - elsif ($command eq 'for') { - $parser->_transition ('for'); - if ($paragraph =~ /^(:\S+|docbook)/) { - $paragraph =~ s/$1\s+//; - print $out_fh $paragraph, "\n"; - } - } - elsif ($command eq 'over') { $parser->_transition ('over'); push @{$parser->{'Pod::DocBook::state'}}, 'over'; @@ -1109,7 +1120,8 @@ =item title -This option sets the output document's title. +This option sets the output document's title. If set to a false +value then no title will be generated in the output. =back Index: t/Pod-DocBook.t =================================================================== RCS file: /var/cvs/pod-docbook/t/Pod-DocBook.t,v retrieving revision 1.1.1.1 retrieving revision 1.3 diff -u -r1.1.1.1 -r1.3 --- t/Pod-DocBook.t 28 Sep 2005 01:54:19 -0000 1.1.1.1 +++ t/Pod-DocBook.t 28 Sep 2005 02:32:39 -0000 1.3 @@ -5,7 +5,7 @@ use warnings; use Test; -BEGIN { plan tests => 18 }; +BEGIN { plan tests => 20 }; use Pod::DocBook; ok 1; @@ -16,7 +16,7 @@ my @samples = qw(head paragraphs indent lists docbook table formatting_codes e_command e_nested_fc e_unknown_fc e_empty_l e_escape - e_item e_mismatched_end e_no_end e_colspec); + e_item e_mismatched_end e_no_end e_colspec for); foreach my $name (@samples) { my $parser = Pod::DocBook->new (doctype => 'section', @@ -47,6 +47,20 @@ "t/test-no_header.out differs from t/no_header.sgml") && unlink "t/test-no_header.out"; +#----------------------------------------------------------------------- +# test no-title options +#----------------------------------------------------------------------- + +Pod::DocBook->new (doctype => 'chapter', + title => "", + fix_double_quotes => 1, + header => 0, + spaces => 2) + ->parse_from_file ("t/no_title.pod", "t/test-no_title.out"); + +ok (check ("t/no_title.sgml", "t/test-no_title.out"), 1, + "t/test-no_title.out differs from t/no_title.sgml") && + unlink "t/test-no_title.out"; sub check { Index: t/for.pod =================================================================== RCS file: t/for.pod diff -N t/for.pod --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ t/for.pod 28 Sep 2005 02:05:00 -0000 1.1 @@ -0,0 +1 @@ +=for docbook <emphasis>This is important.</emphasis> Index: t/for.sgml =================================================================== RCS file: t/for.sgml diff -N t/for.sgml --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ t/for.sgml 28 Sep 2005 02:05:00 -0000 1.1 @@ -0,0 +1,12 @@ +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.2//EN"> +<!-- + Generated by Pod::DocBook v1.2, using: + Digest::MD5 v2.13 + Pod::Parser v1.13 + Pod::ParseLink v1.05 + Text::ParseWords v3.2 + Text::Wrap v2001.0131 +--> +<section><title>for.pod</title> +<emphasis>This is important.</emphasis> +</section> Index: t/no_title.pod =================================================================== RCS file: t/no_title.pod diff -N t/no_title.pod --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ t/no_title.pod 28 Sep 2005 02:32:39 -0000 1.1 @@ -0,0 +1,8 @@ +=for docbook <title>An example chapter</title> + +=head1 Once upon a time... + +Once upon a time there was a module named Pod::DocBook, it had +many great adventures and lived happily ever after. + +The end. Index: t/no_title.sgml =================================================================== RCS file: t/no_title.sgml diff -N t/no_title.sgml --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ t/no_title.sgml 28 Sep 2005 02:32:39 -0000 1.1 @@ -0,0 +1,19 @@ +<!-- + Generated by Pod::DocBook v1.2, using: + Digest::MD5 v2.13 + Pod::Parser v1.13 + Pod::ParseLink v1.05 + Text::ParseWords v3.2 + Text::Wrap v2001.0131 +--> +<chapter><title>An example chapter</title> + <section id="ID-ac42dda70ff06e57d9f33c7395669b50"><title>Once upon a time...</title> + <para> + Once upon a time there was a module named Pod::DocBook, it had many + great adventures and lived happily ever after. + </para> + <para> + The end. + </para> + </section> +</chapter>