[Python-checkins] CVS: python/dist/src/Doc/doc doc.tex,1.42,1.43
Fred L. Drake
fdrake@users.sourceforge.net
Fri, 06 Jul 2001 15:34:35 -0700
Update of /cvsroot/python/python/dist/src/Doc/doc
In directory usw-pr-cvs1:/tmp/cvs-serv28402/doc
Modified Files:
doc.tex
Log Message:
Add new material on some markup that will be checked in shortly. This
includes some minor new inline markup and markup to generate hyperlinked
grammar productions.
Adopt a "style guide" document -- this beats writing our own and means
we'll have a chance at consistency, without having to make it all up
ourselves.
Index: doc.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/doc/doc.tex,v
retrieving revision 1.42
retrieving revision 1.43
diff -C2 -r1.42 -r1.43
*** doc.tex 2001/06/18 14:59:58 1.42
--- doc.tex 2001/07/06 22:34:33 1.43
***************
*** 154,157 ****
--- 154,194 ----
+ \section{Style Guide}
+
+ The Python documentation should follow the \citetitle
+ [http://developer.apple.com/techpubs/macos8/pdf/apple_styleguide00.pdf]
+ {Apple Publications Style Guide} wherever possible. This particular
+ style guide was selected mostly because it seems reasonable and is
+ easy to get online. (Printed copies are available; see the Apple's
+ \citetitle[http://developer.apple.com/techpubs/faq.html]{Developer
+ Documentation FAQ} for more information.)
+
+ Topics which are not covered in the Apple's style guide will be
+ discussed in this document if necessary.
+
+ Many special names are used in the Python documentation, including
+ the names of operating systems, programming languages, standards
+ bodies, and the like. Many of these were assigned \LaTeX{} macros
+ at some point in the distant past, and these macros lived on long
+ past their usefulness. In the current markup, these entities are
+ not assigned any special markup, but the preferred spellings are
+ given here to aid authors in maintaining the consistency of
+ presentation in the Python documentation.
+
+ \begin{description}
+ \item[POSIX]
+ The name assigned to a particular group of standards. This is
+ always uppercase.
+
+ \item[Python]
+ The name of our favorite programming language is always
+ capitalized.
+
+ \item[Unicode]
+ The name of a character set and matching encoding. This is
+ always written capitalized.
+ \end{description}
+
+
\section{\LaTeX{} Primer \label{latex-primer}}
***************
*** 742,745 ****
--- 779,788 ----
\end{macrodesc}
+ \begin{macrodesc}{infinity}{}
+ The symbol for mathematical infinity: \infinity. Some Web
+ browsers are not able to render the HTML representation of this
+ symbol properly, but support is growing.
+ \end{macrodesc}
+
\begin{macrodesc}{kbd}{\p{key sequence}}
Mark a sequence of keystrokes. What form \var{key sequence}
***************
*** 784,787 ****
--- 827,844 ----
\end{macrodesc}
+ \begin{macrodesc}{pep}{\p{number}}
+ A reference to a Python Enhancement Proposal. This generates
+ appropriate index entries. The text \samp{PEP \var{number}} is
+ generated; in the HTML output, this text is a hyperlink to an
+ online copy of the specified PEP.
+ \end{macrodesc}
+
+ \begin{macrodesc}{plusminus}{}
+ The symbol for indicating a value that may take a positive or
+ negative value of a specified magnitude, typically represented
+ by a plus sign placed over a minus sign. For example:
+ \emph{The lateral movement has a tolerance of \plusminus 3\%{}}.
+ \end{macrodesc}
+
\begin{macrodesc}{program}{\p{name}}
The name of an executable program. This may differ from the
***************
*** 803,813 ****
\end{macrodesc}
- \begin{macrodesc}{pep}{\p{number}}
- A reference to a Python Enhancement Proposal. This generates
- appropriate index entries. The text \samp{PEP \var{number}} is
- generated; in the HTML output, this text is a hyperlink to an
- online copy of the specified PEP.
- \end{macrodesc}
-
\begin{macrodesc}{refmodule}{\op{key}\p{name}}
Like \macro{module}, but create a hyperlink to the documentation
--- 860,863 ----
***************
*** 852,864 ****
\end{macrodesc}
\begin{macrodesc}{url}{\p{url}}
A URL (or URN). The URL will be presented as text. In the HTML
and PDF formatted versions, the URL will also be a hyperlink.
! This can be used when referring to external resources. Note
! that many characters are special to \LaTeX{} and this macro
! does not always do the right thing. In particular, the tilde
! character (\character{\~}) is mis-handled; encoding it as a
! hex-sequence does work, use \samp{\%7e} in place of the tilde
! character.
\end{macrodesc}
--- 902,925 ----
\end{macrodesc}
+ \begin{macrodesc}{ulink}{\p{text}\p{url}}
+ A hypertext link with a target specified by a URL, but for which
+ the link text should not be the title of the resource. For
+ resources being referenced by name, use the \macro{citetitle}
+ macro. Not all formatted versions support arbitrary hypertext
+ links. Note that many characters are special to \LaTeX{} and
+ this macro does not always do the right thing. In particular,
+ the tilde character (\character{\~}) is mis-handled; encoding it
+ as a hex-sequence does work, use \samp{\%7e} in place of the
+ tilde character.
+ \end{macrodesc}
+
\begin{macrodesc}{url}{\p{url}}
A URL (or URN). The URL will be presented as text. In the HTML
and PDF formatted versions, the URL will also be a hyperlink.
! This can be used when referring to external resources without
! specific titles; references to resources which have titles
! should be marked using the \macro{citetitle} macro. See the
! comments about special characters in the description of the
! \macro{ulink} macro for special considerations.
\end{macrodesc}
***************
*** 917,921 ****
be described as a unit --- are documented using the same markup as
modules. The name for a module in a package should be typed in
! ``fully qualified'' form (i.e., it should include the package name).
For example, a module ``foo'' in package ``bar'' should be marked as
\samp{\e module\{bar.foo\}}, and the beginning of the reference
--- 978,982 ----
be described as a unit --- are documented using the same markup as
modules. The name for a module in a package should be typed in
! ``fully qualified'' form (it should include the package name).
For example, a module ``foo'' in package ``bar'' should be marked as
\samp{\e module\{bar.foo\}}, and the beginning of the reference
***************
*** 1300,1328 ****
\end{macrodesc}
! \section{Special Names}
! Many special names are used in the Python documentation, including
! the names of operating systems, programming languages, standards
! bodies, and the like. Many of these were assigned \LaTeX{} macros
! at some point in the distant past, and these macros lived on long
! past their usefulness. In the current markup, these entities are
! not assigned any special markup, but the preferred spellings are
! given here to aid authors in maintaining the consistency of
! presentation in the Python documentation.
! \begin{description}
! \item[POSIX]
! The name assigned to a particular group of standards. This is
! always uppercase.
! \item[Python]
! The name of our favorite programming language is always
! capitalized.
! \item[Unicode]
! The name of a character set and matching encoding. This is
! always written capitalized.
! \end{description}
--- 1361,1431 ----
\end{macrodesc}
+ \subsection{Grammar Production Displays \label{grammar-displays}}
! Special markup is available for displaying the productions of a
! formal grammar. The markup is simple and does not attempt to
! model all aspects of BNF (or any derived forms), but provides
! enough to allow context-free grammars to be displayed in a way
! that causes uses of a symbol to be rendered as hyperlinks to the
! definition of the symbol. There is one environment and a pair of
! macros:
!
! \begin{envdesc}{productionlist}{\op{language}}
! This environment is used to enclose a group of productions. The
! two macros are only defined within this environment. If a
! document descibes more than one language, the optional parameter
! \var{language} should be used to distinguish productions between
! languages. The value of the parameter should be a short name
! that can be used as part of a filename; colons or other
! characters that can't be used in filename across platforms
! should be included.
! \end{envdesc}
!
! \begin{macrodesc}{production}{\p{name}\p{definition}}
! A production rule in the grammar. The rule defines the symbol
! \var{name} to be \var{definition}. \var{name} should not
! contain any markup, and the use of hyphens in a document which
! supports more than one grammar is undefined. \var{definition}
! may contain \macro{token} macros and any additional content
! needed to describe the grammatical model of \var{symbol}. Only
! one \macro{production} may be used to define a symbol ---
! multiple definitions are not allowed.
! \end{macrodesc}
!
! \begin{macrodesc}{token}{\p{name}}
! The name of a symbol defined by a \macro{production} macro, used
! in the \var{definition} of a symbol. Where possible, this will
! be rendered as a hyperlink to the definition of the symbol
! \var{name}.
! \end{macrodesc}
! Note that the entire grammar does not need to be defined in a
! single \env{productionlist} environment; any number of
! groupings may be used to describe the grammar. Every use of the
! \macro{token} must correspond to a \macro{production}.
! The following is an example taken from the
! \citetitle[../ref/identifiers.html]{Python Reference Manual}:
! \begin{verbatim}
! \begin{productionlist}
! \production{identifier}
! {(\token{letter}|"_") (\token{letter} | \token{digit} | "_")*}
! \production{letter}
! {\token{lowercase} | \token{uppercase}}
! \production{lowercase}
! {"a"..."z"}
! \production{uppercase}
! {"A"..."Z"}
! \production{digit}
! {"0"..."9"}
! \end{productionlist}
! \end{verbatim}
!
! \section{Graphical Interface Components}
!
! The components of graphical interfaces will be assigned markup, but
! the specifics have not been determined.