|
Hi,
I think perhaps it was premature of me to notify
the list about the modular DocBook work before it was ready to be
released. I'm afraid people are getting the wrong impression due to the
lack of information. My brief summary did not do justice to the actual
work. In fact, an assembly will accept chapters and sections as well as
topics. You don't have to use topics at all, but they are a useful
semantic if you are creating such modular content from scratch.
I understand that Norm will soon be releasing the
actual beta schemas, and I think those will answer many of the questions my
posting raised.
----- Original Message -----
Sent: Tuesday, July 27, 2010 1:21
PM
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
|