More about DocBook

1. A first step : a skeleton according to the official table of contents of the Java technical report

   1. XML file
      
   2. XHTML stylesheet
   3. CSS file
      
   4. FO style sheet
   5. PDF rendering
      
   
   

2. Additional remarks

   1. About images

      Reading the DocBook documentation leads to believing that a double-barrelled specification like
      
           <mediaobject>
        <imageobject condition="web">
            <imagedata fileref="someImageFile.xxx" />
        </imageobject>
        <imageobject condition="print">
            <imagedata fileref="otherImageFile.yyy" scalefit="1"/>
        </imageobject>
    </mediaobject>
      
      will result in 2 different source files being used according to the chosen target.
      In particular, choosing otherImageFile with reduced dimensions would help in insuring that the image actually fit in the printed page.
      As was observed with the About DocBook example, this did not seem to work...
      
      Indeed, the actual working of the standard stylesheets do not conform to these expectations.
      Only the first file (someImageFile) is used in both cases, as is clearly demonstrated by inspecting the generated xhtml and fo files :
      
      • xhtml
      <div class="mediaobject">
        <img src="someImageFile.xxx" />
      </div>
        
        
      • fo
      <fo:block id="idp28445200">
          <fo:external-graphic src="url(someImageFile.xxx)"
             width="auto" height="auto" content-width="auto" content-height="auto"/>
      </fo:block>
        
      
      The distinction between condition="web" and condition="print" being useless, it is best to simplfy to
      
         <mediaobject>
        <imageobject>
            <imagedata fileref="someImageFile.xxx" />
        </imageobject>
    </mediaobject>
      
      Therefore take care to use image files that are small enough to fit in your pdf page !
      Observe that the space that is taken up on the printed page is much larger you would expect (compare the html and pdf renderings of the same image).
      
      

   2. About code snippets with the <programlisting> tag

      Since the management of linebreaks is inhibited for <programlisting> contents, long lines will be displayed as such.
      With html rendering, horizontal scrolling will allow complete access, not so with the fixed width of the printed page !
      See instances on the About DocBook example.
      
      There is no hope of setting up a linebreaking device which would produce a legible result :
      indeed, producing a legible printout of code amounts to understanding the code (at least superficially).
      So forget it and take care to format your code snippets in uch a way that tthey remain legible when printed.