Re: [docbook] Polymorphic Modular DocBook

["Rajal Shah" <rajal@meshsoftware.com>]

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
>