docbook message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [docbook] Is it possible to split chapters ?
- From: Kate.Wringe@ianywhere.com
- To: "David Cramer" <dcramer@motive.com>
- Date: Thu, 31 Jan 2008 16:48:05 -0500
Hi David et al.
Thanks for all of the advice!
The reason why I wanted to use a wrapper
like a div or a refentry tag was to try and preserve the amount of drilling
that the
user would have to do in the output
(in this case HTMLhelp and PDF).
Originally the output looked like this:
LargeChapter title
first
sect1 title
second
sect1tile
third
sect1 tile
....
two-hundredth
sect 1 title
The easiest solution, and the one that
I think we're going to go with is to just demote our sect1s to sect2s.
New output would look like this:
LargeChapter title
intro
sect1 title (e.g., statements a to f)
first sect2 title
second sect2 title
...
second
intro sect1 title (eg. statemetns f to m)
fifty-second sect 2 tile
....
It's not a big difference, but we were
hoping to maintain the same look and drilling-level.
Thanks again,
Kate
"David Cramer"
<dcramer@motive.com>
01/30/2008 05:09 PM
|
To
| <Kate.Wringe@ianywhere.com>
|
cc
| <docbook@lists.oasis-open.org>
|
Subject
| RE: [docbook] Is it possible to
split chapters ? |
|
> I
mean validation in the sense of providing authoring assistance as you type.
The problem with validating the parent-doc is that I can't simply click
Go To
in the Validation Log when there is an error.
Yeah, that's another problem with XMetaL.
With the authoring assistance on, you rarely end up with an invalid doc,
but if you accidentially delete an element with an id you'd xrefed to,
the feedback from validation is useless if you've broken your doc into
entities. For that case, I have an "Open current document in emacs"
macro that I use to open the parent doc in emacs (+ psgml mode), validate
it and quickly find and fix the errors.
You should bring up all these issues up with
XMetaL support.
> So far the solution I've come up with
is to change the refentry element
in docbook so that it allows multiple sect1 tags.
This is what I came up with for the declaration of refentry. Is this OK
to do in docbook?
Ok, I think I'm beginning to understand what
you want to do, but now I don't understand why. Technically, if you have
file1.xml that contains:
<sect1>
<title>foo</title>
<para>foo</para>
</sect1>
<sect1>
<title>bar</title>
<para>bar</para>
</sect1>
The file is well formed xml and
can be included into another file as an entity (I've also heard of the
term 'well balanced' to distinguish between files that have a root element
and those that don't). Most tools I've encountered handle pulling in a
file that's not well balanced as an entity just fine. In fact, I just did
an experiment and XMetaL also is ok with it. I created wrapper.xml which
is a book and pulled in foo.xml with the following contents:
<section>
<title>foo</title>
<para>blah</para>
</section>
<section>
<title>foo</title>
<para>blah</para>
</section>
When I open wrapper.xml and double
click on the foo.xml entity icon, it opens foo.xml and I get all the normal
assistance while editing. You could hack it so you can add something that
acts like a <div> around your sect1s and then have the processing
system remove those, but why do you need to?
David
From: Kate.Wringe@ianywhere.com [mailto:Kate.Wringe@ianywhere.com]
Sent: Wednesday, January 30, 2008 2:30 PM
To: David Cramer
Cc: docbook@lists.oasis-open.org
Subject: RE: [docbook] Is it possible to split chapters ?
Hi David,
Thanks for responding!
As you mention, XMetaL can
only validate a wrapper file. To get around that, I added a macro (pasted
below) that looks for a processing instruction in the format <?parent-doc
parentdoc.xml?> in a document if it doesn't have a DOCTYPE statement,
then opens parentdoc.xml if necessary, switches to it, and validates it.
You put this in the On_Before_Document_Validate event macro and it fires
whenever you validate a doc.
I mean validation in the sense of providing authoring assistance as you
type. The problem with validating the parent-doc is that I can't simply
click Go To
in the Validation Log when there is an error.
But that may not be the problem you're talking about (I'm not sure whether
you mean validation in the strick sense or in the sense of providing authoring
assistence as you type). Does largechapter.xml have a DOCTYPE (i.e. the
DTD declaration at the top?) or is that in a book.xml that in turn contains
largechapter.xml? A limitation of XMetaL's handling of entities is that
if you include files more than one level deep, then you can't open the
second level. So if you have this situation: book.xml includes largechapter.xml
includes section.xml, then you can open book.xml, click on an entity to
open largechapter.xml, do any editing you want there with XMetaL letting
you know what's allowed where, but you can't open section.xml from largechapter.xml.
This is really a misfeature/lack of functionality in xmetal. We
created a workaround for XMetaL's entities feature by using a script similar
to the one you suggested below within the On_Application_Before_Document_Opens
event.
A workaround that I can think of would be to make some fake wrapper.xml
that includes both largechapter.xml and section.xml directly. The purpose
of wrapper.xml would only be to keep xmetal happy and let you open section.xml
in a way that will let xmetal associate it with it's dtd.
So far the solution I've come up with is to change
the refentry element in docbook so that it allows multiple sect1 tags.
This is what I came up with for the declaration of refentry. Is this OK
to do in docbook?
<!ELEMENT refentry %ho; (beginpage?,
(%ndxterm.class;)?,
refentryinfo?,
refmeta?, (remark|%link.char.class;)?,
refnamediv?,
refsynopsisdiv?, (sect1+|refsect1+|refsection+))
%ubiq.inclusion;>
Thus we can create a chapter like the following:
bigfilechapter.xml
<chapter>
<title> Title </title>
<para>
&file1; &file2;
</chapter>
file1.xml
<refentry>
<sect1>
sect 1 info
</sect1>
<sect1>
sect 1 info
</sect1>
</refentry>
file2.xml
<refentry>
<sect1>
sect 1 info
</sect1>
<sect1>
sect 1 info
</sect1>
</refentry>
I've got to talk with the woman who looks after our XSLT build processes
to see if
it is possible for her to strip out or ignore the refentry tags during
the build process.
Otherwise, I'll have to insert and remove the refentry tags in xmetal.
Thanks again,
Kate
"David Cramer"
<dcramer@motive.com>
01/30/2008 02:33 PM
|
To
| <Kate.Wringe@ianywhere.com>,
<docbook@lists.oasis-open.org>
|
cc
|
|
Subject
| RE: [docbook] Is it possible to
split chapters ? |
|
As you mention, XMetaL can only validate a wrapper file. To get around
that, I added a macro (pasted below) that looks for a processing instruction
in the format <?parent-doc parentdoc.xml?> in a document if it doesn't
have a DOCTYPE statement, then opens parentdoc.xml if necessary, switches
to it, and validates it. You put this in the On_Before_Document_Validate
event macro and it fires whenever you validate a doc.
But that may not be the problem you're talking about (I'm not sure whether
you mean validation in the strick sense or in the sense of providing authoring
assistence as you type). Does largechapter.xml have a DOCTYPE (i.e. the
DTD declaration at the top?) or is that in a book.xml that in turn contains
largechapter.xml? A limitation of XMetaL's handling of entities is that
if you include files more than one level deep, then you can't open the
second level. So if you have this situation: book.xml includes largechapter.xml
includes section.xml, then you can open book.xml, click on an entity to
open largechapter.xml, do any editing you want there with XMetaL letting
you know what's allowed where, but you can't open section.xml from largechapter.xml.
This is really a misfeature/lack of functionality in xmetal.
A workaround that I can think of would be to make some fake wrapper.xml
that includes both largechapter.xml and section.xml directly. The purpose
of wrapper.xml would only be to keep xmetal happy and let you open section.xml
in a way that will let xmetal associate it with it's dtd.
David
// From On_Before_Document_Validate
if(ActiveDocument.doctype.systemId == ""){
Application.StopValidation();
var parentDoc = ActiveDocument.getNodesByXPath("//processing-instruction('parent-doc')");
// Store the object representing
// the active document
var doc = Application.ActiveDocument;
if(parentDoc.length != 0){
try{
var parentDocObj = Documents.item(ActiveDocument.Path + "\\"
+ parentDoc.item(0).nodeValue);
parentDocObj.validate();
if(parentDocObj.isValid){
doc.Activate();
}else{
parentDocObj.Activate();
}
}catch(e){
if(Application.FileExists(ActiveDocument.Path + "\\"
+ parentDoc.item(0).nodeValue)){
var parentDocObj2 = Documents.Open(ActiveDocument.Path +
"\\" + parentDoc.item(0).nodeValue);
ActiveDocument.validate();
if(ActiveDocument.isValid){
doc.Activate();
}
}
}
}else{
Application.Alert("Can't validate a document without a DOCTYPE
or a <?parent-doc path-to-parent?>","Sorry");
}
}
From: Kate.Wringe@ianywhere.com [mailto:Kate.Wringe@ianywhere.com]
Sent: Wednesday, January 30, 2008 10:58 AM
To: docbook@lists.oasis-open.org
Subject: [docbook] Is it possible to split chapters ?
Hello,
We are using docbook 4.2 with our own customizations and our authoring
tool is XMetaL 5.0.
Currently we have a very large chapter, largechapter.xml, that contains
reference material.
This chapter is divided into sect1s. For various reasons, we'd
like
to split up the contents of largechapter.xml into three files/entities
and insert the
entities into the largechapter.xml.
What we've done is created three files that contain a list of sect1s.
For example file1.xml 's hierarchy looks like the following:
<sect1>
referenceA material
</sect1>
<sect1>
referenceB material
</sect1>
...
We have no problem inserting an entity for file1.xml into largechapter.xml
and validating
largechaper.xml. The problem is that we can't validate file1.xml on its
own, because
it does not contain an over-arching root. As a result, it is difficult
for us to edit
file1.xml. Is there a tag that we could use that would fit within
the chapter tag and would
accept sect1s? Or is there another way to do this?
I know that an easy solution would be to convert all the current sect1s
in file1.xml
to sect2s and use one sect1. We'd prefer not to do this as it would add
an
extra level for our users to drill down through.
Any suggestions welcome!
Thank you,
Kate
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]