[OPEN-ILS-DOCUMENTATION] More semantic markup - good project for an enthusiastic volunteer

[jeremy]

I'm glad to hear the Sitka style guide is helpful beyond Sitka's
conversion project.  I should mention again that the guide was written
with Sitka xsl stylesheet customizations in mind.  This is particularly
true for image scaling where the syntax is simplified but non-standard:

http://coconut.pines.bclibrary.ca:21080/docbook/Style/draft/html/ch02.html

The 75% scaling of images in pdf output where scalefit="0" is hard-coded
into the stylesheets (see evergreen_fo_graphics.xsl, line 168).  There
are also heavy-handed modifications to evergreen_xhtml_graphics.xsl:
lines 153-163 are commented out so that if imagedata has the width
attribute, in html output the image will be sized to the
default.image.width specified in evergreen_xhtml.xsl.

Since Robert is also using adapted versions of Sitka stylesheets this
should not be a problem for DIG at the moment, but it may be worth
changing in the future.  I am willing to strip the style guide of Sitka
references and add it to the git repository if the community would like
to build upon it for an Evergreen DocBook style guide (probably not for
a few weeks, though). Let me know if there's interest in this. 

Thanks,
Jeremy

-- 
Jeremy Buhler
Trainer/Help Desk Specialist
Sitka Evergreen Implementation
jbuhler at sitka.bclibraries.ca

On Mon, 2010-09-13 at 12:03 -0400, steve sheppard wrote:
> Thank you, Dan, for the suggestions on semantic markup.
> 
> I reworked my document "ServersideInstallation.xml" over the weekend
> using your comments and Sitka's DocBook style guide. I've gotta say,
> the PDF doc looks a *lot* more professional now with the typography
> properly rendered. I will stick with this style guide from now on.
> 
> Thanks, Sitka folk, for a lucid and workable guide!
> 
> 
> There was one glitch that I haven't yet resolved:
> 
> > [...]In other areas, values that users are expected to input are not
> marked
> > up at all - but could be marked up as <userinput>. <screen> sections
> > could often be broken down into <prompt> and <userinput> sections.
> [...]
> 
> I tried your suggestion of using <prompt> and <userinput> to mark up
> text in <screen> sections, but it didn't work out. With this approach
> line feeds and carriage returns are lost and lines are unreadably
> merged. I tried other combos of <screen>, <prompt/> and <userinput/>
> without luck.
> I'll keep working on it since this will be a common and widespread
> issue in all docs that deal with transcriptions of command-line stuff.
> 
> Try running the included example below through your tool chain to see
> what I mean.
> 
> Cheers!
> --Steve
> 
> ======== %< SNIP-SNIP >% ========
> <figure>
> <title>Commands to configure OpenSRF</title>
> <screen>
> <prompt>$</prompt> <userinput>su - opensrf</userinput>
> <prompt>$</prompt>
> <userinput>cd /home/opensrf/OpenSRF-1.2.2</userinput>
> <prompt>$</prompt> <userinput>./configure --prefix=/openils
> --sysconfdir=/openils/conf</userinput>
> <prompt>$</prompt> <userinput>make</userinput>
> ...
> </screen>
> </figure>
> 
> <para/><para/><para/>
> 
> <figure>
> <title>Commands to configure OpenSRF</title>
> <screen>
> $ su - opensrf
> $ cd /home/opensrf/OpenSRF-1.2.2
> $ ./configure --prefix=/openils --sysconfdir=/openils/conf
> $ make
> ...
> </screen>
> </figure>
> ======== %< SNIP-SNIP >% ========
> 
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation