Re: Structure/Schema - Custom or off the shelf?
Mike Feimster wrote: I've enjoyed the exchange as well. I also read the thread on the DITA list and stumbled across Tim Bray's opinion last week. (Does anyone else see the irony in the fact that one of the creators of a language that allows you to create your own markup language is telling people not to create their own markup language?) If only he'd known then what he knows now - he could have developed the 5 schemas needed by humankind and saved the rest of us the trouble of learning XML in the first place... ;-) I guess the answer to my original question is a resounding it depends. And only a highly paid consultant would know for sure. : ) Now you're getting the hang of it... ;-) Seriously. It seems that the common ground is that before you can decide, you have to do the analysis. If you're requirements are close to an established schema, start with one of those. Otherwise, you're better off creating your own (provided you have the resources or talent available to generate the final outputs. I think that's a pretty fair summary, though I would add that you may be able to convert your custom structure into an OTS structure for publishing. That gives you your cake and lets you eat it as well - you get the richness and security of a custom structure and the application support for your outputs. Moving between structures with XSLT isn't conceptually that much more difficult than creating mapping tables in FrameMaker, though you do need to know the syntax. -- Regards, Marcus Carr email: [EMAIL PROTECTED] ___ Allette Systems (Australia) www:http://www.allette.com.au ___ Everything should be made as simple as possible, but not simpler. - Einstein ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: Structure/Schema - Custom or off the shelf?
I've enjoyed the exchange as well. I also read the thread on the DITA list and stumbled across Tim Bray's opinion last week. (Does anyone else see the irony in the fact that one of the creators of a language that allows you to create your own markup language is telling people not to create their own markup language?) I guess the answer to my original question is a resounding it depends. And only a highly paid consultant would know for sure. : ) Seriously. It seems that the common ground is that before you can decide, you have to do the analysis. If you're requirements are close to an established schema, start with one of those. Otherwise, you're better off creating your own (provided you have the resources or talent available to generate the final outputs. Thanks Mike -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] om] On Behalf Of Alan Houser Sent: Wednesday, February 08, 2006 12:06 PM To: Framers@FrameUsers.com Subject: Re: Structure/Schema - Custom or off the shelf? Hi Marcus, I've enjoyed our exchange. The contrast between Micheal's and Eliot's opinions is fascinating, and insightful. Eliot has a long-standing reputation in the markup languages community, while Michael's reputation is solid as a designer of DITA and much of the underlying XSLT processing required to implement the DITA architecture. Yet they disagree. To add yet another opinion to the mix, Tim Bray, a co-author of the XML recommendation, warns of the requisite effort and risks in designing any new substantial markup vocabulary, and advises readers to begin by evaluating the capabilities of the big five proven XML vocabularies (I would add DITA to his list). http://www.tbray.org/ongoing/When/200x/2006/01/08/No-New-XML-Languages . Why does Michael advocate using DITA out-of-the-box? I can't speak for him, but I suspect the answer lies at least partially in the size and structure of IBM's product development teams, which resemble small-to-medium software companies more than tightly-integrated members of a $150+ billion dollar enterprise. I tend to agree with you and Eliot for XML implementations in which the business requirements mandate a substantially new vocabulary, and the budget supports the necessary development and implementation effort. However, many (especially smaller) organizations face business needs that can be met by subsetting DocBook or using DITA as-is or nearly so. In addition, these vocabularies provide the necessary processing toolkits for generating output. The latter can be a complex, costly effort that is often out-of-reach of smaller organizations who are evaluating a migration to XML-based publishing. This range of needs and budgets reminds me of an exchange I had in the exhibit hall at last year's STC conference in Seattle. I approached one of the well-known content management vendors, and said Do you have a solution in the mid-five figures [U.S. dollars]? If so, I could recommend it to many of my clients. He replied enthusiastically, Yes, most of our implementations are in the half-million dollar range, then proceeded to rattle off several members of the Fortune 100. I listened politely before moving on to the next booth. -Alan Marcus Carr wrote: Alan Houser wrote: DITA architect Michael Priestley (a co-author of the 2001 paper you cited) has more recently addressed the misconception that DITA is an exchange format, not an authoring format (http://groups.yahoo.com/group/dita-users/message/1081). My anecdotal experience matches Michael's -- that about half of all implementations use the DITA DTD out of the box for content authoring. This showed up in a conference plug recently and I revisited the link that Alan provided to Michael Priestly's posting. Out of interest, I looked at the post to which Michael had replied, and found it was a very good email from Eliot Kimber - one of the long-term industry experts going well back into the SGML days. His explanation is far better than mine was, but echoed much of the same sentiment. If you're interested, have a look at http://groups.yahoo.com/group/dita-users/message/1080. -- --- Alan Houser, President Group Wellesley, Inc. 412-363-3481 www.groupwellesley.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/mike.feimster%40acstechn ologies.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources
Re: Structure/Schema - Custom or off the shelf?
Hi Marcus, I've enjoyed our exchange. The contrast between Micheal's and Eliot's opinions is fascinating, and insightful. Eliot has a long-standing reputation in the markup languages community, while Michael's reputation is solid as a designer of DITA and much of the underlying XSLT processing required to implement the DITA architecture. Yet they disagree. To add yet another opinion to the mix, Tim Bray, a co-author of the XML recommendation, warns of the requisite effort and risks in designing any new substantial markup vocabulary, and advises readers to begin by evaluating the capabilities of the big five proven XML vocabularies (I would add DITA to his list). http://www.tbray.org/ongoing/When/200x/2006/01/08/No-New-XML-Languages . Why does Michael advocate using DITA out-of-the-box? I can't speak for him, but I suspect the answer lies at least partially in the size and structure of IBM's product development teams, which resemble small-to-medium software companies more than tightly-integrated members of a $150+ billion dollar enterprise. I tend to agree with you and Eliot for XML implementations in which the business requirements mandate a substantially new vocabulary, and the budget supports the necessary development and implementation effort. However, many (especially smaller) organizations face business needs that can be met by subsetting DocBook or using DITA as-is or nearly so. In addition, these vocabularies provide the necessary processing toolkits for generating output. The latter can be a complex, costly effort that is often out-of-reach of smaller organizations who are evaluating a migration to XML-based publishing. This range of needs and budgets reminds me of an exchange I had in the exhibit hall at last year's STC conference in Seattle. I approached one of the well-known content management vendors, and said Do you have a solution in the mid-five figures [U.S. dollars]? If so, I could recommend it to many of my clients. He replied enthusiastically, Yes, most of our implementations are in the half-million dollar range, then proceeded to rattle off several members of the Fortune 100. I listened politely before moving on to the next booth. -Alan Marcus Carr wrote: Alan Houser wrote: DITA architect Michael Priestley (a co-author of the 2001 paper you cited) has more recently addressed the misconception that DITA is an exchange format, not an authoring format (http://groups.yahoo.com/group/dita-users/message/1081). My anecdotal experience matches Michael's -- that about half of all implementations use the DITA DTD out of the box for content authoring. This showed up in a conference plug recently and I revisited the link that Alan provided to Michael Priestly's posting. Out of interest, I looked at the post to which Michael had replied, and found it was a very good email from Eliot Kimber - one of the long-term industry experts going well back into the SGML days. His explanation is far better than mine was, but echoed much of the same sentiment. If you're interested, have a look at http://groups.yahoo.com/group/dita-users/message/1080. -- --- Alan Houser, President Group Wellesley, Inc. 412-363-3481 www.groupwellesley.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Structure/Schema - Custom or off the shelf?
Alan: Those are great comments and bring up some valid points. It will be interesting to see how Michael Priestley addresses these in his upcoming DITA workshop -- Introduction to DITA -- at the upcoming DITA 2006 conference this March. I've jotted these issues down and hope to get Michael to address them in the workshop. Hope to see you there. About DITA 2006 -- http://www.travelthepath.com/conf/ About Michael Priestley -- http://www.travelthepath.com/conf/MichaelPriestley25.html == The Content Wrangler Scott Abel, Content Management Strategist 3421 Crystal Lakes Ct., Sarasota FL 34235 [EMAIL PROTECTED] 941-359-3416 www.thecontentwrangler.com Recent posts to TheContentWrangler.com ~ $3,500 A Page: “Six Degrees of Documentation” ~ Whitepaper - Planning for DITA Success: How to Set Up the Right Team and the Right Strategy ~ Structured RSS Feeds Help Search Engines ~ DITA 2006 Conference Boasts Big Speakers, Sponsors ~ Webinar: Global Content Management Success at Siemens Medical ~ Free 2006 Semantic Technologies Conference Tickets ~ New Indianapolis DITA User Group Announced ~ The Next Big Thing In Searching On Feb 3, 2006, at 2:00 AM, [EMAIL PROTECTED] wrote: I've valued your opinions over the years, but I must take exception to your assessments of both DITA and DocBook. DITA architect Michael Priestley (a co-author of the 2001 paper you cited) has more recently addressed the misconception that DITA is an exchange format, not an authoring format (http://groups.yahoo.com/group/dita-users/message/1081). My anecdotal experience matches Michael's -- that about half of all implementations use the DITA DTD out of the box for content authoring. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Newbie structure Q: was Re: Structure/Schema - Custom or off the shelf?
At 6:08 am +1100 3/2/06, [EMAIL PROTECTED] wrote: DocBook is a worthless bucket of elements. Sorry. I had a look yesterday and quickly found two examples that were enough to reconfirm my opinion. The first was that footnotes can contain paras that can contain footnotes, so you could have bottomlessly recursive nested footnotes. That reminds me of something I meant to find out. How can you limit the nesting depth of elements to a value other than zero? -- Steve ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Newbie structure Q: was Re: Structure/Schema - Custom or off the shelf?
At 5:23 am -0500 3/2/06, Alan Houser wrote: Unfortunately, there's no way to do this with an XML DTD. However, it's not hard to determine an element's nesting level when processing XML with XSLT or even a FrameMaker EDD. For example, a FrameMaker EDD might specify a text prefix of Element nested too deeply to report back to the author when he/she has violated a nesting convention (nesting a section too deeply, for example). Right: so you can use a level rule to *alert* the user, but there's nothing you can do to actually *remove* the element from the element catalog when selecting it would invalidate a nesting depth restriction, right? -- Steve ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Newbie structure Q: was Re: Structure/Schema - Custom or off the shelf?
This is correct -- you can only alert based on nesting depth. I suspect one could write an FDK client to actually restrict the legal nesting depth as you describe. One of the more obscure XML schema languages (Schematron) already provides this capability outside FrameMaker. -Alan Steve Rickaby wrote: Right: so you can use a level rule to *alert* the user, but there's nothing you can do to actually *remove* the element from the element catalog when selecting it would invalidate a nesting depth restriction, right? ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Structure/Schema - Custom or off the shelf?
Organizations are successful when they meet their business requirements as efficiently (time and $$$) as possible. I talk lots of people _out_ of migrating to XML for this reason. I even occasionally say you're doing just fine with MS Word. I think the answer to the custom or off-the-shelf question differs with each customer's business requirements and even tool choice. For FrameMaker XML implementations, I'm much more likely to recommend designing your own DTD. FrameMaker handles the hard part of publishing XML (printing it), and provides a reasonable environment for building your information model (the structured EDD). It's also relatively difficult to get FrameMaker to play with most off-the-shelf DTDs, mainly because of the constraints of the FrameMaker import/export model. Rolling your own DTD becomes an attractive option with FrameMaker. If you're migrating to XML, *not* using FrameMaker, and have print/PDF as one of your output requirements, take a good hard look at using or leveraging a standard information model, like DocBook or DITA. Printing XML using XSL-FO is one of the most difficult tasks you will face, and leveraging the XSLT transforms for an off-the-shelf DTD is likely to save a very substantial amount of development time. By the way, I never recommend starting out with out-of-the-box DocBook -- if you use DocBook, I always favor constraining it. My observation comes from a couple of implementations in which the client said no thanks, we're not going to bother constraining DocBook. Those clients were creating fairly homogeneous information deliverables, and it turned out that the writers were far more successful at marking up these deliverables than I had expected, because they did so by example. Just an observation. It's also important to remember that a DTD alone isn't sufficient to structure your data. A DTD cannot specify all possible constraints (the recent nesting level discussion is just one example), nor can it prevent the use of valid but semantically-incorrect tags. There always needs to be a human element for markup review and quality control. -Alan [EMAIL PROTECTED] wrote: Alan Houser wrote: Regarding DocBook -- I acknowledge that it's big, and has a designed by committee feel. However, I've seen too many companies use it successfully to dismiss it. Many companies use MSWord and other less than ideal tools. Also strongly depends on your definition of successfully. Having a set of extensible XSLT transformations is absolutely invaluable -- not for the easy stuff, like transforming title to h1, but for the hard stuff, like building a back-of-the-book index. Try writing that XSLT code from scratch. True. But, any self respecting implementer should see how they can create their own work environment that can perhaps integrate with and leverage the existing tools. DocBook's size isn't necessarily the problem it may appear to be. Authors tend to learn markup languages by example. Their approach is typically here's how we mark up a help topic in DocBook (bottom-up), as opposed to which of DocBook's 400 elements do I need to mark up a help topic? (top-down). Another Yuck. Many people use MSWord styles in much the same manner. What's the point of adopting a structured environment if your not going to adopt a design that actually structures and controls your data? here's how we mark up a help topic in DocBook Should be a very easy exercise to take and create a working subset of Docbook. Then there's little authors can do wrong. Eric L. Dunn Senior Technical Writer PS: If this makes it to the list could someone give me a heads up? -- --- Alan Houser, President Group Wellesley, Inc. 412-363-3481 www.groupwellesley.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Structure/Schema - Custom or off the shelf?
--- Alan Houser [EMAIL PROTECTED] wrote: Organizations are successful when they meet their business requirements as efficiently (time and $$$) as possible. I talk lots of people _out_ of migrating to XML for this reason. I even occasionally say you're doing just fine with MS Word. Certainly, there's no rational reason to migrate to XML unless you intend (now or in the future) to manage your documentation by storing it (parsed into its constituent components) in a database/CMS, or your customer(s) demand that your documentation be delivered to them in that form for the same purpose. The other case where XML may be important is database publishing of catalogs, directories, etc., where the content is originated in the database, and must be output to a publishing engine such as FrameMaker. However, there are several other forms (e.g., character-delimited, fixed field, and others) in which any database can output the data, and, in my experience these alternatives are better than XML for database publishing. = Printing XML using XSL-FO is one of the most difficult tasks you will face, and leveraging the XSLT transforms for an off-the-shelf DTD is likely to save a very substantial amount of development time. == And there's the rub, isn't it. The whole idea of SGML and XML is based on the premise that structure and metadata are the important things, and thus all formatting information must be striped out of the stored content. But then the extreme difficulties and high cost associated with developing customized, adaptable XSL-FO, FOSI or DSSL appications forces companies to select a non-optimal standard DTD so they don't have to do any formatting development. Thus, the desira to create a customized DTD that provides the optimal structure for an enterprise must be abandoned snd replaced with a dreary standard DTD like Docbook or DITA. And they must also accept the dreary formatting produced by the standard formatting application. So the original concept that structure is more important than formatting, is, in reality reversed, and the typical enterprise is forced to accept an easy solution to the formatting problem by choosing a mediocre standard monstrosity such as Docbook or DITA. Does that make any sense? Not to me it doesn't. === By the way, I never recommend starting out with out-of-the-box DocBook = That's like putting lipstick on the pig. It's still a pig. And each modification of Docbook or DITA may imply major costs in adapting the standard XSL-FO application which caused you to select the pig in the first place. Thus, significant modification of the pig is likely to be discouraged. Dan Emory Associates FrameMaker/FrameMaker+SGML Document Design Database Publishing DW Emory [EMAIL PROTECTED] ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Structure/Schema - Custom or off the shelf?
Alan Houser wrote: Organizations are successful when they meet their business requirements as efficiently (time and $$$) as possible. I talk lots of people _out_ of migrating to XML for this reason. I even occasionally say you're doing just fine with MS Word. Perhaps our roles are one of the reasons that ours views differ. My role is typically to make migration efficient for companies that have some committment to going to XML in the first place, so I do very few Word vs. XML deliberations. If you're migrating to XML, *not* using FrameMaker, and have print/PDF as one of your output requirements, take a good hard look at using or leveraging a standard information model, like DocBook or DITA. Printing XML using XSL-FO is one of the most difficult tasks you will face, and leveraging the XSLT transforms for an off-the-shelf DTD is likely to save a very substantial amount of development time. Creating XSL-FO is easy - I just tell a programmer what I want. Before you dismiss that as glib consider an alternative approach - say, using Perl to convert the XML to RTF. Either of these approaches are tasks for a programmer and using appropriate resources is at least as important as using the right structure. This should be apparent - you can be pretty sure that the people who wrote the XSL for the OTS schemas were programmers, not writers. Also, XSL-FO is typically used when the print process is a terminal use of the data. If that's all you need, then another approach is to convert the XML into another structure that is more Frame-friendly. There are ways of making publishing the data less difficult. By the way, I never recommend starting out with out-of-the-box DocBook -- if you use DocBook, I always favor constraining it. My observation comes from a couple of implementations in which the client said no thanks, we're not going to bother constraining DocBook. Those clients were creating fairly homogeneous information deliverables, and it turned out that the writers were far more successful at marking up these deliverables than I had expected, because they did so by example. Just an observation. They may have been equally successful, but they weren't *more* successful than if the structure was more concise, so what did they gain? As far as I can see, they saved the cost of cutting it down at the expense of increasing the complexity of adding new writers needing to mark up by example. I'd suggest that's a pretty poor decision. It's also important to remember that a DTD alone isn't sufficient to structure your data. A DTD cannot specify all possible constraints (the recent nesting level discussion is just one example), nor can it prevent the use of valid but semantically-incorrect tags. There always needs to be a human element for markup review and quality control. There are ways of dealing with issues like nesting, but overall I agree - humans need to play a role. Unfortunately, it's mostly to catch the mistakes made by other humans... ;-) Marcus ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Newbie structure Q: was Re: Structure/Schema - Custom or off the shelf?
At 6:08 am +1100 3/2/06, mcarr at allette.com.au wrote: >DocBook is a worthless bucket of elements. Sorry. I had a look yesterday >and quickly found two examples that were enough to reconfirm my opinion. >The first was that footnotes can contain paras that can contain footnotes, >so you could have bottomlessly recursive nested footnotes. That reminds me of something I meant to find out. How can you limit the nesting depth of elements to a value other than zero? -- Steve
Newbie structure Q: was Re: Structure/Schema - Custom or off the shelf?
Unfortunately, there's no way to do this with an XML DTD. However, it's not hard to determine an element's nesting level when processing XML with XSLT or even a FrameMaker EDD. For example, a FrameMaker EDD might specify a text prefix of "Element nested too deeply" to report back to the author when he/she has violated a nesting convention (nesting a too deeply, for example). -Alan Steve Rickaby wrote: > That reminds me of something I meant to find out. How can you limit the > nesting depth of elements to a value other than zero? > -- --- Alan Houser, President Group Wellesley, Inc. 412-363-3481 www.groupwellesley.com
Newbie structure Q: was Re: Structure/Schema - Custom or off the shelf?
At 5:23 am -0500 3/2/06, Alan Houser wrote: >Unfortunately, there's no way to do this with an XML DTD. However, it's not >hard to determine an element's nesting level when processing XML with XSLT or >even a FrameMaker EDD. For example, a FrameMaker EDD might specify a text >prefix of "Element nested too deeply" to report back to the author when he/she >has violated a nesting convention (nesting a too deeply, for >example). Right: so you can use a level rule to *alert* the user, but there's nothing you can do to actually *remove* the element from the element catalog when selecting it would invalidate a nesting depth restriction, right? -- Steve
Newbie structure Q: was Re: Structure/Schema - Custom or off the shelf?
This is correct -- you can only alert based on nesting depth. I suspect one could write an FDK client to actually restrict the legal nesting depth as you describe. One of the more obscure XML schema languages (Schematron) already provides this capability outside FrameMaker. -Alan Steve Rickaby wrote: > Right: so you can use a level rule to *alert* the user, but there's nothing > you can do to actually *remove* the element from the element catalog when > selecting it would invalidate a nesting depth restriction, right? >
Re: Structure/Schema - Custom or off the shelf?
Mike Feimster wrote: The Real Life Migration to Stuctured Doc thread got me thinking. What is better? A custom schema or one the standards such as Docbook or DITA. DITA was designed by IBM for data interchange, so was never really intended as a data authoring structure. This can be confirmed by the creators of DITA at http://www-128.ibm.com/developerworks/xml/library/x-dita1/ where it states: First, both SGML and XML are recognized as meta languages that allow communities of data owners to describe their information assets in ways that reflect how they develop, store, and process that information. Because knowledge representation is so strongly related to corporate cultures and community jargon, most attempts to define a universal DTD have ended up either unused or unfinished. The ideal for information interchange is to share the semantics and the transformational rules for this information with other data-owning communities. So the bottom line is that DITA was never intended to replace a custom schema - it was designed to facilitate date exchange between arbitrary schemas. Nothing wrong with using DITA for that - it makes good sense in that role. DocBook is a worthless bucket of elements. Sorry. I had a look yesterday and quickly found two examples that were enough to reconfirm my opinion. The first was that footnotes can contain paras that can contain footnotes, so you could have bottomlessly recursive nested footnotes. No typesetting application is going to be able to make sense of that, so you're going to have to either tell it to ignore the ridiculous scenarios or remove them from the structure in the first place. The second was that table entries can nest tables in the same way. Good luck rendering that - FrameMaker won't even break an entry over a page, let alone support a handful of levels of tables nested in entries. Sure I could cut DocBook down, but when the starting point involves removing the ridiculous before I can even think of doing anything sensible, I lose patience fast. A far better approach (IMHO) is to start with the simplest schema you can and extend it as required. When someone asks for a new element or looser structure, make 'em justify it. Be ruthless about this - someone has to code for the changes, so make sure they really need it. Extending then becomes an engineering exercise - you can evaluate the impact and the cost of the proposed change, carry out regression testing on any XSLT or other system components, document the change properly, etc. If you must use a DocBook tool, create your schema using DocBook naming conventions and structures, but build it from the ground up, don't cut the big one down. Your analysis will be more thourough and your results better. Oh yeah, and make sure that when you finish playing with DocBook you wash your hands... Marcus ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Structure/Schema - Custom or off the shelf?
Marcus, I've valued your opinions over the years, but I must take exception to your assessments of both DITA and DocBook. DITA architect Michael Priestley (a co-author of the 2001 paper you cited) has more recently addressed the misconception that DITA is an exchange format, not an authoring format (http://groups.yahoo.com/group/dita-users/message/1081). My anecdotal experience matches Michael's -- that about half of all implementations use the DITA DTD out of the box for content authoring. Regarding DocBook -- I acknowledge that it's big, and has a designed by committee feel. However, I've seen too many companies use it successfully to dismiss it. Having a set of extensible XSLT transformations is absolutely invaluable -- not for the easy stuff, like transforming title to h1, but for the hard stuff, like building a back-of-the-book index. Try writing that XSLT code from scratch. DocBook's size isn't necessarily the problem it may appear to be. Authors tend to learn markup languages by example. Their approach is typically here's how we mark up a help topic in DocBook (bottom-up), as opposed to which of DocBook's 400 elements do I need to mark up a help topic? (top-down). I would also argue that the ugly but legal DocBook constructs you observed are due to limitations in the expressive capabilities of XML DTDs, not of DocBook per se. I'm not saying use DITA or use DocBook. There's lots of value in building custom DTDs, and organizations do it successfully all the time. However, many organizations under-estimate the effort required to build the publishing component (e.g., XSLT transformations) to accompany a custom DTD. If you have the time and expertise to do this yourself, great. If not, or if you would prefer to devote this effort elsewhere, architectures like DITA, DocBook, or Scriptorium's DocFrame, which include the necessary publishing component, can become much more appealing than a home-grown alternative. -Alan [EMAIL PROTECTED] wrote: DITA was designed by IBM for data interchange, so was never really intended as a data authoring structure. This can be confirmed by the creators of DITA at http://www-128.ibm.com/developerworks/xml/library/x-dita1/ where it states: First, both SGML and XML are recognized as meta languages that allow communities of data owners to describe their information assets in ways that reflect how they develop, store, and process that information. Because knowledge representation is so strongly related to corporate cultures and community jargon, most attempts to define a universal DTD have ended up either unused or unfinished. The ideal for information interchange is to share the semantics and the transformational rules for this information with other data-owning communities. So the bottom line is that DITA was never intended to replace a custom schema - it was designed to facilitate date exchange between arbitrary schemas. Nothing wrong with using DITA for that - it makes good sense in that role. DocBook is a worthless bucket of elements. Sorry. I had a look yesterday and quickly found two examples that were enough to reconfirm my opinion. The first was that footnotes can contain paras that can contain footnotes, so you could have bottomlessly recursive nested footnotes. No typesetting application is going to be able to make sense of that, so you're going to have to either tell it to ignore the ridiculous scenarios or remove them from the structure in the first place. The second was that table entries can nest tables in the same way. Good luck rendering that - FrameMaker won't even break an entry over a page, let alone support a handful of levels of tables nested in entries. Sure I could cut DocBook down, but when the starting point involves removing the ridiculous before I can even think of doing anything sensible, I lose patience fast. A far better approach (IMHO) is to start with the simplest schema you can and extend it as required. When someone asks for a new element or looser structure, make 'em justify it. Be ruthless about this - someone has to code for the changes, so make sure they really need it. Extending then becomes an engineering exercise - you can evaluate the impact and the cost of the proposed change, carry out regression testing on any XSLT or other system components, document the change properly, etc. If you must use a DocBook tool, create your schema using DocBook naming conventions and structures, but build it from the ground up, don't cut the big one down. Your analysis will be more thourough and your results better. Oh yeah, and make sure that when you finish playing with DocBook you wash your hands... Marcus ___ -- --- Alan Houser, President Group Wellesley, Inc. 412-363-3481 www.groupwellesley.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to
Re: Structure/Schema - Custom or off the shelf?
Alan Houser wrote: I've valued your opinions over the years, but I must take exception to your assessments of both DITA and DocBook. DITA architect Michael Priestley (a co-author of the 2001 paper you cited) has more recently addressed the misconception that DITA is an exchange format, not an authoring format (http://groups.yahoo.com/group/dita-users/message/1081). My anecdotal experience matches Michael's -- that about half of all implementations use the DITA DTD out of the box for content authoring. Yes, but why? I believe that it's because there's tool support for DITA, not necessarily because it's the best structure for the data. There's nothing magical about the structure of DITA, so why hasn't anyone else been so clever in the last 30 years of structured documents as to stumble across this little beauty of a structure? People use DITA out of the box because when coupled with other DITA tools, they find they've got a low entry point to doing XML. Are they really doing the right thing? My feeling is that if DITA is a replacement for analysis, they may not be. Put another way, what does DITA out of the box give you that XHTML doesn't? Regarding DocBook -- I acknowledge that it's big, and has a designed by committee feel. However, I've seen too many companies use it successfully to dismiss it. Having a set of extensible XSLT transformations is absolutely invaluable -- not for the easy stuff, like transforming title to h1, but for the hard stuff, like building a back-of-the-book index. Try writing that XSLT code from scratch. Use it for turning bytes into hardcopy? No problem. Use it as a corporate data structure used to drive a variety of products? Less likely, I would think. No question though - tools can be handy. I guess my point is that if your structures are so generic as to be supportable by existing tools, are they specific enough for your long-term data requirements? DocBook's size isn't necessarily the problem it may appear to be. Authors tend to learn markup languages by example. Their approach is typically here's how we mark up a help topic in DocBook (bottom-up), as opposed to which of DocBook's 400 elements do I need to mark up a help topic? (top-down). The overall size isn't necessarily the problem, it's the number of choices available in the elements when you're working bottom-up. The examples I provided were footnotes and table entries. I just did a rough count on footnotes and they appear to support something like 55 elements. Call me crazy, but I doubt if 95% of anyone's documents would ever require more than 5 elements in a footnote, so forcing users to sift through the other 50 is wasted effort. Sure you could cut the other 50 elements out of the schema, but I'd rather establish which elements I really *want* to allow in a footnote and then add them. I would also argue that the ugly but legal DocBook constructs you observed are due to limitations in the expressive capabilities of XML DTDs, not of DocBook per se. ;-) If DocBook isn't able to be be elegantly represented in XML, to me that points to a problem with DocBook, not with XML. XML isn't perfect by any stretch of the imagination, but it's been judged to be good enough to sweep everything in its path. I'm not saying use DITA or use DocBook. There's lots of value in building custom DTDs, and organizations do it successfully all the time. And by the same token, I'm not saying don't use DITA or DocBook - there are good uses for both. I'm just saying that the fact that they exist doesn't necessarily mean that they'll be less work or equally useful to creating a schema from scratch. Sometimes they will, sometimes they won't. However, many organizations under-estimate the effort required to build the publishing component (e.g., XSLT transformations) to accompany a custom DTD. If you have the time and expertise to do this yourself, great. If not, or if you would prefer to devote this effort elsewhere, architectures like DITA, DocBook, or Scriptorium's DocFrame, which include the necessary publishing component, can become much more appealing than a home-grown alternative. I'd be inclined to contract out the XSLT work and concentrate my efforts on the data structures. Mediocre XSLT applied to data following a well-conceived structure will never give you heartburn the way elegant XSLT run over a sub-optimal data structure will. You can tune XSLT later, but you tend not to get the same luxury with the structure. Once you've started creating data to it, changes to the schema can impact your entire data set. Only yesterday I received email from a list member who had been inspired by this thread to update me with the results of their implementation. This person created their first structured FrameMaker application *because* of the DocBook-derived monster the users were currently wrestling with. They were happy, and now the learning curve has been
Re: Structure/Schema - Custom or off the shelf?
The main advantages to using one of the standard schemas: 1) It has been developed and used by others so it has the benefit of being tested and proven with actual documentation. 2) Even if it needs to be customized, you have a head-start in the development process. 3) If there is already an EDD, etc., for the standard, you can try it out before spending a lot of time or money. 4) There will be other users and developers that you can solicit for help and advice. 5) There may be existing tools (templates, XSLT stylesheets, etc.) that you can use in your environment. Rick Quatro Carmen Publishing 585-659-8267 www.frameexpert.com The Real Life Migration to Stuctured Doc thread got me thinking. What is better? A custom schema or one the standards such as Docbook or DITA. I've often thought that if one knows how to create a schema (and the resulting EDD, DTD, XSD, etc.) you're better off creating your own, especially since Docbook and, to a lesser extent, DITA would need to be customized to realize the true potential of XML. I'm curious as to what others think about this. --- Mike Feimster IDD Technical Analyst ACS Technologies 180 N. Dunbarton Drive Florence, SC 29501 p / 843.413.8122 f / 843.413.8122 e / [EMAIL PROTECTED] ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Structure/Schema - Custom or off the shelf?
Hi Michael, Good points, well taken. Thanks. Rick I agree with Rick's points. But there are situations where it might not be worth the effort digging deep in the available material for a so-called standard, when -- in the end -- the customized solution still needs non-standard modifications. As an example: DocBook comes with many more elements than you will likely use and the available XSL transformations deal with almost all of them. During all your initial setup work and all maintenance steps you will somehow have to deal with a lot of stuff you never use. I learned that the maintenance effort is somehow proportional to the number of elements and attributes in a DTD. So from my point of view it is a good idea to start with a DTD/Schema as simple as possible. If you add elements or attributes during your testing phase you do not invalidate existing documents. A good example of such a minimalistic approach is the DocFrame environment created by Scriptorium Publ. IMO it is a perfect head-start for FrameMaker users. http://scriptorium.com/docframe/ If you need/want to be compatible with some other structure later on, you can create an XSL stylesheet to take care of that compatibility. - Michael ___ You are currently subscribed to Framers as [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
