I will try to push this bug forward:
festival-doc source package builds two packages: festival-doc and speech-tools-doc. Once we have a build system working for both packages, I suggest Jean-Philippe intends to adopt festival-doc source package (or the TTS team adopts it, I don't know :-) ).
Here is the status of building both packages from festival and speech-tools sources:
Regarding festival-doc:
===================
I have managed to successfully build festival-doc from the festival source package using texi2html.
As Ryan Kavanagh pointed to Peter, there is a transition from texi2html to texinfo [1]. Until I have properly replaced texi2html with texinfo I will not commit any patch unless you prefer to have a texi2html temporal solution.
I have to read how to replace texi2html with texinfo, I hope it is not going to be hard, given that many people may have done this transition before :-)
Regarding speech-tools-doc:
=====================
Building speech-tools-doc from src:speech-tools is not trivial.
Current issues:
----------------------
- It depends on Doc++ (an automatic documentation program not updated since 2003 [2] and removed from debian repository [3]).
- It depends on jade which seems to be being replaced by openjade because (according to jade's changelog [4] and jade's website [5]) it has not received any upstream update since 1999.
- The manual is in DocBook V3.0 and quite integrated with Doc++ specific XML output format.
Proposed solution: (I am working on it now)
--------------------------
- Replace Doc++ with Doxygen. Doxygen is quite standard for source documentation nowadays. It can provide output in HTML and PDF formats and initially it was partially based on Doc++ [6], so its syntax is quite similar.
- Replace the sgml manual with markdown pages. Doxygen is markdown friendly and this change would allow us to integrate the manual with the source code documentation and build everything together (with links from the manual to the source documentation, etc...).
* Pros:
- The proposed solution would drop all documentation dependencies (doc++, jade, perl...) and only leave doxygen, which seems to have good support and is a very active project with many users.
- The Makefile will be much simpler.
- Markdown format is extensively used in many projects and very easy to read in raw format.
* Cons:
- Converting sgml pages to markdown may lead to a patch of considerable size. I will try to estimate its size ASAP.
As always, alternative solutions, comments, likes/dislikes are very welcome :-)