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

[Ron Catterall <ron@catterall.net>]

A quick contribution.
Use Xinclude for large amounts of text, entities for the small stuff.
One thing I have found useful is using entities to build a skeleton 
index as writing progresses, put all the primary index stuff into the 
entity.
Ron

On 9/26/10 9:55 AM, Denis Bradford wrote:
> Also see Bob Stayton's summary of using xincludes in
> http://www.sagehill.net/docbookxsl/DuplicateIDs.html.
> I've successfully implemented xincludes in place of entity refs, but it
> was tricky, along the lines that Sam describes.
>
> That's why I sat up when David mentioned Jirka's transclusion proposal.
> I sure hope it's adopted by the DocBook committee. I'm not much of a
> DITA fan, but resurrecting transclusions is one thing I do like about
> it. DITA conrefs are almost as verbose as xincludes, but they do avoid
> duplicate ids.
>
> On 09/26/2010 08:10 AM, Sam Fischmann wrote:
>> Sorry for mailing so much on this topic, but thanks for the link. The
>> information here is great to see, but I'm curious about the current
>> status of any work related to this proposal. My situation is difficult
>> because I'm sitting on a huge amount of material and don't want to
>> pull the trigger upgrading it until I'm certain I have good support
>> going forward from editors, parsers, stylesheets, etc. For now, I
>> wait.
>>
>> -Sam
>>
>> On Sat, Sep 25, 2010 at 1:25 PM, Cramer, David W (David)
>> <dcramer@motive.com> wrote:
>>> 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
>>>
>>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
>> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>>
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>
>

-- 
Ron Catterall Ph.D. D.Sc.
ron@catterall.net
http://catterall.net

S/MIME Cryptographic Signature