Re: [HappyDoc-discuss] Latex formatter and design questions

[Doug H. <do...@he...>]

On Monday 23 December 2002 4:19 pm, Magos=E1nyi =C1rp=E1d wrote:
> Hi!
>
> I am writing a Latex formatter for happydoc. It is now functional,
> utilizes the hyperref latex package, so able to create nice crossrefere=
nced

Great!

> pdf documentation, but the code is not very well thought-out.
> I have some question regarding the design of happydoc.
>
> My main problem while writing the formatter was that the formatter
> gets only syntactic (as opposed to semantic) information from the
> docset code. What I have done is that I have invented some new
> methods of the formatter class:
> 	beginModule
> 	endModule
> 	beginClass
> 	endClass
> 	beginFunction
> 	endFunction
> 	beginClassesofMod
> 	endClassesofMod
> 	beginFuncsofMod
> 	endFuncsofMod
> 	beginImports
> 	endImports
> 	noImports
> 	getStructuredLabel
> 	getStructuredReference
>
> Before I did this, I made a short attempt to utilize the xml formatter
> base, but that (at least in my copy which is the debian package
> python-happydoc 2.0-2) was unuseable. And anyway, I guess the problem l=
ays

One of the XML formatters does have serious problems.  I think I changed =
some=20
APIs and the formatter author hasn't caught up yet, so it is my fault.

> deeper: I think that the interface between the docset code and the
> formatter code is not the best.

I couldn't agree more.  I have a couple of pernicious bugs related to whe=
re=20
files are written, how they are named, building cross references, etc. =20
Basically the same list you cite as problems in the work you were doing.

> My proposal is that the docset code should be concerned solely with the
> structure of the document: "where the parts of the documentation
> reside in the disc and within the document?", and the formatter be
> responsible for the actual format of the parts of the document. For thi=
s,

I'm currently working on HappyDoc 3.0, which is going to be a complete=20
re-write to solve some of these design problems as well as add some new=20
features.  The biggest change is that the docset and formatter plugins ar=
e=20
merged into a single plugin.  The idea that the docsets and formatters co=
uld=20
be mixed and matched turned out to be less feasible than I originally=20
thought.  There were several cases where both a docset and a formatter ne=
eded=20
to be written, and there was a 1:1 mapping between them (OpenOffice, PDF,=
=20
etc.).

So, the docset is used by HappyDoc 3.0 through the "write()" method, and =
that=20
is the only API required for the application.  Everything else is handled=
=20
inside the docset itself.  I am going to provide base classes for the doc=
set=20
for single and multiple files on the file system, to simplify the work of=
=20
development.  There will be an API similar to what you have laid out.  Th=
e=20
author of a new docset could either choose to override those methods to=20
provide output in a different format, or they can create docset plugins=20
without subclassing as long as their class has a write() method.

> the docset should call methods of the formatter which refer to the
> structure, and not to the syntax of the document, and should pass the
> objects, not some names of them. (It made me some hard minutes to figur=
e
> out where the reference to a module gets "Module: " prepended to it, an=
d
> some hard hours to come up with a consistent method for cross-referenci=
ng.)
>
> I have created a MultipleFileX and a SingleFileX docset which calls the
> above-mentioned methods of the formatter, and of course the Latex forma=
tter
> uses these methods. Now the old formatter methods are also called from =
the
> docsets. The question is: how to do the transition? I can think of two
> ways:
>
> way #1: use the new docsets for new formatters, and the old ones for ol=
d
> formatters. pros:
> 		the transition can be done smoothly
> 	cons:
> 		the user should know which docset works with which formatter
>
> way #2: rewrite all formatters to use the new docsets
> 	pros:
> 		transition is fast, and the user cannot see it
> 	cons:
> 		lotsa code should be reworked, the probability of bugs is high
>
> way #3: make the new docsets recognise the "version" of the formatter,
> 	and call the old formatters in the old way, the new ones in the new wa=
y
>
> 	pros:
> 		smooth transition, the user cannot see it
> 	cons:
> 		the docset code will be unnecessarily complex
>
>
> Which way to go?

There's not much point in modifying any of the existing docsets/formatter=
s=20
since 3.0 is already in the works.  I would go with option #1.  The user =
will=20
only need to worry about which formatters and docsets work together for a=
=20
short time, assuming I can spend some time over the holiday working on 3.=
0. =20
:-)

> I have some additional questions:
>
> -How to submit my code? (It needs to be reworked because the above
> problems, but works now, and release early, release often)

The easiest way initially would be to submit patches via SourceForge.  If=
=20
you're interested, we could also talk about you having CVS access.  Do yo=
u=20
have a SourceForge user account?

> -I am just starting to convert the structuredtext docstrings to latex.
> 	Where is the most efficient to start it?

I would take a look at the existing code that converts to HTML.  That is =
in=20
the happydoclib/docstring/StructuredText package somewhere (don't remembe=
r of=20
the top of my head - look at the docstring converter plugin for clues).

Doug