RE: [docbook] Add topic element to DocBook?

["Rowland, Larry" <larry.rowland@hp.com>]

Actually, section is a legal root element.  I have used it for chunking
books into files in the past for authoring convenience.

I agree that sections imply sequential content, but that hasn't
prevented me from using them for modular document development.  I
regularly reuse admonitions, tables, procedures, sections and list
items, on occasion even pulling an individual paragraph.  I can nest
sections inside other sections with no problem.  Modern XML with XPATH
makes much of what traditional content management systems did possible
without any real concern for where chunking occurs -- I frequently pull
elements out of the middle of a file by referencing the id on the
element.  I include sections from help systems in user guides and from
both in product Web sites.  The real problem with content reuse is
making sure the document constructed by assembling content is cohesive
when it is done.

This is not an argument for or against adding topic, just an attempt to
make it clear that topic is not necessary to accomplish modular
development.  Discipline in authoring is important (use explicit
references to other content rather than positional references -- no more
"as described in the preceding ...").  This seems more like a question
of making the author's intent clear (or possibly using terminology that
is trendy), rather than one of whether the grammar can support reuse.  I
already do significant reuse and suspect many authors out there using
DocBook do also.

I would like to make sure that if we add topic to an already large
collection of elements that it serves a truly valuable purpose in
clarifying the authors intent.  As far as I can tell, modifying the
grammar to allow section as a child of book and part appears to be the
only syntactic difference between section and topic.  I am still open on
what semantic value is added by adding it -- I recognize the value of
having multiple admonitions in the grammar over an admonition element
with a class attribute, I am still not clear how a topic differs from a
section other than the sequential content implication.

I do like the idea of a map element.  We had to invent one for
constructing help systems, and having something like that as a standard
from DocBook would be nice.

Larry Rowland 

-----Original Message-----
From: chris.chiasson@gmail.com [mailto:chris.chiasson@gmail.com] On
Behalf Of Chris Chiasson
Sent: Friday, October 27, 2006 9:51 AM
To: Johnson, Eric
Cc: docbook@lists.oasis-open.org
Subject: Re: [docbook] Add topic element to DocBook?

I haven't checked this, but I think section is not allowed as a root
element. This means that documents beginning with <section> will
require a DocBook schema customization to validate. I have had this
problem with documents that begin with <equation>.

Maybe it would be better if someone who actually wants <topic> to make
a case for it?

On 10/27/06, Johnson, Eric <Eric.Johnson@iona.com> wrote:
> As a member of a group who is currently switching from unstructured
> Frame to an XML based authoring system, I think the familiarity of
terms
> like section and book make the move smoother. They ease the semantic
> shift because we understand what a book, chapter, section, etc are.
> Having read through much of the Docbook literature, I don't see any
> reason why I could not write my content at the section level and then
> reassemble the sections into any form that I need. It may be called a
> book in mark-up, but the end result is whatever I want it to be.
> Maybe a <map> element could be a useful tool to make it easier to
build
> a larger unit of content out of section. However, it sounds like the
> current debate is about duplicating <section> with a <topic> element
for
> purely marketing reasons. Will the <topic> element have a different
> content model? Will it be usable in ways that the current <section>
> element is not? How will it make creating reusable content easier?
> I'm not saying that marketing is not a good reason for adding stuff,
but
> it is not a great one.
>
> > -----Original Message-----
> > From: Rajal Shah [mailto:rajal@meshsoftware.com]
> > Sent: Friday, October 27, 2006 11:33 AM
> > To: 'Michael(tm) Smith'; docbook@lists.oasis-open.org
> > Subject: RE: [docbook] Add topic element to DocBook?
> >
> > Mike -
> >
> > There are a lot of organization which have based their XML
> > authoring/publishing infrastructure on DocBook.. They've been
> > writing books all this time.. Now with DITA coming to the
> > fore and the fact that the TechPubs groups need to provide
> > customized content - based on new markets or even to improve
> > search results to find the exact topic/article that solves
> > customer's issue - they are forced to consider modular writing..
> >
> > The way to go about solving the issue is to provide a
> > mechanism within DocBook to continue producing books - as
> > collections of topics - as well have these individual topics
> > available for re-use or stand-alone..
> >
> > This is a very real scenario.. And has caused a lot of
> > confusion over whether to switch over to DITA despite having
> > DocBook.. And I think DocBook would be missing the point if
> > they didn't address how to support modular writing as well
> > have a mechanism to assemble topics into a book (it does that
> > current with the DTD v/s a map in DITA)..
> >
> > Regads.
> > --
> > Rajal
> >
> >
> > -----Original Message-----
> > From: Michael(tm) Smith [mailto:smith@sideshowbarker.net]
> > Sent: Friday, October 27, 2006 6:53 AM
> > To: docbook@lists.oasis-open.org
> > Subject: Re: [docbook] Add topic element to DocBook?
> >
> > Chris Chiasson <chris@chiasson.name>, 2006-10-27 00:28 -0500:
> >
> > > I am afraid of this new <topic> element. However, I don't
> > want DocBook
> > > to stagnate while DITA grows just because some people are afraid
of
> > > change.
> >
> > Substitute the word "wary" for "afraid". The thing about
> > changes is that they often have unforeseen consequences. For
> > example, we decided to add Task as a child of section, and a
> > year or two later, we've got to figure if/how to allow Task
> > content in places where by design it's currently not permitted.
> >
> > And I don't think there's any risk of DocBook stagnating.
> > It's soundly designed and is meeting the needs of its target
> > user base quite well. It's going to remain just as useful a
> > solution as it always has been: A common vocabulary and
> > processing infrastructure (the DocBook XSL stylesheets) that
> > even users/groups with very limited resources can learn and
> > use productively -- without the need or time or money to do
> > stuff like customizing/extending the schema/DTD or to write
> > their own sets of stylesheets.
> >
> > And as far as DITA goes, I guess some might argue that it's
> > tuned for a different target user base: organizations that
> > manage large and complex sets of content and that can save a
> > lot of money by using a system that's specifically built,
> > from the ground up, to faciliate extensive content reuse and
> > to faciliate creation of custom markup specialized to their
> > particular needs.
> >
> > Anyway, in spite of the possibility that the
> > information-mapping topic-based authoring approach may not
> > really be the right solution for many organizations
> > (especially those that aren't smart enough or careful enough
> > about avoiding all the possible pitfalls around it), it is
> > what a lot of them in the corporate tech-writing world seem
> > to want. And I suspect that many organizations who want that
> > were not using or considering DocBook to begin with; I'd
> > guess many had some legacy system based on authoring in, at
> > best, Framemaker -- and at worst, MS Word or RoboHelp or
> > whatever. A move by anybody away from that stuff and into any
> > XML and XSLT-based system is a win for all of us.
> >
> >   --Mike
> >
> >
> >
---------------------------------------------------------------------
> > 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
>
>


-- 
http://chris.chiasson.name/

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org