232378 - switch from entities to XIncludes for inclusion of modular docs files

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect)

Description

[Myk Melez [:myk] [@mykmelez]]

Entities have some limitations as a mechanism for including chapter files into a
DocBook book.  In particular, the files can't have their own DOCTYPE declaration
and thus cannot be valid XML documents themselves, making it harder to track
down and fix errors in them.  XIncludes solve this problem and have a variety of
other useful features.  For more info, see this page:

http://www.sagehill.net/docbookxsl/ModularDoc.html

Comment 1

[Gervase Markham [:gerv]]

Sounds cool. Does it involve any content restructuring, or just a big
search-and-replace? Do the current versions of the tools we use support it, or
will we need a tool upgrade?

Gerv

Comment 2

[Myk Melez [:myk] [@mykmelez]]

(In reply to comment #1)
> Sounds cool. Does it involve any content restructuring, or just a big
> search-and-replace?

It's almost as simple as a search-and-replace.  It also requires adding DOCTYPE
declarations to the top of every chapter file, and it may require defining the
entities used in those files at the top (or putting the entities in their own
file so there's no duplication).  We might want to add the appropriate namespace
for XIncludes to the top-level XML element in each file and get rid of entities
as chapter file references, but those are optional steps and can also been done
down the road.

> Do the current versions of the tools we use support it, or will we need
> a tool upgrade?

As far as I know our current tools support it, although we may need to upgrade
to docbook 4.2.

Comment 3

[Gervase Markham [:gerv]]

Go to it, then, Myk ;-)

Gerv

Comment 4

[Dave Miller [:justdave]]

Preliminarily moving all docs bugs to 2.18, we should make a valiant attempt to
have the docs as up-to-date as possible when 2.18 releases.

Comment 5

[Colin Ogilvie [:cso]]

Attachment: Add XIncludes instead of entites (requires the forthcoming entites file too)

Changes to using XIncludes... this has been tested and seems to work.

Comment 6

[Colin Ogilvie [:cso]]

Attachment: Entity File

This goes in xml/

Comment 7

[Colin Ogilvie [:cso]]

OH, except not with OpenJade as far as I can tell :(

Comment 8

[Colin Ogilvie [:cso]]

Attachment: Entity File

Now it works for OpenJade.

Comment 9

[Vlad Dascalu]

Comment on attachment 207195 [details] [diff] [review]
Add XIncludes instead of entites (requires the forthcoming entites file too)

In order to add a new file to the diff, uou can diff locally against /dev/null, then append the output to the cvs diff.

+<!-- Not sure why this is here... no content. Excluding for now... -->
+<!--xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="index.xml" /-->

index.xml is the place where PSGML settings for Emacs are saved, in a LISP notation. Emacs has this cool "mode" thing were you can actually turn the editor into something completely new. PSGML is an Emacs mode made specifically for SGML ( http://www.lysator.liu.se/projects/about_psgml.html ), and index.xml is a placeholder for LISP settings regarding configuration of PSGML. I'd leave it included.

+<?xml version="1.0" encoding="iso-8859-1" ?>

Why iso-8859-1? UTF-8 would be more sensible, but the rest of the xml declarations don't have an encoding specified, so probably the new file should leave that one empty as well.

Comment 10

[Colin Ogilvie [:cso]]

Checked in to trunk only:

cvs commit: Examining docs/xml
Checking in docs/xml/Bugzilla-Guide.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/Bugzilla-Guide.xml,v  <--  Bugzilla-Guide.xml
new revision: 1.58; previous revision: 1.57
done
Checking in docs/xml/about.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/about.xml,v  <--  about.xml
new revision: 1.20; previous revision: 1.19
done
Checking in docs/xml/administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/administration.xml,v  <--  administration.xml
new revision: 1.56; previous revision: 1.55
done
RCS file: /cvsroot/mozilla/webtools/bugzilla/docs/xml/bugzilla.ent,v
done
Checking in docs/xml/bugzilla.ent;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/bugzilla.ent,v  <--  bugzilla.ent
initial revision: 1.1
done
Checking in docs/xml/conventions.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/conventions.xml,v  <--  conventions.xml
new revision: 1.10; previous revision: 1.9
done
Checking in docs/xml/customization.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/customization.xml,v  <--  customization.xml
new revision: 1.22; previous revision: 1.21
done
Checking in docs/xml/faq.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/faq.xml,v  <--  faq.xml
new revision: 1.40; previous revision: 1.39
done
Checking in docs/xml/gfdl.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/gfdl.xml,v  <--  gfdl.xml
new revision: 1.10; previous revision: 1.9
done
Checking in docs/xml/glossary.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/glossary.xml,v  <--  glossary.xml
new revision: 1.18; previous revision: 1.17
done
Checking in docs/xml/index.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/index.xml,v  <--  index.xml
new revision: 1.5; previous revision: 1.4
done
Checking in docs/xml/installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/installation.xml,v  <--  installation.xml
new revision: 1.108; previous revision: 1.107
done
Checking in docs/xml/modules.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/modules.xml,v  <--  modules.xml
new revision: 1.5; previous revision: 1.4
done
Checking in docs/xml/patches.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/patches.xml,v  <--  patches.xml
new revision: 1.22; previous revision: 1.21
done
Checking in docs/xml/security.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/security.xml,v  <--  security.xml
new revision: 1.9; previous revision: 1.8
done
Checking in docs/xml/troubleshooting.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/troubleshooting.xml,v  <--  troubleshooting.xml
new revision: 1.7; previous revision: 1.6
done
Checking in docs/xml/using.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/using.xml,v  <--  using.xml
new revision: 1.40; previous revision: 1.39
done

Comment 11

[Colin Ogilvie [:cso]]

This didn't seem to work on landfill, although I'm positive I tested it there :/

Comment 12

[Vlad Dascalu]

Comment on attachment 207199 [details]
Entity File

Cancelling review, in order to stop this from appearing on the "reviewed docs" query.

Comment 13

[Frédéric Buclin]

This bug is retargetted to Bugzilla 3.2 for one of the following reasons:

- it has no assignee (except the default one)
- we don't expect someone to fix it in the next two weeks (i.e. before we freeze the trunk to prepare Bugzilla 3.0 RC1)
- it's not a blocker

If you are working on this bug and you think you will be able to submit a patch in the next two weeks, retarget this bug to 3.0.

If this bug is something you would like to see implemented in 3.0 but you are not a developer or you don't think you will be able to fix this bug yourself in the next two weeks, please *do not* retarget this bug.

If you think this bug should absolutely be fixed before we release 3.0, either ask on IRC or use the "blocking3.0 flag".

Comment 14

[Max Kanat-Alexander]

Bugzilla 3.2 is now frozen. Only enhancements blocking 3.2 or specifically approved for 3.2 may be checked in to the 3.2 branch. If you would like to nominate your enhancement for Bugzilla 3.2, set the "blocking3.2" flag to "?". Then, either the target milestone will be changed back, or the blocking3.2 flag will be granted, if we will accept this enhancement for Bugzilla 3.2.

This particular bug has not been touched in over eight months, and thus is being retargeted to "---" instead of "Bugzilla 4.0". If you believe this is a mistake, feel free to retarget it to Bugzilla 4.0.

Comment 15

[Frédéric Buclin]

Attachment: Add XIncludes instead of entites, v1.1

The previous patch was bitrotten. Here is an unbitrotten one. But I didn't manage to make it work with jade, even with the Entity File applied. It looks like jade happily ignores <xi:include ...>.

Comment 16

[Frédéric Buclin]

Attachment: Add XIncludes instead of entites, v1.2

It looks like entities defined in Bugzilla-Guide.xml do not propagate to other .xml files, so I had to put them in bugzilla.ent. To correctly generate bugzilla.ent, I wrote a bugzilla_compat.ent file to which additional data is appended.

As said in my previous comment, jade ignores <xi:include> entirely, so this is patch is not for review.

When I use xmlto instead, it complains that the URI is missing:

  "parser error : SYSTEM or PUBLIC, the URI is missing"

So this means we would have to revert the change done in bug 445061, unless Colin has an idea to fix this problem.

Comment 17

[Frédéric Buclin]

Attachment: bugzilla_compat.ent, v2

The file to put in the same directory as makedocs.pl. This is the template which will be used to generate bugzilla.ent.

Comment 18

[Frédéric Buclin]

Colin, did you make some progress since 2005? :)

Comment 19

[Frédéric Buclin]

Implemented in bug 423496.