From 72c75c0eeda5f42cfd61589d3594b386ceba9993 Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Thu, 8 Jan 2004 15:00:13 +0000
Subject: add new reference macro: \seelink

---
 Doc/doc/doc.tex          |  9 +++++++++
 Doc/perl/python.perl     | 13 +++++++++++++
 Doc/texinputs/python.sty | 10 ++++++++++
 3 files changed, 32 insertions(+)

diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex
index 47fd3b5..2edaadd 100644
--- a/Doc/doc/doc.tex
+++ b/Doc/doc/doc.tex
@@ -1400,6 +1400,15 @@ This \UNIX\ is also followed by a space.
     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 7d50e49..bdf4937 100644
--- a/Doc/perl/python.perl
+++ b/Doc/perl/python.perl
@@ -1908,6 +1908,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 dba42dd..9638b56 100644
--- a/Doc/texinputs/python.sty
+++ b/Doc/texinputs/python.sty
@@ -1159,6 +1159,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
@@ -1203,6 +1211,7 @@
   \let\seerfc=\py@seerfc
   \let\seetitle=\py@seetitle
   \let\seeurl=\py@seeurl
+  \let\seelink=\py@seelink
 }{\par}
 \newenvironment{seealso}{
   \par
@@ -1214,6 +1223,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
-- 
cgit v0.12