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

[steve sheppard]

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 >% ========
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20100913/64c620df/attachment.htm