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

[Soulliere, Robert]

Thanks Dan,

These are excellent tips and guidelines.

I will start cleaning up the sections I have converted or written.

Any help you could provide would be greatly appreciated.

Regards,
Robert
________________________________________
From: open-ils-documentation-bounces at list.georgialibraries.org [open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of Dan Scott [dan at coffeecode.net]
Sent: September 11, 2010 1:47 AM
To: Documentation discussion for Evergreen software
Subject: [OPEN-ILS-DOCUMENTATION] More semantic markup - good project for an    enthusiastic volunteer

Hey:

It's awesome to see so much happening with the documentation! I
created a Gitorious project for the Evergreen documentation over at
http://gitorious.org/evergreen-documentation if anyone is interested
in what I'm up to. I'll track Robert's repo, but hope to be able to
help out as time permits.

In a few of the sections I poked at, there's currently a lot of use of
<emphasis> tags; these are presentation-oriented rather than semantic.
For the purposes of generating HTML and PDF, that's definitely cool in
the short term, but over the longer term adopting more semantic markup
gives us the ability to have more fine-grained control over the
stylesheets and resulting output. It also makes it a bit easier to
focus on marking up _what_ the thing is rather than trying to remember
how it's supposed to look.

As a couple of quick examples, in one file <emphasis role="bold"> is
used to mark up usernames, commands, and file paths and file names;
<emphasis> is used to mark up command options (--foo) and commands
(/bin/foo); and double-quotes are used to denote commands. But DocBook
gives us ways to differentiate between all of those things:

  * <command> is used for command names
(http://www.docbook.org/tdg5/en/html/command.html)
  * <filename> is used for file paths and file names
(http://www.docbook.org/tdg5/en/html/filename.html)
  * <option> is used for command options
(http://www.docbook.org/tdg5/en/html/option.html)
  * <systemitem class="username"> is used for user names
(http://www.docbook.org/tdg5/en/html/systemitem.html)

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
have to give kudos to Sitka for their DocBook style guide
(http://coconut.pines.bclibrary.ca:21080/docbook/Style/draft/html/ch01.html)
- that kind of resource goes a long way towards keeping a single body
of documentation coherent.

Now, it's a bit hypocritical for a person like me who has been writing
primarily in AsciiDoc for the past year to suggest using more semantic
markup. I'm a big fan of getting things done, though, and the DIG is
definitely getting things done, so keep writing, first and foremost!
As the subject suggests, someone else can always come along and
enhance the markup, but pulling quality content together is job #1.
I'm willing to tackle one big chunk of content for a semantic cleanup;
I'm looking at the installation document, as I've been one of the
maintainers of that information in the wiki and am familiar with the
turf.

Ah, and one quick tip that might save you some pain: if you find
yourself with long <programlisting> or <screen> sections that contain
a lot of XML that you're changing < to &lt; to avoid XML errors, you
can wrap the whole thing in <![CDATA[ .... ]]> and the XML parser will
skip it. For example:

<programlisting language="xml">
<![CDATA[
<!-- Example of an app-specific setting override -->
<opensrf.persist>
  <app_settings>
  <dbfile>/tmp/persist.db</dbfile>
  </app_settings>
</opensrf.persist>
]]>
</programlisting>

It's a lot easier to copy and paste that as a writer than to copy and
paste it, then run a regular expression to escape the worrisome
characters!
_______________________________________________
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.