[HappyDoc-discuss] Latex formatter and design questions

[<ma...@bu...>]

Hi!

I am writing a Latex formatter for happydoc. It is now functional,
utilizes the hyperref latex package, so able to create nice crossreferenced
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=20
python-happydoc 2.0-2) was unuseable. And anyway, I guess the problem lays
deeper: I think that the interface between the docset code and the
formatter code is not the best.
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 responsi=
ble
for the actual format of the parts of the document. For this, 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 figure out where the refere=
nce
to a module gets "Module: " prepended to it, and some hard hours to come up
with a consistent method for cross-referencing.)

I have created a MultipleFileX and a SingleFileX docset which calls the
above-mentioned methods of the formatter, and of course the Latex formatter
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 old fo=
rmatters.
	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 way

	pros:
		smooth transition, the user cannot see it
	cons:
		the docset code will be unnecessarily complex


Which way to go?

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)

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

--=20
GNU GPL: csak tiszta forr=E1sb=F3l