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

[Soulliere, Robert]

Thanks Jeremy,

That would be great!


Robert

________________________________________
From: open-ils-documentation-bounces at list.georgialibraries.org [open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of jeremy [jeremy.buhler at gmail.com]
Sent: September 13, 2010 4:17 PM
To: Documentation discussion for Evergreen software
Subject: Re: [OPEN-ILS-DOCUMENTATION] More semantic markup - good project for an enthusiastic volunteer

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


_______________________________________________
OPEN-ILS-DOCUMENTATION mailing list
OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation

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.