Ticket #6 (new task)
Documentation system: update tools, change format, etc. ?
| Reported by: | debrouxl | Owned by: | somebody |
|---|---|---|---|
| Priority: | major | Milestone: | Version 1.00 |
| Component: | doc-tools | Version: | 0.96 |
| Keywords: | Cc: |
Description (last modified by debrouxl) (diff)
The current documentation system is an ad-hoc system developed for TIGCC:
- a family of Properties/INI-type formats, in which several sections can contain HTML code instead of simple name/value pairs;
- several tools to parse these files, generate C headers and HTML code (of the old-fashioned kind) + MS HTML Help metadata. Most of these tools are written in Delphi. The Delphi tools work perfectly under Wine, I successfully recompiled UpdateInclude? with Delphi 7.
We're bound to modify the executables system sooner or later, e.g. in order to fix the annoying "stop at first error" behaviour, for ticket #5 or another currently unforseen reason.
We have at least three ways to handle maintenance and evolution of the documentation system:
- stick to the current bits of Delphi code, modify them when necessary. Sustainability in the long run is currently seen as good, but we might want to make extensive changes to the documentation, or we may have to rewrite them for some reason.
- rewriting the current tools in other languages, e.g. scripting languages, C++/Qt4, while keeping the input format. Kevin did that for two of the simplest tools.
- change the documentation format:
- keep the same kind of documentation paradigm, with input formats such as Docbook or DITA. Those two are XML+XSLT-based, which may make it possible to generate C headers from XML documents.
- switch to a Doxygen-type documentation paradigm (generate documentation from the code of C headers, instead of generating C headers from documentation), if flexible enough.
Change History
Note: See
TracTickets for help on using
tickets.
