After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 487727 - DocBook XML DTD version
DocBook XML DTD version
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
1.9
Other Linux
: Normal enhancement
: 1.11
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2007-10-18 01:14 UTC by Karsten Bräckelmann
Modified: 2008-06-24 13:18 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
try various version of the stylesheets (1.11 KB, patch)
2007-10-22 13:29 UTC, Stefan Sauer (gstreamer, gtkdoc dev)
rejected Details | Review

Description Karsten Bräckelmann 2007-10-18 01:14:30 UTC
Maybe I'm totally off-base, and just don't see it, but...

gtk-doc depends hard on DocBook XML DTD V4.1.2, whereas gnome-user-docs uses version 4.3. Can this be somehow unified, so one doesn't need to keep both around?


In case I just missed something, please feel free to tell me. :)
Comment 1 Stefan Sauer (gstreamer, gtkdoc dev) 2007-10-22 13:28:05 UTC
I have lots of those installed:

grep "DTD DocBook XML" /etc/xml/docbook-xml.xml
<delegatePublic publicIdStartString="-//Norman Walsh//DTD DocBook XML V4.0//EN" catalog="file:///usr/share/xml/docbook/schema/dtd/4.0/catalog.xml"/>
<delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML V4.1//EN" catalog="file:///usr/share/xml/docbook/schema/dtd/4.1.2/catalog.xml"/>
<delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML V4.2//EN" catalog="file:///usr/share/xml/docbook/schema/dtd/4.2/catalog.xml"/>
<delegatePublic publicIdStartString="-//Norman Walsh//DTD DocBook XML V3" catalog="file:///usr/share/xml/docbook/schema/dtd/3.1.7/catalog.xml"/>
<delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML V4.1.2//EN" catalog="file:///usr/share/xml/docbook/schema/dtd/4.1.2/catalog.xml"/>
<delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML V4.4//EN" catalog="file:///usr/share/xml/docbook/schema/dtd/4.4/catalog.xml"/>
<delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML V4.3//EN" catalog="file:///usr/share/xml/docbook/schema/dtd/4.3/catalog.xml"/>

in the configure we probe against 4.1.2 and then the online one. Could you try the attached patch?

Comment 2 Stefan Sauer (gstreamer, gtkdoc dev) 2007-10-22 13:29:17 UTC
Created attachment 97627 [details] [review]
try various version of the stylesheets

works down from newest known version ...
Comment 3 Stefan Sauer (gstreamer, gtkdoc dev) 2007-10-29 19:36:19 UTC
Bah, the patch is non-sense. We're talking about the dtd version here and not abut the xsl-stylesheets. Of the later we prefer more recent versions.

Regarding the dtd, there question is what benefits newser dtd bring? Bumping the dtd version could causes gtk-doc documents to become invalid (no idea if they remove tags).

If you can find some usefull pointers regarding the changes, please let me know.
Comment 4 Karsten Bräckelmann 2007-10-31 10:07:09 UTC
(In reply to comment #3)
> Regarding the dtd, there question is what benefits newser dtd bring?

The benefit of a common used version that I see is, that you don't need all different (used) versions installed, or tweak your catalog to hold *all* 4.x.y versions and make them point to a single install... I actually don't see any benefit in using a newer DTD, but a common one.


> Bumping the dtd version could causes gtk-doc documents to become invalid
> (no idea if they remove tags).
> 
> If you can find some usefull pointers regarding the changes, please let me
> know.

My google foo suggests that there are no incompatability issues. This quote [1] is of particular interest:

  The OASIS DocBook Technical Committee (TC) observes a very cautious policy
  regarding changes to the DTD. Backward-incompatible changes can only be
  introduced:
    * In major releases (4.0, 5.0, 6.0, and so on)

  Changes made at point-releases are always backward-compatible to the
  previous major release.


Other sources seem to state, that 4.x generally is in maintenance mode, with no backwards incompatible changes [2]. Also see the FAQ [3].


[1] http://www.faqs.org/docs/docbook/html/appc.html
[2] http://www.docbook.org/specs/docbook-4.5-spec.html
[3] http://www.dpawson.co.uk/docbook/reference.html#d17e1205
Comment 5 Stefan Sauer (gstreamer, gtkdoc dev) 2008-06-23 07:24:01 UTC
I found some concrete benefits, less validation errors. For gtk-doc 1.11 we'll switch to 4.3.
Comment 6 Stefan Sauer (gstreamer, gtkdoc dev) 2008-06-24 13:18:42 UTC
2008-06-24  Stefan Kost  <ensonic@users.sf.net>

	* configure.in:
	* gtkdoc-mkdb.in:
	* tests/bugs/docs/tester-docs.xml:
	* tests/gobject/docs-tmpl/tester-docs.xml:
	* tests/gobject/docs/tester-docs.xml:
	  Switch to docbook 4.3 dtd. Fixes #487727.