OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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.



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


Camille Bégnis wrote:
> 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.
> 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
> ---------------------------------------------------------------------
> 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]