Fixes for problems with figures in documentation
------------------------------------------------
Key: DERBY-5148
URL: https://issues.apache.org/jira/browse/DERBY-5148
Project: Derby
Issue Type: Bug
Components: Documentation
Affects Versions: 10.7.1.1
Reporter: Kim Haase
Assignee: Kim Haase
Priority: Minor
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"/>
</copy>
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
expanse="column"
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.
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
