[l2h] Book recommendations anyone?
Fred L. Drake, Jr.
fdrake@acm.org
Mon, 20 May 2002 10:06:54 -0400
[Dave: I don't know how interested other L2H users are in this; if
you'd like to pursue using the Python tools, we can move this to the
Python Doc-SIG list, where this is clearly ontopic.]
I wrote:
> Are you using the tools for formatting the Python documentation?
> What would you do differently?
Dave Cole writes:
> A few things have me stumped:
>
> 1) \verbatiminput does not use the same size font as \verbatim. It
> does not indent the same,
This has been fixed in the CVS version of the tools.
> and the Python tools use `basename`.txt
> to build a "download as text" file. When you have more than one
> file which differ only in suffix, this is a problem.
An excellent point; I'll count this as a bug that need to be fixed:
http://sourceforge.net/tracker/index.php?func=detail&aid=558279&group_id=5470&atid=105470
> 2) The argument list formatting for methoddesc (and others) does not
> wrap long argument lists.
>
> Check this out:
> http://www.object-craft.com.au/projects/albatross/albatross/pack-simplesessapp.html
I don't think I see the problem. Is it the constructor argument list?
It wraps for me once I shrink the window (Mozilla 0.9.9).
> The PDF document truncates the argument list.
This is painful, and I'm not sure how to fix it. The problem is
really two-fold:
1. The signature line is an \item in a list environment, and I've no
idea how to get that to do any sort of line wrapping.
2. I don't know how to get it to wrap where I want it to. Ideally, a
long list of arguments should be wrapped, but line up after the
opening parenthesis:
myMethod(arg1, arg2, ...,
argN)
> 3) The List of Figures is a bit non-functional in HTML (probably my
> fault).
How are you marking figures? We've not been using that with the
Python documentation, so I have no idea how that works. If you can
supply a short sample document via private email, I'll take a look at
what can be done.
While we're on figures, how are you generating the UML diagrams?
> There are other things which I want to have a fiddle with, but they
> are not really problems.
Feel free to elucidate!
> Fred> If you're not using the tools that come with the Python source
> Fred> distribution to format the documentation, please take a look at
> Fred> those; you can find some documentation for the markup we use in
> Fred> "Documenting Python", included as part of the standard
> Fred> documentation.
>
> The stuff which comes with Python is awesome.
Thanks!
-Fred
--
Fred L. Drake, Jr. <fdrake at acm.org>
PythonLabs at Zope Corporation