[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