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

[Soulliere, Robert]

Thanks Steve,

Keeping style notes will be extremely important.

I create a directory for the stylesheets I have been working with:
http://github.com/rsoulliere/Evergreen-DocBook/tree/master/stylesheets/
These stylesheets are actually slightly modified stylesheets from SITKA. We definitely need to make a note of that in our acknowledgements and credits section. I have been experimenting with them for a while on the test server but should have shared them a while ago. I think they already have formatting for links in the PDF version (green underlined). Steve, maybe you could download the styles sheets and experiment on your server?
-the version of the base docbook stylesheets might be  outdated (docbook-xsl-1.75.2) I haven't had a chance to update them.

Note that I placed this outside of the 1.6 directory. It might be a good idea to keep stylesheets and notes outside of the version directories since these notes and style sheets will be outside of the content versions. e.g. The  same style notes will be important for version 1.6 and 2.0. I wonder if we could name the "docbook" directory "style notes" or "processing notes"

The structure could look like:

Evergreen DocBook
- Stylesheets
- tools  (e.g. scripts for processing and autodoc etc...)
- style notes or processing notes?
- 1.6
- 2.0

Not sure if we need a folder for called "content" to store the version subfolders? What do repository orgainzation experts think?

If you have any questions, let me know.

Thanks,
Robert



________________________________________
From: open-ils-documentation-bounces at list.georgialibraries.org [open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of steve sheppard [ssheps at gmail.com]
Sent: September 2, 2010 2:06 PM
To: open-ils-documentation at list.georgialibraries.org
Subject: [OPEN-ILS-DOCUMENTATION] documenting minor changes to our toolchain

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

This E-mail contains privileged and confidential information intended
only for the individual or entity named in the message.  If the reader
of this message is not the intended recipient, or the agent responsible
to deliver it to the intended recipient, you are hereby notified that
any review, dissemination, distribution or copying of this communication
is prohibited.  If this communication was received in error, please
notify the sender by reply E-mail immediately, and delete and destroy
the original message.