Add a new environment in the Python docs markup: seealso*. This is similar

to seealso, but does not add the "See also:" header or put the content in a
box in the HTML version.

Updated the description of \seeurl to better indicate when it should be used;
the old description was written before we had \seetitle.

3 files changed, 41 insertions, 11 deletions

diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex
index 1a7df0a..49e8c49 100644
--- a/Doc/doc/doc.tex
+++ b/Doc/doc/doc.tex
@@ -1302,27 +1302,40 @@ This \UNIX\ is also followed by a space.
 
     Many sections include a list of references to module documentation
     or external documents.  These lists are created using the
-    \env{seealso} environment.  This environment defines some
-    additional macros to support creating reference entries in a
-    reasonable manner.
+    \env{seealso} or \env{seealso*} environments.  These environments
+    define some additional macros to support creating reference
+    entries in a reasonable manner.
 
     The \env{seealso} environment is typically placed in a section
     just before any sub-sections.  This is done to ensure that
     reference links related to the section are not hidden in a
-    subsection in the hypertext renditions of the documentation.
+    subsection in the hypertext renditions of the documentation.  For
+    the HTML output, it is shown as a ``side bar,'' boxed off from the
+    main flow of the text.  The \env{seealso*} environment is
+    different in that it should be used when a list of references is
+    being presented as part of the primary content; it is not
+    specially set off from the text.
 
     \begin{envdesc}{seealso}{}
       This environment creates a ``See also:'' heading and defines the
       markup used to describe individual references.
     \end{envdesc}
 
+    \begin{envdesc}{seealso*}{}
+      This environment is used to create a list of references which
+      form part of the main content.  It is not given a special
+      header and is not set off from the main flow of the text.  It
+      provides the same additional markup used to describe individual
+      references.
+    \end{envdesc}
+
     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.
 
     These macros are only defined within the content of the
-    \env{seealso} environment.
+    \env{seealso} and \env{seealso*} environments.
 
     \begin{macrodesc}{seemodule}{\op{key}\p{name}\p{why}}
       Refer to another module.  \var{why} should be a brief
@@ -1369,9 +1382,10 @@ This \UNIX\ is also followed by a space.
 
     \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
-      reference, but the \var{why} text may include a title marked
-      using the \macro{citetitle} macro.
+      the \macro{seeurl} macro if they don't have a meaningful title.
+      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}
 
 
diff --git a/Doc/perl/python.perl b/Doc/perl/python.perl
index 54a92c5..88f2aa5 100644
--- a/Doc/perl/python.perl
+++ b/Doc/perl/python.perl
@@ -1725,6 +1725,12 @@ sub do_env_seealso{
             . '</div>');
 }
 
+sub do_env_seealsostar{
+    return ("<div class=\"seealso-simple\">\n  "
+            . @_[0]
+            . '</div>');
+}
+
 sub do_cmd_seemodule{
     # Insert the right magic to jump to the module definition.  This should
     # work most of the time, at least for repeat builds....
diff --git a/Doc/texinputs/python.sty b/Doc/texinputs/python.sty
index fa6681e..bddffe7 100644
--- a/Doc/texinputs/python.sty
+++ b/Doc/texinputs/python.sty
@@ -1096,9 +1096,20 @@
     #2
   \end{fulllineitems}
 }
-\newenvironment{seealso}[0]{
+
+\newenvironment{seealso*}{
+  \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}
+\newenvironment{seealso}{
+  \par
+  \strong{See Also:}
   \par
-  \strong{See Also:}\par
   \def\seetext##1{\par{##1}}
   \let\seemodule=\py@seemodule
   \let\seepep=\py@seepep
@@ -1106,7 +1117,6 @@
   \let\seetitle=\py@seetitle
   \let\seeurl=\py@seeurl
 }{\par}
-
 
 % Allow the Python release number to be specified independently of the
 % \date{}.  This allows the date to reflect the document's date and