[Python-bugs-list] [ python-Bugs-430627 ] Fixes for templates/module.tex file

[noreply@sourceforge.net]

Bugs item #430627, was updated on 2001-06-06 02:57
You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=105470&aid=430627&group_id=5470

Category: Documentation
Group: None
>Status: Closed
>Resolution: Fixed
Priority: 5
Submitted By: Nobody/Anonymous (nobody)
Assigned to: Fred L. Drake, Jr. (fdrake)
Summary: Fixes for templates/module.tex file

Initial Comment:
Hello,

I am writing some docs for a module I implemented using
the templates/module.tex file (great file BTW).
I found some minor glitches which you may want to fix:

Line 16: Comment says 'descrition' instead of
'description' (one p extra)

Line 134: in "\subsection{Example \label{...}}" is the
space not wanted IMHO.

Line 134 is also not consistent with line 154, where
the \label{..} tag is after the \subsection instead of
within it.

I don't know what to do with global constants (I have a
variable
 NOMATCH='no match' at the global level of the module.
Although the variable may be modified, the idea is that
it is a constant. I don't know how to document that.
The closest match is with \begin{datadesc} I think, but
that is not entirely correct.

While writing I simply assumed that stuff like
\class{xx} or \function{xx} existed. Since LaTeX does
not complain, obviously it does.
I know that documentation about these macro's exists
somewhere but until now, I have not run into it (I
haven't been looking too hard for it though). For other
users, you may want to add a comment near the top of
the file that refers to the exact document that covers
what macro's exist.

Finally, you may want to add some notes how to LaTeX
the module documentation on its own. Basic problem is
that the template file on its own will not be parsed by
LaTeX. I solved the problem by hacking lib/lib.tex and
stripping away most of the existing stuff. A more
elegant approach would be to create a wrapper tex file.

All in all, I think you all did a great job of making
the writing of documentation easier. The existence of
docs for many modules as a large factor in the success
of Python IMHO !!

----------------------------------------------------------------------

>Comment By: Fred L. Drake, Jr. (fdrake)
Date: 2001-06-06 09:14

Message:
Logged In: YES 
user_id=3066

Fixed in the files:

Doc/templates/howto.tex (revisions 1.5, 1.4.12.1)
Doc/templates/manual.tex (revisions 1.3, 1.2.12.1)
Doc/templates/module.tex (revisions 1.22, 1.21.6.1)

The space before the \label{} is considered acceptable, and
is given more often than omitted in the Python
documentation.  This is done primarily for readability; no
problems with formatting have been reported which relate to
this.  It is not an error for LaTeX.

"datadesc" is the appropriate markup for module-level
constants as well as mutable data.  The description should
indicate whether changes from outside the module are
respected.  You can use \constant{} to mark the names of
constants in running text.

The file Doc/templates/howto.tex includes an example showing
how to include a module section in a formattable document. 
If you think this is not sufficient, please file a separate
request for an example showing a wrapper.

Thanks for your comments on the Python documentation!

----------------------------------------------------------------------

You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=105470&aid=430627&group_id=5470