\seetitle: New macro for building reference list content.

3 files changed, 43 insertions, 4 deletions

diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex
index a834ab3..449bb8b 100644
--- a/Doc/doc/doc.tex
+++ b/Doc/doc/doc.tex
@@ -803,10 +803,10 @@ distribution, to create or maintain whole documents or sections.
       markup used to describe individual references.
     \end{envdesc}
 
-    For each of the following macros, \var{why} should be a complete
-    sentence, start with a capital letter (unless it starts with an
-    identifier, which should not be modified), and end with the
-    apropriate punctuation.
+    For each of the following macros, \var{why} should be one or more
+    complete sentences, starting with a capital letter (unless it
+    starts with an identifier, which should not be modified), and
+    ending with the apropriate punctuation.
 
     \begin{macrodesc}{seemodule}{\op{key}\p{name}\p{why}}
       Refer to another module.  \var{why} should be a brief
@@ -844,6 +844,13 @@ distribution, to create or maintain whole documents or sections.
       complete sentences.
     \end{macrodesc}
 
+    \begin{macrodesc}{seetitle}{\op{url}\p{title}\p{why}}
+      Add a reference to an external document named \var{title}.  If
+      \var{url} is given, the title is made a hyperlink in the HTML
+      version of the documentation, and displayed below the title in
+      the typeset versions of the documentation.
+    \end{macrodesc}
+
     \begin{macrodesc}{seeurl}{\p{url}\p{why}}
       References to specific on-line resources should be given using
       the \macro{seeurl} macro.  No title is associated with the
diff --git a/Doc/perl/python.perl b/Doc/perl/python.perl
index f457715..58a4a88 100644
--- a/Doc/perl/python.perl
+++ b/Doc/perl/python.perl
@@ -1444,6 +1444,25 @@ sub do_cmd_seerfc{
     return handle_rfclike_reference(@_[0], "RFC");
 }
 
+sub do_cmd_seetitle{
+    local($_) = @_;
+    my $url = next_optional_argument();
+    my $title = next_argument();
+    my $text = next_argument();
+    if ($url) {
+        return '<dl compact class="seetitle">'
+          . "\n    <dt><em class=\"citetitle\"><a href=\"$url\""
+          . "\n        class=\"url\">$title</a></em>"
+          . "\n    <dd>$text\n  </dl>"
+          . $_;
+    }
+    return '<dl compact class="seetitle">'
+      . "\n    <dt><em class=\"citetitle\""
+      . "\n        >$title</em>"
+      . "\n    <dd>$text\n  </dl>"
+      . $_;
+}
+
 sub do_cmd_seeurl{
     local($_) = @_;
     my $url = next_argument();
diff --git a/Doc/texinputs/python.sty b/Doc/texinputs/python.sty
index 40c870b..fe5db27 100644
--- a/Doc/texinputs/python.sty
+++ b/Doc/texinputs/python.sty
@@ -922,6 +922,17 @@
     \end{fulllineitems}
   }
 }
+% \seetitle[url]{title}{why it's interesting}
+\newcommand{\py@seetitle}[3][\py@modulebadkey]{%
+  \par
+  \begin{fulllineitems}
+    \item[\citetitle{#2}]
+    \ifx\py@modulebadkey#1\else
+      \item[{\small{(\url{#1})}}]
+    \fi
+    #3
+  \end{fulllineitems}
+}
 % \seepep{number}{title}{why it's interesting}
 \newcommand{\py@seepep}[3]{%
   \par%
@@ -951,7 +962,9 @@
   \strong{See Also:}\par
   \def\seetext##1{\par{##1}}
   \let\seemodule=\py@seemodule
+  \let\seepep=\py@seepep
   \let\seerfc=\py@seerfc
+  \let\seetitle=\py@seetitle
   \let\seeurl=\py@seeurl
 }{\par}