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.

1 files changed, 22 insertions, 8 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}