From: Achim Bohnet Date: Wed, 11 Feb 1998 17:29:20 +0000 (+0100) Subject: 5.004_58 | _04: pod2*,perlpod: L X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b74bceb9cc5d8f31510279b2c34ea465fe21fd8f;p=p5sagit%2Fp5-mst-13.2.git 5.004_58 | _04: pod2*,perlpod: L p4raw-id: //depot/perl@508 --- diff --git a/lib/Pod/Html.pm b/lib/Pod/Html.pm index d6add62..d03c1b6 100644 --- a/lib/Pod/Html.pm +++ b/lib/Pod/Html.pm @@ -1344,6 +1344,9 @@ sub process_L { $str =~ s/\n/ /g; # undo word-wrapped tags $s1 = $str; for ($s1) { + # LREF: a la HREF L + $linktext = $1 if s:^([^|]+)\|::; + # a :: acts like a / s,::,/,; @@ -1369,13 +1372,13 @@ sub process_L { $page=$page83 if (defined $pages{$page83}); if ($page eq "") { $link = "#" . htmlify(0,$section); - $linktext = $section; + $linktext = $section unless defined($linktext); } elsif (!defined $pages{$page}) { warn "$0: $podfile: cannot resolve L<$str> in paragraph $paragraph: no such page '$page'\n"; $link = ""; - $linktext = $page; + $linktext = $page unless defined($linktext); } else { - $linktext = ($section ? "$section" : "the $page manpage"); + $linktext = ($section ? "$section" : "the $page manpage") unless defined($linktext); $section = htmlify(0,$section) if $section ne ""; # if there is a directory by the name of the page, then assume that an @@ -1397,7 +1400,7 @@ sub process_L { warn "$0: $podfile: cannot resolve L$str in paragraph $paragraph: ". "no .pod or .pm found\n"; $link = ""; - $linktext = $section; + $linktext = $section unless defined($linktext); } } } diff --git a/lib/Pod/Text.pm b/lib/Pod/Text.pm index 96fda96..67993db 100644 --- a/lib/Pod/Text.pm +++ b/lib/Pod/Text.pm @@ -165,6 +165,10 @@ sub prepare_for_output { s/I<(.*?)>/*$1*/sg; # s/[CB]<(.*?)>/bold($1)/ge; s/X<.*?>//sg; + + # LREF: a la HREF L + s:L<([^|>]+)\|[^>]+>:$1:g; + # LREF: a manpage(3f) s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the $1$2 manpage:g; # LREF: an =item on another manpage diff --git a/pod/perlpod.pod b/pod/perlpod.pod index 6a578ca..d20d62d 100644 --- a/pod/perlpod.pod +++ b/pod/perlpod.pod @@ -7,10 +7,12 @@ perlpod - plain old documentation A pod-to-whatever translator reads a pod file paragraph by paragraph, and translates it to the appropriate output format. There are three kinds of paragraphs: +L, +L, and +L. -=over 4 -=item * +=head2 Verbatim Paragraph A verbatim paragraph, distinguished by being indented (that is, it starts with space or tab). It should be reproduced exactly, @@ -18,9 +20,10 @@ 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. -=item * -A command. All command paragraphs start with "=", followed by an +=head2 Command Paragraph + +All command paragraphs start with "=", followed by an identifier, followed by arbitrary text that the command can use however it pleases. Currently recognized commands are @@ -35,13 +38,29 @@ use however it pleases. Currently recognized commands are =begin X =end X +=over 4 + +=item =pod + +=item =cut + The "=pod" directive does nothing beyond telling the compiler to lay off parsing code through the next "=cut". It's useful for adding another paragraph to the doc if you're mixing up code and pod a lot. +=item =head1 + +=item =head2 + Head1 and head2 produce first and second level headings, with the text in the same paragraph as the "=headn" directive forming the heading description. +=item =over + +=item =back + +=item =item + Item, over, and back require a little more explanation: "=over" starts a section 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 @@ -56,6 +75,13 @@ or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use 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. + +=item =for + +=item =begin + +=item =end + For, begin, and end let you include sections that are not interpreted as pod text, but passed directly to particular formatters. A formatter that can utilize that format will use the section, otherwise it will be @@ -123,9 +149,13 @@ Some examples of lists include: =back -=item * -An ordinary block of text. It will be filled, and maybe even +=back + + +=head2 Ordinary Block of Text + +It will be filled, and maybe even justified. Certain interior sequences are recognized both here and in commands: @@ -140,6 +170,14 @@ here and in commands: L<"sec"> section in this manual page (the quotes are optional) L ditto + same as above but only 'text' is used for output. + (Text can not contain the characters '|' or '>') + L + L + L + L + L + F Used for filenames X An index entry Z<> A zero-width character @@ -152,7 +190,8 @@ here and in commands: E Some non-numeric HTML entity, such as E -=back + +=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 @@ -179,9 +218,10 @@ 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, TeX, and other markup languages, as used for online documentation. Translators exist for B (that's for nroff(1) and troff(1)), -B, B, and B. +B, B, B, and B. -=head1 Embedding Pods in Perl Modules + +=head2 Embedding Pods in Perl Modules You can embed pod documentation in your Perl scripts. Start your documentation with a "=head1" command at the beginning, and end it @@ -201,7 +241,8 @@ directive. If you had not had that empty line there, then the translators wouldn't have seen it. -=head1 Common Pod Pitfalls + +=head2 Common Pod Pitfalls =over 4 @@ -219,6 +260,10 @@ B for details). Thus, you shouldn't write things like CfooE manpage>, if you want the translated document to read sensibly. +If you don need or want total control of the text used for a +link in the output use the form LEshow this text|fooE +instead. + =item * The script F in the Perl source distribution diff --git a/pod/pod2man.PL b/pod/pod2man.PL index 5c8afc7..5e5dfb0 100644 --- a/pod/pod2man.PL +++ b/pod/pod2man.PL @@ -801,6 +801,9 @@ while (<>) { # no break -- usually we want C<> for this s/S<([^<>]*)>/nobreak($1)/eg; + # LREF: a la HREF L + s:L<([^|>]+)\|[^>]+>:$1:g; + # LREF: a manpage(3f) s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the I<$1>$2 manpage:g;