[Devel] DocMaker 2

[David Turner]

Hi again,

  just a quick note regarding the "DocMaker" tool used to
  generate the API reference:

  I. New Architecture:

    the tool was recently completely rewritten. It has been moved
    to the "src/tools/docmaker/" directory.

    It's still in Python but is now more modular. There is an
    abstract "formatter" class that can be derived to implement
    format-specific output. For example, HTML output is now
    fully contained in the "tohtml.py" source. Everything is
    done through a rather simple SAX-like interface.

    This means that outputting to XML, text or anything else
    shouldn't be too difficult. I now wonder: should we write
    format-specific backends for all intended output formats,
    or generate DocBook or TeX files that could later be
    translated into something different with standard tools
    (i.e. I don't want to generate PDF files in DocMaker :-)

    What's your experience with documentation formats, and
    which one would you recommend. I'd like to be able to
    generate at least the following in the end:

        - HTML (cross-referenced)
        - raw text
        - man pages
        - PDF
        - info files (maybe ??)

    I don't want PS or DVI, they're legacy and should die as
    soon as possible.


    Note that another feature of the multiple-backends approach
    is the ability to generate "tags" file to implement external
    cross-references in the documentation.

    Another application would be automatic-reformatting of the
    documentation comments, but I'm not too hasteful to implement
    ot. Hell, we could even automatically generate JavaDoc comments !!


  II. Generating the API Reference:

    in case you're wondering, you can re-generate the API reference
    anytime you want with the following command:

        python src/tools/docmaker/docmaker.py --title=FreeType-2.1.3   \
        --prefix=ft2 --output=<output-directory> include/freetype/*.h  \
        include\freetype\config\*.h include\freetype\cache\*.h

    yes, it's still a bit gross, but I don't want to introduce configuration
    files for now :-)


Best Regards,

- David Turner
- The FreeType Project  (www.freetype.org)