Uploaded image for project: 'Derby'
  1. Derby
  2. DERBY-5148

Fixes for problems with figures in documentation



    • Bug
    • Status: Closed
    • Minor
    • Resolution: Fixed
    • Documentation
    • None


      There are several problems with figures in the documentation. (Only the Tuning and Developer's Guides have figures.)

      1) The build.xml file doesn't copy over the GIF files, only the JPEG files:

      <copy todir="${dita.output.dir}/${manual.name}">
      <fileset dir="${dita.src.dir}/${manual.name}" includes="*.jpg"/>

      This means that in the output of a clean build, only the one-page HTML and PDF output (which use the JPEG) look correct; in the frames HTML output, the alt text appears but the figures don't. The trunk build on the Derby web site has the GIF files, but not because the build.xml file put them there.

      If the line is changed to the following, the output directory contains the GIF files:

      <fileset dir="${dita.src.dir}/${manual.name}" includes=".jpg,.gif"/>

      2) The Tuning Guide source file ctundepth32379.dita (Using the statement cache) has two figures, one of which specifies its expanse attribute as "page" instead of "column". This causes the caption to appear at the far left side of the page in the one-page HTML and PDF. Changing the expanse value to "column", and also removing the align="center" attribute from the <image> tag, creates reasonable-looking output in the HTML.

      The output of the second figure (stmt_os.jpg) is very large in the PDF (see pages 19-20 of http://db.apache.org/derby/docs/dev/tuning/tuningderby.pdf). For some reason I have a version of that file in one of my workspaces that has the same height-width dimensions but fewer bytes (16800 bytes vs. 57415). If I use that, the PDF output fits in the column.

      3) The Developer's Guide source file cdevdeploy855368.dita (Embedded deployment application overview), unlike the other DITA source files that contain figures, does not specify the attribute


      for its two <fig> elements. Putting this in for consistency makes sense.

      Two figures in the Developer's Guide PDF are also way too big (Figure 4 and Figure 6, dead.jpg and itserv_os.jpg). In fact, several figures in the devguide are too big in the PDF, though only Figures 4 and 6 overhang the margin. The big ones are much larger than the others:

      rw-rw-r- 1 chaase javaeast 24570 Mar 26 2008 appauth_os.jpg
      rw-rw-r- 1 chaase javaeast 38266 Mar 26 2008 dead.jpg
      rw-rw-r- 1 chaase javaeast 29547 Mar 26 2008 itserv_os.jpg
      rw-rw-r- 1 chaase javaeast 32084 Mar 26 2008 lockwa1.jpg
      rw-rw-r- 1 chaase javaeast 32669 Mar 26 2008 lockwa2.jpg
      rw-rw-r- 1 chaase javaeast 39174 Mar 26 2008 lockwa3.jpg

      These are the smaller ones –

      rw-rw-r- 1 chaase javaeast 8473 Mar 26 2008 authentic_os.jpg
      rw-rw-r- 1 chaase javaeast 9256 Mar 26 2008 dbcont.jpg
      rw-rw-r- 1 chaase javaeast 16131 Mar 26 2008 edeploy_os.jpg
      rw-rw-r- 1 chaase javaeast 8113 Mar 26 2008 embed_os.jpg
      rw-rw-r- 1 chaase javaeast 5207 Mar 26 2008 security2_os.jpg
      rw-rw-r- 1 chaase javaeast 13452 Mar 26 2008 security_os.jpg
      rw-rw-r- 1 chaase javaeast 15520 Mar 26 2008 system_os.jpg

      I find that opening these large JPEG files in MS Paint and then saving them again as JPEG shrinks them so that they look correct in the PDF and just the same in the one-page HTML:

      rw-rw-r- 1 chaase javaeast 10037 Mar 22 16:56 appauth_os.jpg
      rw-rw-r- 1 chaase javaeast 14472 Mar 22 16:57 dead.jpg
      rw-rw-r- 1 chaase javaeast 11275 Mar 22 16:58 itserv_os.jpg
      rw-rw-r- 1 chaase javaeast 11379 Mar 22 16:26 lockwa1.jpg
      rw-rw-r- 1 chaase javaeast 11468 Mar 22 16:50 lockwa2.jpg
      rw-rw-r- 1 chaase javaeast 13519 Mar 22 16:59 lockwa3.jpg

      I will file a patch for these modifications shortly. I'd like to commit the patch in a day or so, so please let me know if you see any problems with it.


        1. DERBY-5148.zip
          38 kB
          Camilla Haase
        2. DERBY-5148.stat
          0.3 kB
          Camilla Haase
        3. DERBY-5148.diff
          4 kB
          Camilla Haase



            chaase3 Camilla Haase
            chaase3 Camilla Haase
            0 Vote for this issue
            0 Start watching this issue