RE: [docbook-apps] Use of xincludes vs. entities

["Cramer, David W (David)" <dcramer@motive.com>]

Hi Sam and Jim,
You might be interested in Jirka's proposal for transclusions in DocBook. It notes the problems with xincludes for the very use case you bring up:

http://lists.oasis-open.org/archives/docbook-tc/201007/msg00041.html

David

-----Original Message-----
From: Sam Fischmann [mailto:sam.fischmann@gmail.com] 
Sent: Saturday, September 25, 2010 3:10 PM
To: Jim Campbell; docbook-apps@lists.oasis-open.org
Subject: Re: [docbook-apps] Use of xincludes vs. entities

Hi Jim,

I say pick the right tool for the job. I think that the two cases you
outline above are completely reasonable uses for entities. I'm also a
bit sheepish about using XInclude with XPointer because of the
differing levels of support for XPointer in different XSL processors.
I don't think it's Bad with a captial "B" to use entities in places
where they are a simple, elegant solution.

Another way to look at it... While editing, a lot of the XInclude junk
doesn't seem helpful for a small bit of text replacement:
<para>The ball is &product_color;.</para>
<para>The ball is <xi:include href="product_info.xml" xpointer="color"/>.</para>

I think product_info.xml is just going to be a weird file to maintain,
too, but that could be personal preference.

However, if it were a file, xi:include provides valuable information:
<para>See the following table: &uh_what_file;</para>
<para>See the following table: <xi:include
href="../tables/product_table.xml"></para>


[ I am going to rant slightly off-topic now, but you might find some
of this interesting and related to your question ]

I am in a situation right now where I have a very large base of
existing DocBook material that uses entities extensively. I would like
to use XPointer for including chunks of text, but I run into all sorts
of problems when those chunks of text themselves contain entities.

Consider two books: Book1 and Book2. Book1 defines &foo; as "1" and
Book2 defines &foo; as "2". I have a file "inc.xml" that's included in
each book via entities. It has the content: "<para>My number is
&foo;</para>". It works great. When I view either book in an editor,
the entity resolves nicely to 1 in Book1 and 2 in Book2.
Unfortunately, most editors don't allow me to edit the contents of
"inc.xml", or as soon as they do, &foo; doesn't resolve because it's
not aware of the parent book that defines it because it's in another
file.

Now I change to XInclude. If I simply add a DOCTYPE tag to "inc.xml"
and include it, &foo; won't resolve at all, because it needs to be
declared inside "inc.xml". But this file is included by two books
which would each define the entity differently. What do I do?

To solve the general case, somebody might tell me that I could define
&foo; in two different entity files, then create two XML catalogs, one
for use with each book, that define the same public identifier for
each respective entity file.  I would then use the public identifier
to declare the entity file in the subset of "inc.xml" and
conditionally specify one or the other catalog when building each
book. That's an awful lot of infrastructure, not to mention that I'm
going to be hard-pressed to find an editor which could elegantly
handle the catalog situation.

Somebody else might respond: but clearly there's some ill-conceived
organization here. Why aren't you using profiling to get the "1" and
"2"? Surely then, you could define a couple profiled phrases for
&foo;, then specify the profile when making the book. Well, consider
what might happen if I had 15 books that each required a unique
definition? Now every time that entity is used and I'm editing a book,
I've got to look at a massive chunk of profiled phrases. Still, I'm
considering this to be the only reasonable route to take; if you name
your entities well enough you can hide their text values when editing
material in a nice full-featured editor.

-Sam

On Sat, Sep 25, 2010 at 8:25 AM, Jim Campbell <jwcampbell@gmail.com> wrote:
> Hi All,
>
> As I understand it, the xincludes feature provides a number of advantages
> over use of entities, but are there some situations where entities are still
> relevant and recommended?
>
> For example, I'm considering the use of click-paths for guimenu > guisubmenu
> chains.  In the past, we have used an entity file to house all of the
> guimenu click-paths for our documentation.  If the guimenu click-path
> changed, we would just update it in our entities file, and it would be
> updated throughout the documentation.  It seems that using xinclude +
> xpointer to perform the same feature would be overkill for in performing the
> same task. Similarly, in the past we have used entities to handle updates to
> version numbering, and it seems that xinclude + xpointer would be overkill
> there, as well.
>
> Much of how I've seen xinclude being used seems to be relevant for including
> entire chapters or otherwise large chunks of text, and I do see the
> relevance there.  Is xinclude helpful and manageable for smaller textual
> insertions, too, or are entities still a reasonable way to go for these
> types of uses?
>
> Thanks for your help,
>
> Jim
>
> P.S.  I do understand that DocBook version 5 schemas do not support entity
> declarations in the schema, and that I'd have to reference the entities file
> via the doctype declaration.
>

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org