Re: [AD] Makedoc swallowing external files

[Elias Pschernig <elias@xxxxxxxxxx>]

On Mon, 2004-11-08 at 23:09 +0000, Grzegorz Adam Hankiewicz wrote:
> I've made this patch which makes the pdf/ps output include the
> external files, but I've lost interest in it: the output looks ugly
> and there's no chance to make it work for .info output. Anyway,
> if somebody wants to continue hacking this, the patch is attached.

Hm, that was about my experience with it as well. My attempt broke all
output plugins though, which was when I lost interest..

But after that last thread about this here, I looked at the makedoc cvs
module, and it looks like the secret plans for makedoc could look
something like this:

- Keep ._tx (much easier to edit in a text editor than XML), but
  convert ._tx to XML before generating output (._tx could always be
  dropped then).

- Simplify ._tx a lot, especially remove any output format dependencies,
  like !info !man !html and so on, as well as the obscure features (what
  is e.g. !node for?) Everything which can't be translated into the XML
  will go.

- Add the stripped down makedoc (which does ._tx->.xml) to the makedoc
  module (maybe this could even be a simple python script to
  convert ._tx -> .xml, since that may be just as simple as taking apart
  makedoc and adding an XML plugin).

- Add more python output prototypes to the makedoc module (i couldn't
  even get the html one already there working). Most of the
  functionality could probably be extracted from the current makedoc,
  and hopefully this process would be much easier than refactoring the
  current makedoc. The output generators would simply work on the XML
  specification currently in the makedoc cvs module.

- Once everything is ready, remove the current makedoc, and replace by a
  C version of the one in the makedoc module (or maybe keep the python
  version). And, we get a shiny new, modular, simple, documented, easily
  modfiable makedoc 2.0, which produces much superior documentation :)

Hm, or at least, in any case, let's get rid of the current makedoc. If
refactoring it seems easier than the above, maybe we should do that.. or
if there is some ready-to-use external tool.. or wait, no, can just read
the A5 archives for the discussion on other documentation tools..

-- 
Elias Pschernig