diff options
| -rw-r--r-- | Doc/doc/doc.tex | 30 | ||||
| -rw-r--r-- | Doc/perl/python.perl | 6 | ||||
| -rw-r--r-- | Doc/texinputs/python.sty | 16 |
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 |