The assembly does not require using topics. Conventional
DocBook elements like chapter and section can be used as resources. The
introduction of topic was to facilitate development of documentation for which the
topic-orientation can be helpful. The idea was to support reuse of
existing content while extending the model for other users.
Regards,
Larry Rowland
From: Kate.Wringe@sybase.com
[mailto:Kate.Wringe@sybase.com]
Sent: Tuesday, July 27, 2010 2:21 PM
To: rob.cavicchio@emc.com
Cc: bobs@sagehill.net; docbook@lists.oasis-open.org;
docbook-tc@lists.oasis-open.org
Subject: RE: [docbook] RE: Sections and topics
I am proposing
that the traditional DocBook schema allow for sections to appear at the same
level as chapters. That is, we allow a book to contain chapters or sections.
This would
allow "traditional" DocBook users who want and need to use chapters
to continue using them, while allowing other users the flexibility to work with
one less level in the hierarchy.
I'm not
suggesting that Modular DocBook be abandoned. I think that Modular DocBook has
some really useful features and will go a long way to helping DocBook users.
However, I am a bit confused as to why the assembly requires the use of the
Topic element (i.e., why couldn't the resources also accept chapters and
sections?). Will it be possible for users to easily share content between
Modular DocBook and the non-modular DocBook? Or is the intent that a team will
either write exclusively in Modular DocBook?
Thank you in
advance,
Kate
..........................................................................................................................................................................................................................
|
Kate
Wringe |
Tech Writer 2| Sybase
445 Wes Graham Way, Waterloo, ON, N2L 6R2 Canada | Tel: (519) 883-6838 | kate.wringe@sybase.com
| www.sybase.com
|
<rob.cavicchio@emc.com>
07/27/2010
10:32 AM
|
To
|
<Kate.Wringe@sybase.com>,
<bobs@sagehill.net>
|
cc
|
<docbook@lists.oasis-open.org>,
<docbook-tc@lists.oasis-open.org>
|
Subject
|
RE:
[docbook] RE: Sections and topics
|
|
I
have similar misgivings as Kate. I haven't seen the full proposal for modular
content (is it out there?), but I don't think that a whole new solution needs
to be designed. I actually like the linear structure of DocBook and the fact
that we don't need an entirely separate construct in order to sequence content
the way DITA does. I just think we need to tweak the definitions of the section
elements so that they are not tied to a particular level in the hierarchy and
can be reused in multiple contexts *if desired*. But I don't see that bursting
an integrated flow into tiny pieces in order to reuse one of them is
necessarily the best solution.
From:
Kate.Wringe@sybase.com [mailto:Kate.Wringe@sybase.com]
Sent: Tuesday, July 27, 2010 6:50 AM
To: Bob Stayton
Cc: docbook@lists.oasis-open.org; docbook-tc@lists.oasis-open.org;
Cavicchio, Rob
Subject: Re: [docbook] RE: Sections and topics
Hi Bob
Thank you for responding and providing more information about DocBook 5.1.
When I look at the description of Topic in the Unofficial DocBook 5.1
Definitive Guide, it appears as though Topic is more akin to chapter than
section in that you
cannot nest Topics within Topics
(http://www.docbook.org/tdg51/en/html/topic.html).
If I have a <Topic> that contains multiple <sections> can I convert
one or more of the sections into <Topics> and vice versa?
Thank you,
Kate
..........................................................................................................................................................................................................................
|
Kate
Wringe |
Tech Writer 2| Sybase
445 Wes Graham Way, Waterloo, ON, N2L 6R2 Canada | Tel: (519) 883-6838 |
kate.wringe@sybase.com | www.sybase.com
|
Bob
Stayton <bobs@sagehill.net>
07/26/2010
07:21 PM
|
To
|
<rob.cavicchio@emc.com>,
<Kate.Wringe@sybase.com>, <docbook-tc@lists.oasis-open.org>,
<docbook@lists.oasis-open.org>
|
cc
|
|
Subject
|
Re:
[docbook] RE: Sections and topics
|
|
This discussion is of great interest to the DocBook Technical Committee, as we
are
currently developing a DocBook solution for modular content. I believe
most of the
problems that have been mentioned here will be addressed.
The first step toward modular content was the introduction of the topic
element, which
will debut in DocBook 5.1. A topic element is meant as a standalone
module of
content, ready to be assembled into larger documents. Its structure is
similar to
section. The placement of topic within existing DocBook elements like
book and
chapter is not very important, as those will serve primarily as storage boxes
for
topic elements to be assembled.
The other addition in 5.1 will be the assembly element and its descendant
elements
like structure, resource and module. An assembly is similar to a DITA
map, in that it
contains a set of pointers that define the content and structure of the
assembled
document, but not the content itself. But a DocBook assembly is quite
different from
a DITA map in many ways.
One of the features will be an option to include content without including the
wrapper
element, which permits you to avoid duplicate ID values in an assembled
document.
Another is the renderas attribute, which allows you to convert a topic to a
chapter,
appendix, or section as needed, or vice-versa.
You can expect to soon see public announcements regarding release of the new
schemas
in beta form for testing, as well as some documentation and tools for
processing.
Bob Stayton
Sagehill Enterprises
bobs@sagehill.net
----- Original Message -----
From: <rob.cavicchio@emc.com>
To: <Kate.Wringe@sybase.com>; <docbook-tc@lists.oasis-open.org>;
<docbook@lists.oasis-open.org>
Sent: Monday, July 26, 2010 1:50 PM
Subject: [docbook] RE: Sections and topics
Kate.Wringe@sybase.com [mailto:Kate.Wringe@sybase.com] wrote:
>
Here's the problem that I am increasingly running into: We have a
<section> in one
book that we want to reuse as a <chapter> in another book and vice versa.
<
This does not solve your immediate issue, but I think that the time has really
come to
allow <section> at any level. The whole chapter vs. section thing is very
static-book-oriented and does not lend itself well to information reuse.
*************************
Rob Cavicchio
Principal Technical Writer & Information Architect
EMC Captiva
Information Intelligence Group
EMC Corporation
3721 Valley Centre Drive, Ste 200
San Diego, CA 92130
P: (858) 320-1208
F: (858) 320-1010
E: rob.cavicchio@emc.com
The opinions expressed here are my personal opinions. Content published here is
not
read or approved in advance by EMC and does not necessarily reflect the views and
opinions of EMC.
---------------------------------------------------------------------
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