Closed
Bug 232378
Opened 21 years ago
Closed 13 years ago
switch from entities to XIncludes for inclusion of modular docs files
Categories
(Bugzilla :: Documentation, defect)
Bugzilla
Documentation
Tracking
()
RESOLVED
FIXED
Bugzilla 4.4
People
(Reporter: myk, Assigned: LpSolit)
References
()
Details
(Whiteboard: [Fixed by blocker])
Attachments
(2 files, 4 obsolete files)
12.44 KB,
patch
|
Details | Diff | Splinter Review | |
1.09 KB,
text/plain
|
Details |
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•21 years ago
|
||
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
Reporter | ||
Comment 2•21 years ago
|
||
(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•21 years ago
|
||
Go to it, then, Myk ;-)
Gerv
Comment 4•21 years ago
|
||
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.
Target Milestone: --- → Bugzilla 2.18
Comment 5•19 years ago
|
||
Changes to using XIncludes... this has been tested and seems to work.
Updated•19 years ago
|
QA Contact: mattyt-bugzilla → documentation
Comment 6•19 years ago
|
||
This goes in xml/
Comment 7•19 years ago
|
||
OH, except not with OpenJade as far as I can tell :(
Comment 8•19 years ago
|
||
Now it works for OpenJade.
Attachment #207196 -
Attachment is obsolete: true
Comment 9•19 years ago
|
||
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.
Attachment #207195 -
Flags: review? → review+
Updated•19 years ago
|
Attachment #207199 -
Flags: review+
Comment 10•19 years ago
|
||
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
Status: ASSIGNED → RESOLVED
Closed: 19 years ago
Resolution: --- → FIXED
Target Milestone: Bugzilla 2.18 → Bugzilla 2.24
Comment 11•19 years ago
|
||
This didn't seem to work on landfill, although I'm positive I tested it there :/
Status: RESOLVED → REOPENED
Resolution: FIXED → ---
Updated•19 years ago
|
Status: REOPENED → ASSIGNED
Comment 12•19 years ago
|
||
Comment on attachment 207199 [details]
Entity File
Cancelling review, in order to stop this from appearing on the "reviewed docs" query.
Attachment #207199 -
Flags: review+
Updated•19 years ago
|
Attachment #207195 -
Flags: review+
![]() |
Assignee | |
Comment 13•18 years ago
|
||
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".
Target Milestone: Bugzilla 3.0 → Bugzilla 3.2
Comment 14•17 years ago
|
||
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.
Target Milestone: Bugzilla 3.2 → ---
Updated•17 years ago
|
Attachment #207196 -
Attachment mime type: application/octet-stream → text/plain
![]() |
Assignee | |
Updated•15 years ago
|
QA Contact: documentation → default-qa
![]() |
Assignee | |
Comment 15•13 years ago
|
||
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 ...>.
Attachment #207195 -
Attachment is obsolete: true
![]() |
Assignee | |
Comment 16•13 years ago
|
||
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.
Attachment #560886 -
Attachment is obsolete: true
![]() |
Assignee | |
Comment 17•13 years ago
|
||
The file to put in the same directory as makedocs.pl. This is the template which will be used to generate bugzilla.ent.
Attachment #207199 -
Attachment is obsolete: true
![]() |
Assignee | |
Comment 18•13 years ago
|
||
Colin, did you make some progress since 2005? :)
![]() |
Assignee | |
Updated•13 years ago
|
![]() |
Assignee | |
Comment 19•13 years ago
|
||
Implemented in bug 423496.
Assignee: colin.ogilvie → LpSolit
Status: ASSIGNED → RESOLVED
Closed: 19 years ago → 13 years ago
Resolution: --- → FIXED
Whiteboard: [Fixed by blocker]
Target Milestone: --- → Bugzilla 5.0
You need to log in
before you can comment on or make changes to this bug.
Description
•