Doc packages (Was: Schedule to migrate to SVN repository)

[Andreas Tille <tillea@rki.de>]

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.

Kind regards

          Andreas.