Xi:includes and Entity Parameters

[Dermot O'H]

Hi all,

I've got a DocBook guide comprised of chapters maintained in individual files that are imported using xi:includes:

<book>
    <title>My Book</title>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chapter-1.xml"/>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chapter-2.xml"/>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chapter-3.xml"/>
 </book>

As you can see, all included files are in the guide's own root directory. I've also defined shared text entities within a file called entities.ent located in the guide's root directory aswell:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myents SYSTEM "entities.ent" >
%myents;
]>

<book>
    <title>My Book</title>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chapter-1.xml"/>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chapter-2.xml"/>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chapter-3.xml"/>
 </book>

Each xi:include file must contain the above parameter entity declaration and reference in its DOCTYPE - this is fine by me as it's only in a few cases and is very manageable.

Now, I also wish to xi:include a common chapter located within a global directory. I do this as follows:

...
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../global/common-chapter.xml"/>
...

The problem is that if I try to reference one of the entities (e.g. &productname; ) within the common-chapter.xml file it will not resolve due to the way xi:inlcude works: the common-chapter.xml file will expect the entities.ent file to be located within its root directory.(i.e. "../../global/entities.ent") and not in the guide's root directory (where the entities.xml file does reside).

Is there a way around this problem? I am restricted to using relative paths due to our build system and the different OS environments it works in. It's not possible for me to reference an entities file via an absolute path such as http://myserver/entities.ent. Again, this is due to our build system and the way we use version control.

Is there some way to stop the included common-chapter.xml from resolving the entities.ent file relative to its location and use the location of the root guide instead? Or perhaps an alternative method of importing a global file that resolves entities based on the guide doing the importing?

Thanks!

D.

[David Cramer (Tech Pubs)]

Sounds like a job for catalog files:
http://www.sagehill.net/docbookxsl/Catalogs.html

With a catalog file, you map any public or system identifier to a local
copy. The location of the resource can be relative to the catalog file.

David

> -----Original Message-----
> From: Dermot O'H [mailto:dermot.ohalloran@...]
> Sent: Monday, June 29, 2009 11:39 AM
> To: docbook@...
> Subject: [docbook] Xi:includes and Entity Parameters
>
>
> Hi all,
>
> I've got a DocBook guide comprised of chapters maintained in
> individual files that are imported using xi:includes:
>
> <book>
>     <title>My Book</title>
>     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
> href="chapter-1.xml"/>
>     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
> href="chapter-2.xml"/>
>     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
> href="chapter-3.xml"/>
>  </book>
>
> As you can see, all included files are in the guide's own
> root directory.
> I've also defined shared text entities within a file called
> entities.ent located in the guide's root directory aswell:
>
> <?xml version="1.0" encoding="UTF-8"?>
> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
> "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
> <!ENTITY % myents SYSTEM "entities.ent" > %myents; ]>
>
> <book>
>     <title>My Book</title>
>     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
> href="chapter-1.xml"/>
>     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
> href="chapter-2.xml"/>
>     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
> href="chapter-3.xml"/>
>  </book>
>
> Each xi:include file must contain the above parameter entity
> declaration and reference in its DOCTYPE - this is fine by me
> as it's only in a few cases and is very manageable.
>
> Now, I also wish to xi:include a common chapter located
> within a global directory. I do this as follows:
>
> ...
>     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
> href="../../global/common-chapter.xml"/>
> ...
>
> The problem is that if I try to reference one of the entities (e.g.
> &productname; ) within the common-chapter.xml file it will
> not resolve due to the way xi:inlcude works: the
> common-chapter.xml file will expect the entities.ent file to
> be located within its root directory.(i.e.
> "../../global/entities.ent") and not in the guide's root
> directory (where the entities.xml file does reside).
>
> Is there a way around this problem? I am restricted to using
> relative paths due to our build system and the different OS
> environments it works in. It's not possible for me to
> reference an entities file via an absolute path such as
> http://myserver/entities.ent. Again, this is due to our build
> system and the way we use version control.
>
> Is there some way to stop the included common-chapter.xml
> from resolving the entities.ent file relative to its location
> and use the location of the root guide instead? Or perhaps an
> alternative method of importing a global file that resolves
> entities based on the guide doing the importing?
>
> Thanks!
>
> D.
> --
> View this message in context:
> http://www.nabble.com/Xi%3Aincludes-and-Entity-Parameters-tp24

102062p24102062.html
> Sent from the docbook General mailing list archive at Nabble.com.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@...
> For additional commands, e-mail: docbook-help@...
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Mike Maxwell-2]

In the description of footnotes in the DocBook 5 documentation
   http://www.docbook.org/tdg5/en/html/footnote.html
under the section "Additional Constraints" it lists the following
constraint:
   indexterm must not occur in the descendants of footnote
I'm confused about how indexterms are supposed to be used in footnotes.
Typically (I think) you have a para inside the footnote (at least that's
how the example works on that same page).  The implication of the above
constraint would then be that any indexterm in a footnote has to be outside
the text of the footnote, I guess like this:

   <para>An annual percentage rate<footnote>
   <indexterm>...prime rate...</indexterm>
   <para>The prime rate, as published in the <citetitle>Wall Street
   Journal</citetitle> on the first business day of the month,
   plus 7.0%.
   </para>
   </footnote>
   ...

Is that the intention?  One perhaps undesirable result of this would be
that if the footnote extends over two pages, the indexterm might point to
the wrong page.  Or is the expectation that in the output document, the
index would say something like "prime rate: 23 footnote 7"?

(Of course, one might say that footnotes should never extend over more than
one page.  That's a rule we academics tend to break...)

   Mike Maxwell

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Mike Maxwell-2]

I've seen no response to my query (below), which makes me think it's either
too newbee or too hard.

Can anyone give me an example of an indexterm in a footnote?  Just an
example is all I need...  Or else tell me that the tentative example I gave
below is the way it's supposed to be.

   Mike Maxwell

On Tue, 07 Jul 2009 15:00:37 -0400, maxwell <maxwell@...> wrote:
> In the description of footnotes in the DocBook 5 documentation
>    http://www.docbook.org/tdg5/en/html/footnote.html
> under the section "Additional Constraints" it lists the following
> constraint:
>    indexterm must not occur in the descendants of footnote
> I'm confused about how indexterms are supposed to be used in footnotes.
> Typically (I think) you have a para inside the footnote (at least that's
> how the example works on that same page).  The implication of the above
> constraint would then be that any indexterm in a footnote has to be
outside

> the text of the footnote, I guess like this:
>
>    <para>An annual percentage rate<footnote>
>    <indexterm>...prime rate...</indexterm>
>    <para>The prime rate, as published in the <citetitle>Wall Street
>    Journal</citetitle> on the first business day of the month,
>    plus 7.0%.
>    </para>
>    </footnote>
>    ...
>
> Is that the intention?  One perhaps undesirable result of this would be
> that if the footnote extends over two pages, the indexterm might point to
> the wrong page.  Or is the expectation that in the output document, the
> index would say something like "prime rate: 23 footnote 7"?
>
> (Of course, one might say that footnotes should never extend over more

than
> one page.  That's a rule we academics tend to break...)
>
>    Mike Maxwell
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@...
> For additional commands, e-mail: docbook-help@...

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Bob Stayton]

I believe the statement in the documentation is saying that footnotes should
not contain indexterms at all.  I cannot tell you why, though.

Bob Stayton
Sagehill Enterprises
bobs@...


----- Original Message -----
From: "maxwell" <maxwell@...>
To: <docbook@...>
Sent: Monday, July 13, 2009 9:26 AM
Subject: Re: [docbook] indexterm in footnote


I've seen no response to my query (below), which makes me think it's either
too newbee or too hard.

Can anyone give me an example of an indexterm in a footnote?  Just an
example is all I need...  Or else tell me that the tentative example I gave
below is the way it's supposed to be.

   Mike Maxwell

On Tue, 07 Jul 2009 15:00:37 -0400, maxwell <maxwell@...> wrote:
> In the description of footnotes in the DocBook 5 documentation
>    http://www.docbook.org/tdg5/en/html/footnote.html
> under the section "Additional Constraints" it lists the following
> constraint:
>    indexterm must not occur in the descendants of footnote
> I'm confused about how indexterms are supposed to be used in footnotes.
> Typically (I think) you have a para inside the footnote (at least that's
> how the example works on that same page).  The implication of the above
> constraint would then be that any indexterm in a footnote has to be
outside

> the text of the footnote, I guess like this:
>
>    <para>An annual percentage rate<footnote>
>    <indexterm>...prime rate...</indexterm>
>    <para>The prime rate, as published in the <citetitle>Wall Street
>    Journal</citetitle> on the first business day of the month,
>    plus 7.0%.
>    </para>
>    </footnote>
>    ...
>
> Is that the intention?  One perhaps undesirable result of this would be
> that if the footnote extends over two pages, the indexterm might point to
> the wrong page.  Or is the expectation that in the output document, the
> index would say something like "prime rate: 23 footnote 7"?
>
> (Of course, one might say that footnotes should never extend over more

than
> one page.  That's a rule we academics tend to break...)
>
>    Mike Maxwell
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@...
> For additional commands, e-mail: docbook-help@...

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...




---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Mike Maxwell-2]

On Mon, 13 Jul 2009 14:37:04 -0700, "Bob Stayton" <bobs@...>
wrote:
> I believe the statement in the documentation is saying that footnotes
> should not contain indexterms at all.  I cannot tell you why, though.

I guess that's a possible interpretation.  But the documentation for
'footnote' says that 'indexterm' is a possible child of footnote, and the
documentation for 'indexterm' says that 'footnote' is a possible parent of
'indexterm'.  So my interpretation was that an indexterm could not appear
inside a para which in turn appeared inside a footnote.  But like you, I'm
not sure why.

Another constraint is that 'footnote must not occur in the descendants of
footnote'.  That makes perfect sense; you wouldn't want a footnote inside a
para inside a footnote, any more than you would want a 'footnote' as an
immediate parent or child of 'footnote'.  But I'm not sure why you wouldn't
want an indexterm there.

I just now noticed that 'equation' is in the same boat as 'indexterm':
'equation' is listed as a possible child of 'footnote', and vice versa.
But the documentation for 'footnote' says "equation must not occur in the
descendants of footnote."  But 'equation' can occur inside a 'para'.  Maybe
it's forbidden in the descendants of footnotes because 'equation's are
expected to be "Formatted as a displayed block", rather than as inlines?
(Whereas 'mathphrase' is intended for inline formatting, and is not
forbidden among the descendants of footnote.)

   Mike Maxwell

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Jirka Kosek]

maxwell wrote:

> On Mon, 13 Jul 2009 14:37:04 -0700, "Bob Stayton" <bobs@...>
> wrote:
>> I believe the statement in the documentation is saying that footnotes
>> should not contain indexterms at all.  I cannot tell you why, though.
>
> I guess that's a possible interpretation.  But the documentation for
> 'footnote' says that 'indexterm' is a possible child of footnote, and the
> documentation for 'indexterm' says that 'footnote' is a possible parent of
> 'indexterm'.  So my interpretation was that an indexterm could not appear
> inside a para which in turn appeared inside a footnote.  But like you, I'm
> not sure why.
>
> Another constraint is that 'footnote must not occur in the descendants of
> footnote'.  That makes perfect sense; you wouldn't want a footnote inside a
> para inside a footnote, any more than you would want a 'footnote' as an
> immediate parent or child of 'footnote'.  But I'm not sure why you wouldn't
> want an indexterm there.

The inconsistency comes from fact that parent/child relationships in TDG
are based only on RELAX NG grammar. However rule that indexterm can't be
descendant of footnote is expressed by additional Schematron rule. So it
is best to validate your document against RELAX NG + Schematron at the
same time.

But more to the core problem. I think that there is no reason for
disallowing indexterms in footnote. Might be it is just unintended error
or some legacy stuff. It seems that DocBook XSL stylesheets are able to
process indexterms in footnote correctly. Please file new RFE so DocBook
Technical Committee can discuss this issue and possibly allow indexterms
in footnote in next version of DocBook schema.

Go to

http://sourceforge.net/tracker/?group_id=21935&atid=384107

and the choose "Add new" (you have to be logged into SF).

Thanks,

                        Jirka
--
------------------------------------------------------------------
  Jirka Kosek      e-mail: jirka@...      http://xmlguru.cz
------------------------------------------------------------------
       Professional XML consulting and training services
  DocBook customization, custom XSLT/XSL-FO document processing
------------------------------------------------------------------
 OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
------------------------------------------------------------------

[Dave Pawson]

On 07/14/2009 11:36 AM, Jirka Kosek wrote:
>
> But more to the core problem. I think that there is no reason for
> disallowing indexterms in footnote. Might be it is just unintended error
> or some legacy stuff. It seems that DocBook XSL stylesheets are able to
> process indexterms in footnote correctly.
>    

Speaking against indexterm in footnote on a practical level.
Given page xxx reference to such a term it seems 'odd' or
awkward to go searching for the reference and find it in the footnote?
Index terms are generally to body content, rather than to marginalia
such as footnotes?

Just a practical (visual) issue.


regards

DaveP


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Mike Maxwell-2]

Dave Pawson wrote:

> On 07/14/2009 11:36 AM, Jirka Kosek wrote:
>> But more to the core problem. I think that there is no reason for
>> disallowing indexterms in footnote. Might be it is just unintended error
>> or some legacy stuff. It seems that DocBook XSL stylesheets are able to
>> process indexterms in footnote correctly.
>
> Speaking against indexterm in footnote on a practical level.
> Given page xxx reference to such a term it seems 'odd' or
> awkward to go searching for the reference and find it in the footnote?
> Index terms are generally to body content, rather than to marginalia
> such as footnotes?
>
> Just a practical (visual) issue.

I guess I would say that whether something in a footnote is marginalia
or not is in the eye of the beholder.  It's not uncommon in scholarly
work to index footnotes, and it's quite common to index endnotes.
(DocBook doesn't distinguish the two.)

If necessary, one can modify the index page number to indicate that the
reference is in a footnote, there's an example here:
   http://www.fao.org/forestry/media/16346/1/0/
It's also done in "The Sound Pattern of English", perhaps the most
famous phonology book ever.  (OK, it's famous among us linguists...)
You can see some examples in Amazon's "Look Inside":
http://www.amazon.com/Sound-Pattern-English-Noam-Chomsky/dp/026253097X#reader
E.g. in the "Word Index" on pg. 449, 'ability' appears in a footnote, as
indicated by the 'n' in the page reference '160n'.  Also the second
entry in the "Subject Index" on pg. 464 for "Admissibility, phonological."

Now whether any means of producing a PDF etc. from a DocBook supports
marking index items that are from a footnote with an 'f' or 'n', I don't
know.  I wouldn't be surprised, though, that there's a way to do this
with LaTeX (we convert our DocBook books to LaTeX using the dblatex
program).

I also don't know whether it's possible to produce multiple indices, as
in the Sound Pattern of English example; maybe I could use a 'role' attr
on indexterm...
--
    Mike Maxwell
    What good is a universe without somebody around to look at it?
    --Robert Dicke, Princeton physicist

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Cavicchio_Rob]

Dave Pawson [mailto:davep@...] wrote:

> Speaking against indexterm in footnote on a practical level.
> Given page xxx reference to such a term it seems 'odd' or
> awkward to go searching for the reference and find it in the footnote?
> Index terms are generally to body content, rather than to marginalia
> such as footnotes?


Maybe, but I think that sort of decision should be up to the author of
each document. There's no fundamental reason why an index term in a
footnote must always be illogical, so the semantics should allow it.


*************************
Rob Cavicchio
Principal Technical Writer
EMC Captiva
EMC Corporation
10145 Pacific Heights Boulevard, 6th Floor
San Diego, CA 92121-4234

P: [phone]
F: [phone]
E: Cavicchio_Rob@...

The opinions expressed here are my personal opinions. Content published
here is not read or approved in advance by EMC and does not necessarily
reflect the views and opinions of EMC.
 

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Dave Pawson]

On 07/14/2009 11:36 AM, Jirka Kosek wrote:
>
> The inconsistency comes from fact that parent/child relationships in TDG
> are based only on RELAX NG grammar. However rule that indexterm can't be
> descendant of footnote is expressed by additional Schematron rule. So it
> is best to validate your document against RELAX NG + Schematron at the
> same time.
>    

Where is it documented 'how' to do this please Jirka?
I'll add it to the FAQ.

As part of a validator run or separately?


regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Jirka Kosek]

Dave Pawson wrote:

> On 07/14/2009 11:36 AM, Jirka Kosek wrote:
>>
>> The inconsistency comes from fact that parent/child relationships in TDG
>> are based only on RELAX NG grammar. However rule that indexterm can't be
>> descendant of footnote is expressed by additional Schematron rule. So it
>> is best to validate your document against RELAX NG + Schematron at the
>> same time.
>>    
>
> Where is it documented 'how' to do this please Jirka?
> I'll add it to the FAQ.

Differences between schemas are shown there
http://docbook.org/docs/howto/#t.schema-comparison

> As part of a validator run or separately?

NVDL schema for DocBook binds together RELAX NG and Schematron validation:

http://docbook.org/docs/howto/#validators

--
------------------------------------------------------------------
  Jirka Kosek      e-mail: jirka@...      http://xmlguru.cz
------------------------------------------------------------------
       Professional XML consulting and training services
  DocBook customization, custom XSLT/XSL-FO document processing
------------------------------------------------------------------
 OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
------------------------------------------------------------------