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

[Sam Fischmann <sam.fischmann@gmail.com>]

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
>
>