[OPEN-ILS-DOCUMENTATION] Circ docs (Re: Introductory Material for the Book of Evergreen)

[Soulliere, Robert]

Thanks Steve for looking into image naming and processing. Naming conventions will definitely be important and I think your convention to include the chapter name and then the specific image will work great.

I forgot that SITKA did provide a great set of image formatting guidelines in their docbook guide which they shared with the list a while back:
http://coconut.pines.bclibrary.ca:21080/docbook/Style/draft/html/ch02.html

In regards to the question about documentation image customization:
All documents and processing tools will be made available in a repository for free download but image customizations must be done from a local copy of the documentation. It is important to note that once you download and customize your local docbook documents, the good news is that you can edit and customize any of the documents any way you want. The bad news is that you will be working with a local copy and not benefit from updates to the docbook documents in the community repository unless you download the updates and reprocess your local copies again using the steps explained by Steve. I would expect that the documentation would be changing quite often, especially in the short run, so this could become tedious if you want to keep up to the updates. In my opinion, if you are going to make changes to processes or critical screen shot content, it might make sense. If you just want to plug in your logo, I would carefully calculate the benefits vs. time required for this process.

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: August 4, 2010 7:55 PM
To: open-ils-documentation at list.georgialibraries.org
Subject: [OPEN-ILS-DOCUMENTATION] Circ docs (Re: Introductory Material for      the Book of Evergreen)

I can see one way to do this --
Images are specified in DocBook source files by various tags and attributes with pathnames, filenames, image sizes and positions. If we name image files logically, refer to them properly, and stick to sizing standards when we create them, I think they can be sized to properly fit on a finished PDF page. For instance, I used some simple naming conventions for image files in our "1.6/media/" directory to complete the new "myaccount.xml" file, and it looks okay when rendered as a PDF file. Last night I experimented with image sizing/placement on the PDF page to get a feel for the process (using 'GIMP', the Gnu Image Manipulation Program). Yes, tedious but not impossible. Image manipulation can be a time sink.

If you could cleanly overlay/replace image files with your own versions, you could solve both the skinning and translation problems that Robert mentioned. The entire document package could be rebuilt on demand using your own local images like this:
1.  load our generic DocBook sources into a handy local directory tree;
2.  overlay/replace generic media with your own images;
3.  rebuild all the PDF files using our usual application of 'xsltproc' and 'fop'.

So, sounds possible, but assumes we establish and maintain image file naming and sizing conventions to ensure such overlays can work.
As Robert suggests, it may be best to leave images out entirely for now, or maybe replace them with zero-sized dummies as place-holders.
--Steve


> I was thinking about this, and I don't have any experience with
> DocBook, but is there a way people can upload sets of images that
> apply to their own installation? So when you use it to produce
> documentation, you'd specify a particular set of images?  That would
> make it a lot more generally useful.
>
> Just curious. I think "example of" makes sense, and would be a lot
> more efficient than trying to produce a lot of generic images.
>
> Sarah


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.