Doc packages (Was: Schedule to migrate to SVN repository)
On Wed, 30 Jun 2004, Otavio Salvador wrote:
> To me, the <cdd>-doc need be build together with the core package
> since it document a "picture" of the package and because of this
> should be release with it.
> Looks not so dificult merge it in each package and I think is the
> better thing to do. Possible, each maintainer can realize it in your
> package and you, me and someothers do it in core package. What you think?
Well, you are right here in principle but this would require that we
relay on a certain text processing kit. While I used debiandoc-sgml for
cdd-doc I have used linuxdoc sgml for med-doc and Mako mentioned XML.
While I'm more or less convinced to use some kind of XML (I have seen
a really good looking document at LinuxTag) I think we can not force
anybody to a certain toolkit. I personally have no strict preferences
and my choices came out of historical reasons which are:
med-doc in linuxdoc sgml:
Just found a good example which seemed fit for all purposes.
I just found some drawbacks I do not remember any more.
med-doc in a special XML format for LinuxTag paper
Well I have a current conversion in XML of this document
which was prepared with a special DTD for LinuxTag but did
not builded with only Debian tools (might be fixed now - I
did not checked).
cdd-doc in debiandoc-sgml:
Subproject-howto was written using this and it seemed appropriate
for the first moment. If I would have checked the BTS for bugs in
debiandoc-sgml I would perhaps used a differnt tool (I even found
more bugs) and it has some constraints I do not like.
Even if I'm willing to convert to one common tool (whichever it is -
conversion to a different toolkit often shows bugs in content and
thus it is a good idea to be forced working on the whole text) I doubt
that we are able to settle down to one toolkit. It would be nice
if you would prove me wrong here. So I doubt that we can build the
doc package in a common way even if this would be a nice thing.