add new reference macro: \seelink

3 files changed, 33 insertions, 1 deletions

diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex
index 2270968..aacce2f 100644
--- a/Doc/doc/doc.tex
+++ b/Doc/doc/doc.tex
@@ -1395,11 +1395,20 @@ This \UNIX\ is also followed by a space.
     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.
+    ending with the appropriate punctuation.
 
     These macros are only defined within the content of the
     \env{seealso} and \env{seealso*} environments.
 
+    \begin{macrodesc}{seelink}{\p{url}\p{linktext}\p{why}}
+      References to specific on-line resources should be given using
+      the \macro{seelink} macro if they don't have a meaningful title
+      but there is some short description of what's at the end of the
+      link.  Online documents which have identifiable titles should be
+      referenced using the \macro{seetitle} macro, using the optional
+      parameter to that macro to provide the URL.
+    \end{macrodesc}
+
     \begin{macrodesc}{seemodule}{\op{key}\p{name}\p{why}}
       Refer to another module.  \var{why} should be a brief
       explanation of why the reference may be interesting.  The module
diff --git a/Doc/perl/python.perl b/Doc/perl/python.perl
index 5ef3b27..89e12d5 100644
--- a/Doc/perl/python.perl
+++ b/Doc/perl/python.perl
@@ -1950,6 +1950,19 @@ sub do_cmd_seetitle{
       . $_;
 }
 
+sub do_cmd_seelink{
+    local($_) = @_;
+    my $url = next_argument();
+    my $linktext = next_argument();
+    my $text = next_argument();
+    my $icon = get_link_icon($url);
+    return '<dl compact class="seeurl">'
+      . "\n    <dt><a href='$url'"
+      . "\n        >$linktext$icon</a></dt>"
+      . "\n    <dd>$text</dd>\n  </dl>"
+      . $_;
+}
+
 sub do_cmd_seeurl{
     local($_) = @_;
     my $url = next_argument();
diff --git a/Doc/texinputs/python.sty b/Doc/texinputs/python.sty
index d8071ee..ff37ad9 100644
--- a/Doc/texinputs/python.sty
+++ b/Doc/texinputs/python.sty
@@ -1160,6 +1160,14 @@
   }
 \fi
 
+% \seelink{url}{link text}
+\newcommand{\py@seelink}[3]{%
+  \par
+  \begin{fulllineitems}
+    \item[\ulink{#2}{#1}]
+    #3
+  \end{fulllineitems}
+}
 % \seetitle[url]{title}{why it's interesting}
 \newcommand{\py@seetitle}[3][\py@modulebadkey]{%
   \par
@@ -1204,6 +1212,7 @@
   \let\seerfc=\py@seerfc
   \let\seetitle=\py@seetitle
   \let\seeurl=\py@seeurl
+  \let\seelink=\py@seelink
 }{\par}
 \newenvironment{seealso}{
   \par
@@ -1215,6 +1224,7 @@
   \let\seerfc=\py@seerfc
   \let\seetitle=\py@seetitle
   \let\seeurl=\py@seeurl
+  \let\seelink=\py@seelink
 }{\par}
 
 % Allow the Python release number to be specified independently of the