Docbook: generic technical document published for multiple clients

[David Montgomery]

Hi,

Our company provides ASP services to multiple government agencies. These
agencies in turn provide our ASP services to the general public through
their web portals. As part of our service we need to provide end-user
documentation for the general public to use our ASP tools, providing
really simple to understand step-by-step instruction with lots and lots
of picture examples.

As part of my project to create this documentation, I managed to stumble
across Docbook, and it looks like a great way for us to maintain our end-
user docs.

My last remaining obstacle to overcome however is this:

We have several different government agencies as clients. Each agency
would like to have the end-user documentation customized to refer to
their agency specifically. Example: if both the City of Anaheim City
Clerk's office is our client and the Santa Clara County Registrar of
Voters is also our client, then my documentation would need to change
from this

"For more information, contact the City Clerk's office at 909-555-1212
during our normal business hours from 8AM to 5PM"

to

"For more information, contact the Registrar of Voter's office at 408-
555-1212 during our normal business hours from 9AM to 5PM"

For the vast majority of the documentation, the content of the document
will be identical, but for small sections, I will need to substitute
content specific to a particular government agency.

I have considered building a XSL stylesheet that does nothing more than
taking a single "master" docbook instance, and producing subsidiary
output docbook instances, one for each of our agency clients, then using
the "normal Docbook" html and PDF output stylesheets to generate the
final output(s) for each agency.

Does this sound reasonable? Is there some other more obvious way to
customize docbook documents? Is there a way to use replaceable
"parameters " within a docbook instance? This is where my lack of XSL
knowledge really hurts...

Any advice would be appreciated.

Best Regards,

David Montgomery

[Peter Flynn]

David Montgomery wrote:

Hi,

Our company provides ASP services to multiple government agencies. These
agencies in turn provide our ASP services to the general public through
their web portals. As part of our service we need to provide end-user
documentation for the general public to use our ASP tools, providing
really simple to understand step-by-step instruction with lots and lots
of picture examples.

As part of my project to create this documentation, I managed to stumble
across Docbook, and it looks like a great way for us to maintain our end-
user docs.

My last remaining obstacle to overcome however is this:

We have several different government agencies as clients. Each agency
would like to have the end-user documentation customized to refer to
their agency specifically. Example: if both the City of Anaheim City
Clerk's office is our client and the Santa Clara County Registrar of
Voters is also our client, then my documentation would need to change
from this

"For more information, contact the City Clerk's office at 909-555-1212
during our normal business hours from 8AM to 5PM"

to

"For more information, contact the Registrar of Voter's office at 408-
555-1212 during our normal business hours from 9AM to 5PM"

For the vast majority of the documentation, the content of the document
will be identical, but for small sections, I will need to substitute
content specific to a particular government agency.
These are known as "effectivities" , and are usually handled in DocBook
with the attributes arch, condition, conformance, os, revision, security,
userlevel, and vendor. You can add your own if you need, making a
declaration in the local.effectivi ty.attrib parameter entity, eg

<?xml version="1.0"?>
<!DOCTYPE article SYSTEM "/dtds/docbook/docbookx.dtd" [
<!ENTITY % local.effectivi ty.attrib "agency ENTITIES #IMPLIED">
<!NOTATION text SYSTEM "plaintext" >
<!ENTITY anaheim SYSTEM "ana.txt" NDATA text>
<!ENTITY santa-clara SYSTEM "sc.txt" NDATA text>
]>
<article>
<para agency="anaheim santa-clara"></para>
</article>

Making the values ENTITIES ensures (by validation) that only predefined
values can be used.

Your XSLT stylesheet can now access these values in processing, and
make suitable variations to the output.
I have considered building a XSL stylesheet that does nothing more than
taking a single "master" docbook instance, and producing subsidiary
output docbook instances, one for each of our agency clients, then using
the "normal Docbook" html and PDF output stylesheets to generate the
final output(s) for each agency.

The above method automates the process and lets you use a single XSL[T]
stylesheet for any of the document types.

///Peter
--
"The cat in the box is both a wave and a particle"
-- Terry Pratchett, introducing quantum physics in _The Authentic Cat_