\seetitle: New macro for building reference list content.
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 @@
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 @@
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 @@
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}