oXygen XML Editor

2. Principles

This section is based on a conversation on the docbook-apps list in May 2009. My thanks to Larry and Dean for letting me steal the ideas with glee.

Principle ideas. Firstly the storage of shared style information in a location accessible from a disk based setup, a CD based setup or a web site based setup. Next The collation of all graphics referenced from a document into a common place, within the document structure. Finally the uploading to the target of the collated material, both document based and any changes to the shared style information.

The style information is stored in /styles/docbook. A more sophisticated structure than this may be envisaged if versioning is required, other material is added etc, but for this demonstration only the docbook graphics will be stored there. Potential problems exist if multiple disks are used. On Linux, an alias can resolve this. Similarly if administrative privileges are not available to the author. It will work on both Windows and Linux. This means that the docbook build process needs to be told that its graphics are to be found at an absolute address of /styles/images. This is done in the customization layer, using the parameter


  
<xsl:param name="admon.graphics.path"   
               select="'/styles/docbook/images'"/>
<xsl:param name="callout.graphics.path" 
               select="'/styles/docbook/images/callouts'"/>

I am being a little more cautious and placing them under a docbook directory, since I also want to store other images here. A version number (again under docbook) would satisfy the most paranoid, in case the docbook image set changes. I believe it to be fairly stable, hence haven't bothered. I would then expect to see something like

annot-close.png  draft.png      next.png  tip.gif        up.svg
annot-open.png   home.gif       next.svg  tip.png        warning.gif
blank.png        home.png       note.gif  tip.svg        warning.png
callouts         home.svg       note.png  tip.tif        warning.svg
caution.gif      important.gif  note.svg  toc-blank.png  warning.tif
caution.png      important.png  note.tif  toc-minus.png
caution.svg      important.svg  prev.gif  toc-plus.png
caution.tif      important.tif  prev.png  up.gif
colorsvg         next.gif       prev.svg  up.png

... the above listing of files and directories under that hierarchy.

Other items suggested for this /styles directory are javascript, CSS files, icons, any favicon files, etc. I.e only those items which are common to many usages across the website, not those which are document specific, for which see below. Another option, for those dealing in multiple locales, might be language specific common text files, warnings etc. A possible directory layout is shown below, tailor yours to suit your needs

  /styles [/5.0/]    If versioning is used
    [locale/]        If locale used 
       de/
         de/
           images/   graphics specific to de_DE locale
           js/       Javascripts specific to de_DE locale
                     (the Javascript selects CSS based on 
                      browser and platform)
           styles/   CSS specific to de_DE locale 
                     (multiple, selected by Javascript)
       es/
       en/
       etc.
     favicon.ico     (this gets moved to the root of the Web 
                      exposure to make the icon work correctly)
     styles/         Common CSS stylesheets
     js/             Common javascript 
     docbook/
       images/       graphics that do not need localization 
                     (here is where the DocBook graphics are)  
          callouts/

This layout may seem complex, but for a basic docbook installation it could be as simple as:

  /styles
     docbook/
       images/       graphics that do not need localization 
                     (here is where the DocBook graphics are)  
         callouts/   Callout graphics

Which is much more manageable. Remember that having built this structure, it can be copied to the root of your local disk, to a CD, or even zipped and delivered over email to a customer. Once complete, it is a package that is common to your docbook documents.