Re: [docbook] Sections and topics

Hi Kate,

You should investigate olinks if you want to link 
across books or use modular source files.  See:

 

http://www.sagehill.net/docbookxsl/Olinking.html

 

Bob Stayton
Sagehill Enterprises


 

 

  
----- Original Message ----- 

  
From: 
   

  
To: Rowland, Larry 

  
Cc:  ; 
  DocBook Technical Committee 
  

  
Sent: Wednesday, July 28, 2010 6:10 
  AM

  
Subject: RE: [docbook] Sections and 
  topics

  

Thanks Larry! 
I'll look into this idea. 
At first glance, I'm a bit concerned that the 
  <set> element does not contain the <article> element. We need to 
  be able to link across books 
and I 
  thought that the <set> element played a large role in this. 
  

Thanks again, 
Kate 

.......................................................................................................................................................................................................................... 
  

  
    
    

      
      Kate Wringe | Tech 
        Writer 2| Sybase
445 Wes Graham Way, Waterloo, ON, N2L 6R2 Canada | 
        Tel: (519) 883-6838 |  | www.sybase.com 
    

  
 

  
    
    

      "Rowland, Larry" 
        <> 
        
07/27/2010 05:46 PM 

      
        
          
          

            
              
To

            "" <>, 
              DocBook Technical Committee 
              <>, 
              "" 
              <> 
          

            
              
cc

            
          

            
              
Subject

            RE: [docbook] Sections 
              and topics

        
          
          

            
            

I know that you have already had a good deal 
  of response to this, but you asked about potential solutions and there is one 
  I haven’t seen mentioned. 
  
We sometimes 
  have requirements for short documents and have set up the transforms to use an 
  article as the root element for this type of document.  If you need a 
  title page more closely resembling a book than an article (which has a much 
  simpler title page by default) and want to preserve both the traditional 
  article title page and a book-style title page for articles, you can use a 
  role attribute on the articles that you want processed like a book to indicate 
  that.  As an alternative, you can  have the transform check to see 
  if the article is the root element and decide what type of title page to use 
  based on that characteristic.  Articles allow you to use the section 
  elements directly as children of the root element instead of having to include 
  the chapter element in the hierarchy.  This would meet your requirement 
  without needing to change the DocBook schema and can be done now rather than 
  having to wait for DocBook to change. 
  
Regards, 
Larry 
  Rowland 
  
  
From:  
  [mailto:] 
Sent: Monday, July 26, 2010 1:26 
  PM
To: DocBook Technical Committee; 
  
Subject: [docbook] Sections and 
  topics 
  

Hello, 
  

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. 

For 
  example, in book A, there is section about using a tool with product A and in 
  book B, we need to include the same information, but it must exist at the 
  chapter level. 
Currently, in order to solve this problem, in Book A we 
  create a <section> that contains the information and we xinclude this 
  <section> into an essentially empty <chapter> element in Book B. 
  As a result, our TOC becomes bloated and we end up with these funny chapter 
  pages (in HTML Help) that only contain vague sentences followed by links to 
  sections. 

It would be easier for us if the book structure allowed 
  the <section> element to exist at the same level as the <chapter> 
  element. 
So that, for example, the following would be valid: 
<book><title>titletext</title> 
  
       <section>text.... 
      
   </section> 
</book> 
  

I understand that the section element 
  is supposed to contain information that is a section of something else and so 
  the committee has been reluctant to see the <section> as a direct 
  element of the <book> element. I had hoped that the <topic> 
  element in modular DocBook would offer a better alternative. Unfortunately, 
  from what I understand, you 
  
cannot have a topic embedded within a 
  topic. So, even if we switched to using topics, we'd have the same problem as 
  described above. 

Apologies if I am bringing up a subject that has already 
  been addressed. Any suggestions as to how to solve this problem would be 
  greatly appreciated. 
  

Thank you, 
Kate 

.......................................................................................................................................................................................................................... 
  

  
    
    

      
      Kate Wringe | Tech 
        Writer 2| Sybase
445 Wes Graham Way, Waterloo, ON, N2L 6R2 Canada | 
        Tel: (519) 883-6838 |  | www.sybase.com