OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook] Easiest way to define ProductName variable?

But, to be honest, for the very large, thousand-page DocBook doc set I maintain, we found that the profiling overhead for simple variable substitution put far too much of a burden on our doc build times, and we gave up on it. We now use profiling only to generate two output document types from a single source. 

For variables, we ended up with a simple Perl script substitution that runs on a copy of our doc source files. Thus, a simplified version of our doc build script is something like this:
  • Delete any temp-source directory from a previous build
  • rsync doc-source to temp-source
  • Run the Perl substitution script on all files in temp-source
  • Run java —{saxon} on each temp-source/<book> file in turn

Profiling does not require the use of XML entities. That is one possible implementation, but the recommended way is to just place alternate passages adjacent to each other in the DocBook source file, each with a different attribute setting. Then select between them at build time by specifying a runtime parameter. For two profiled options, you would transform your document twice; for three options, three transformations, and so on.

For the example on the cited page, you would transform with profile.os=“win” and again with profile.os=“linux”. 

Hi, Mary.

The profiling chapter provides great information, but I was initially missing a simple use case for implementing a ProductName variable, which appears  in our XML source as: &ProductName;

The part I was missing was putting the ProductName entity in the header of our XML files (after <?xml version.. and the DocBook schema declarations) as follows:

<!DOCTYPE section [
<!ENTITY ProductName '<phrase condition="Mobile">Mobile-specific Product</phrase><phrase condition="Buyer">Buyer-specific Product</phrase><phrase condition="Seller">Seller-specific Product</phrase>'>

We then indicate the desired product name condition in our oXygen transform scenario by setting the profile.condition parameter to a one of our condition values, such as Mobile. Once the transform then replaces &ProductName; with the desired product name for the target help system.

We also show or hide any product-specific content using audience attributes, such as <para audience="seller"> and then set the profile.audience parameter in our oXygen transform scenario to the desired value.

Perhaps others on this list can let us know a better approach.


--Jared Crawford
Pasadena CA USA

On Friday, January 23, 2015 1:57 PM, Barton Wright <ordinant@gmail.com> wrote:

Hi Mary,

The keyword you’re looking for is profiling. See

Best of luck with DocBook. Ask anything anytime.

> I'm brand new to docbooks, having inherited it through this job I started. Now that I have my build scripts working, I'm in good shape, except that I've not yet figured out how best to achieve this simple goal: create a variable (such as ProductName) that can resolve to one of several values based on whether it's a corporate or an OEM build target.
> I must not be searching on the correct words to find out how this is typically done!
> Gratefully,
> Mary

To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]