5.004_58 | _04: pod2*,perlpod: L<show this|man/section>

p4raw-id: //depot/perl@508

diff --git a/lib/Pod/Html.pm b/lib/Pod/Html.pm
index d6add62..d03c1b6 100644 (file)
--- 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<show this text|man/section>
+       $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 (file)
--- 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<show this text|man/section>
+       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 (file)
--- 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<verbatim|/"Verbatim Paragraph">,
+L<command|/"Command Paragraph">, and
+L<ordinary text|/"Ordinary Block of Text">.
 
-=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</"sec">           ditto
+               same as above but only 'text' is used for output.
+               (Text can not contain the characters '|' or '>')
+                   L<text|name>
+                   L<text|name/ident>
+                   L<text|name/"sec">
+                   L<text|"sec">
+                   L<text|/"sec">
+               
     F<file>    Used for filenames
     X<index>   An index entry
     Z<>                A zero-width character
@@ -152,7 +190,8 @@ here and in commands:
                    E<html>             Some non-numeric HTML entity, such
                                        as E<Agrave>
 
-=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<pod2man>  (that's for nroff(1) and troff(1)),
-B<pod2html>, B<pod2latex>, and B<pod2fm>.
+B<pod2text>, B<pod2html>, B<pod2latex>, and B<pod2fm>.
 
-=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<pod2man> for details).  Thus, you shouldn't write things like C<the
 LE<lt>fooE<gt> 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 LE<lt>show this text|fooE<gt>
+instead.
+
 =item *
 
 The script F<pod/checkpods.PL> in the Perl source distribution

diff --git a/pod/pod2man.PL b/pod/pod2man.PL
index 5c8afc7..5e5dfb0 100644 (file)
--- 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<show this text|man/section>
+       s:L<([^|>]+)\|[^>]+>:$1:g;
+
        # LREF: a manpage(3f)
        s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the I<$1>$2 manpage:g;