[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] Polymorphic Modular DocBook
This is something I had to defend at my current employer too.. So would like to share my perspective.. I do see the benefits of topic-based XML aproach - as suggested by DITA and S1000D.. It clearly is a good model to discuss XML chunks and suggests authoring content in a modular format up front and not keep the book in mind.. (It has implications on the writing style and the flow of content in topics and books).. DocBook (or any other book DTD) can also support reuse simply by the fact that is uses XML and thus can leverage XInclude or File Entities in DTDs.. In other words any XML system - even if it is built with a book in mind - supports reuse concepts just as easily.. For e.g. if you're gonna use DITA (since Camille mentioned it), and if you're not gonna specialize it any further, then that is the equivalent of using <sections> tags in DocBook.. You just create topics as sections and store each topic separately in the filessytem and then instead of using a ditamap use the DocBook DTD to assemble it as a book. It would be nice to have some sort of a DITAMAP equivalent to help assembling books as collections as part of the XML specification.. That seems to be the missing piece in XML which DITA and S1000D has addressed in their solution. Advanced XML use --------------------- A good way to link/reuse chunks though is to use meaningful tags that are meaningful to your business and authors instead of treating everythign as a section or concept, task and reference as in DITA.. for e.g. <hardware-specification>, <verification-task>, <order-info> etc.. And since each business will have its own preferences, I look at open-source standards as a building block that needs to be customized as per the business needs.. What was ironix is that I've attended a lot of DITA presentation where they say that specialization is too erstrictive, not-DITA anymore etc.. and they recommended against using specialization completely.. My ding on DITA is that without specialization, you're not much different then what DocBook acn do with using section tags.. The only benefit then is the idea od a DITA map - which, as I've said - should not be part of DITA but an XML standard.. Regards. -- Rajal ----- Original Message ----- From: "Rowland, Larry" <larry.rowland@hp.com> To: "Scott Hudson" <scott.hudson@flatironssolutions.com>; "Camille Bégnis" <camille@neodoc.biz> Cc: "docbooklist" <docbook@lists.oasis-open.org> Sent: Thursday, June 22, 2006 8:26 AM Subject: RE: [docbook] Polymorphic Modular DocBook > Hello Camille, > > I have to agree with Scott. I have had excellent success with content > reuse based on DocBook, both within and among documents. Furthermore, > with the XML tools that are currently available, I find that the whole > idea of arbitrary chunking of content into some level of container for > reuse is no longer critical. I have been able to reuse content from the > middle of a file by referencing the ID on the element and then pulling it > into place where I need it. > > I also find that inclusion works best on a level below the > chapter-equivalent elements. The chapter element typically has the > introductory information appropriate to the context in which the > information is being presented. I reuse sections, tables, and admonitions > quite frequently and have even, on occasion, reused an introductory > paragraph. With XPATH based inclusion operators (such as xinclude, > although we wrote our own to allow converting among similar grammars on > the fly), I can "chunk" on any element, without regard to where it is > located in the file; just provide the filepath and the XPATH to access > anything inside the file. With many processors, the file reference can > include an HTTP reference, which we use for accessing content across > repositories. > > Regards, > > Larry > > -----Original Message----- > From: Scott Hudson [mailto:scott.hudson@flatironssolutions.com] > Sent: Thursday, June 22, 2006 8:55 AM > To: Camille Bégnis > Cc: docbooklist > Subject: Re: [docbook] Polymorphic Modular DocBook > > Hi Camille, > > IMO, DocBook works very well for modular documentation. That said, I > usually recommend chunking at the section level, leaving the book, > chapters, etc. as "assembly templates/documents". The book and chapters > contain the higher level wrappers and additional verbage that is > appropriate for that level, and then contain entity references or > XIncludes to the section-level chunks that are to be reused. > > Best regards, > > --Scott > > Camille Bégnis wrote: >> -----BEGIN PGP SIGNED MESSAGE----- >> Hash: SHA1 >> >> Hi all, >> >> I used big words in the subject, but it's a simple issue: When doing >> modular DocBook, it sometimes happen that a "chapter" module wants to be >> reused as an "appendix" for example... >> >> Is the only solution to use tinier modules by chunking at the "section" >> level, or is there something more intelligent? >> >> Or should we consider DocBook is not meant to be extremely modular, >> other grammars like DITA are more suited? >> >> Interested in hearing your experience. >> >> Camille. >> -----BEGIN PGP SIGNATURE----- >> Version: GnuPG v1.4.2.2 (GNU/Linux) >> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org >> >> iD8DBQFEmonQjv9P65BfOUMRAuqFAJ9RlFh43Jn//l5LCaP9/yN1S8D2qQCfRxNG >> IV+TMnLp+nz+mQJ5OBN92fg= >> =iban >> -----END PGP SIGNATURE----- >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org >> For additional commands, e-mail: docbook-help@lists.oasis-open.org > > > -- > > --------------------------------------------------------------------- > To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org > For additional commands, e-mail: docbook-help@lists.oasis-open.org >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]