Re: debiandoc vs. docbook
Hi, Susan
These topics have been somewhat emotional flame wars and I want this
thread to be productive one ;-)
In short, as an author of one of the longer debiandoc documents, I am,
to your surprise, for the XML format provided infrastructures (including
nice best practice guide lines) are there for me.
I see many "programmer types" argue strongly about XML and
"documentation authors" are not to excited about "complicated" XML and
very reluctant to the changes. But this stereotype needs to be
considered where it came from. For me, the only way to change document
format is not through argument with hostilities nor by put-downs to the
authors "who does not learn" but by the persuasion with helping hands ;-)
For me, as long as Debian use reasonable subset of XML tags, it ain't too
different.
Please provide following resources, then this conversion will happen
without much fuss.
1. provide debiandoc-to-XML converter (include SGML normalizer).
2. provide XML usage manual with subset of tags (best practice guide).
3. provide nice small subset tag style-sheet.
4. provide wrapper scripts to build many formats easily.
If these are ready, I will not hesitate to move to XML. as far as I
know, I hear loud call for XML but not completed program packages to
support above 3 items. It looks like 1 and 3 are done.
Please point to me to information leading to 2 and 4.
On Fri, Sep 20, 2002 at 08:27:32AM -0400, Susan Kleinmann wrote:
> Hello,
>
> I believe it would be a good idea to revisit the policy stating that
> all debian documentation should be written in debiandoc.
OK ;-)
> The debiandoc DTD was written a couple of years before XML became a
> standard, and therefore addressed inadequacies of that time. It is an
> understatement to say that those inadequacies have now been addressed.
> I therefore propose:
But you need to realize debiandoc is an useful tool and technical
"inadequacies" of it nor strong handed policy changes are not good
enough reason for authors to change its format.
> 1. We should adopt an XML based language because of the abundance of
> tools that exist to manipulate such languages.
I can agree provided "should" is used in loose context.
> 2. We should consider docbook-xml because it is widely used, well
> documented, well supported by tools, and provides much greater
> expressive power than is currently achievable with debiandoc. There
> even exists a docbook-simple now, for those who are initially
> overwhelmed by the richness of the docbook tag set.
docbook-simple sounds interesting. I just installed it. Is there good
tutorial like the one in debiandoc-sgml-doc? Susan's README.Debian.gz
in docbook-simple is not good enough for me ;-(
Please point me to right document.
> 3. We should (soon) transform the debiandoc files that we now have to
> docbook-xml using, e.g., the script written by Ardo van Rangelrooij:
> http://lists.debian.org/debian-doc/2002/debian-doc-200205/msg00183.html
> In any case, we should agree on a script or process to do the
> transformation, because without that, in order to ensure some
> uniformity in the transformation of all the documents to a new DTD.
I overlooked this one. Anyone tested on my document?
> 4. If the original/current authors don't want to do the translation,
> we should consider setting up some kind of volunteer method to do
> that, something like a bug-squashing-party.
If infrastructure is there, all active document author will be
cooperative. You can count on me.
> 5. Those who prefer to write in debiandoc can of course go ahead and
> do so, but should transform their documents to docbook-xml (or
> whatever DTD or schema is adopted) before uploading them to the CVS
> repository.
Nice thing about current debiandoc is "I can be sloppy". many short
forms and missing closing tags are allowed for non-emacs users :-)
> Please note the word "propose", and report your pros and cons on the
> above ideas. I'll try to summarize all the arguments, pro and con,
> after a week of discussion, with the hope that this will lead to some
> kind of consensus.
We need transition policy proposal.
Also this policy change should be done together with file arrangement
issues discussed recently.
> Best regards, Susan
Regards,
osamu
--
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
Osamu Aoki @ Cupertino CA USA, GPG-key: A8061F32
.''`. Debian Reference: post-installation user's guide for non-developers
: :' : http://www.debian.org/doc/manuals/reference/ also http://qref.sf.net
`. `' "Our Priorities are Our Users and Free Software" --- Social Contract
Reply to: