[OPEN-ILS-DOCUMENTATION] documenting minor changes to our toolchain

[steve sheppard]

I thought it would be useful to establish a place to capture any
programmatic changes to our DocBook toolchain, so I created a new repository
directory "docbook". We can use it to track suggestions or adjustments.

I didn't want to change .XML files in the repository; I just wanted to
render parts of them a little differently. Specifically, I wanted all
<link>s within a document to be easily visually identifiable, similar to the
way links are rendered within an HTML document. So, as a first try, I made a
few experimental adjustments to my own DocBook distribution to adjust the
rendering of certain markup in the PDF file (the changes don't change the
HTML file created, just the PDF file). That worked well so, perhaps
unwisely, I got caught up in making other changes; I tried to render
<figure>s in a different background color to make them easier to find. That
also worked well. I outline the adjustment in the new file "docbook/README".

So far as I know (I tried, believe me), it isn't possible to make these
changes on-the-fly by passing "--stringparam" parameters to our "xsltproc"
tool. Instead, I just modified one of the prime files used by "xsltproc" to
adjust the rendering of certain tags in the PDF output file. My changes may
be naive; XSLT and DocBook gurus are welcome to point out better ways to do
this. Anyhow, the PDF file generated for my section "Server-Side
Installation" now looks *so* much better.

Changes include the following:
-----------------------------
1. Motivated by my realization that you can't easily find <link>s to other
chapters or documents within the PDF file. Now all links are rendered in
blue, underlined italic text for easy identification.

2. Motivated by my desire to draw attention to figures or diagrams, which
were hard to pick out of the surrounding text. Now all figures are rendered
in small text (75% the size of normal text), and a background color is added
to the figure to differentiate it from the surrounding document.

3. Motivated by wanting to see if I could do it :). Now all sections within
an <abstract/> tag are rendered in italic font.

Cheers!
--Steve
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20100902/f33c4017/attachment.htm