diff options
| -rw-r--r-- | Doc/doc/doc.tex | 31 |
1 files changed, 30 insertions, 1 deletions
diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex index 4540267..6de8a7b 100644 --- a/Doc/doc/doc.tex +++ b/Doc/doc/doc.tex @@ -751,11 +751,21 @@ distribution, to create or maintain whole documents or sections. 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. + \begin{envdesc}{seealso}{} This environment creates a ``See also:'' heading and defines the markup used to describe individual references. \end{envdesc} + For each of the following macros, \var{why} should be a complete + sentence, start with a capital letter (unless it starts with an + identifier, which should not be modified), and end with the + apropriate punctuation. + \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 @@ -766,10 +776,29 @@ distribution, to create or maintain whole documents or sections. document (the corresponding \macro{declaremodule} is required). \end{macrodesc} + \begin{macrodesc}{seerfc}{\p{number}\p{title}\p{why}} + Refer to an IETF Request for Comments (RFC). \var{number} + should be the official number assigned by the RFC Editor, + \var{title} should be the human-readable title of the RFC as + found in the official copy of the document, and \var{why} should + explain what's interesting about the RFC. This should be used + to refer the reader to RFCs which specify protocols or data + formats relevant to the material in the annotated section of the + documentation. + \end{macrodesc} + \begin{macrodesc}{seetext}{\p{text}} Add arbitrary text \var{text} to the ``See also:'' list. This can be used to refer to off-line materials or on-line materials - using the \macro{url} macro. + using the \macro{url} macro. This should consist of one or more + complete sentences. + \end{macrodesc} + + \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. \end{macrodesc} |