[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook-apps] Use of xincludes vs. entities
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 > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]