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: [email protected] [mailto:[email protected]] Sent: Tuesday, July 27, 2010 2:21 PM To: [email protected] Cc: [email protected]; [email protected]; [email protected] 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 | [email protected] | www.sybase.com <[email protected]> 07/27/2010 10:32 AM To <[email protected]>, <[email protected]> cc <[email protected]>, <[email protected]> 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: [email protected] [mailto:[email protected]] Sent: Tuesday, July 27, 2010 6:50 AM To: Bob Stayton Cc: [email protected]; [email protected]; 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 | [email protected] | www.sybase.com Bob Stayton <[email protected]> 07/26/2010 07:21 PM To <[email protected]>, <[email protected]>, <[email protected]>, <[email protected]> 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 [email protected] ----- Original Message ----- From: <[email protected]> To: <[email protected]>; <[email protected]>; <[email protected]> Sent: Monday, July 26, 2010 1:50 PM Subject: [docbook] RE: Sections and topics [email protected] [mailto:[email protected]] 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: [email protected] 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: [email protected] For additional commands, e-mail: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
