Re: [docbook] Marking up generated content

[Bob Stayton <bobs@sco.com>]

On Tue, Nov 25, 2003 at 11:21:36PM +0100, Christian Roth wrote:
> Hi,
> 
> I'm looking for a good way to markup generated content, i.e. sections
> that get updated resp. replaced just before publication by an additional
> processing step. Things likely to get automatically replaced are the
> current date, a processor identification or the geographical location of
> the publishing machine.
> 
> In some pseudo XML, this would look like:
> 
> <para>
>   Signed <gentext type="Location.City">Munich</gentext>, 
>   <gentext type="Date.Long">November 25, 2003</gentext>: Christian
> </para>
> <para>
>   (Processed by <gentext type="Processor.Name">XalanJ 2.5.2</gentext> 
>   at <gentext type="Time.Short">23:10</gentext>)
> </para>
> 
> In lieu of the <gentext> elements in the above, should I simply use
> <phrase> with a custom role attribute? <replaceable> seems to have
> different semantics and therefore seems not to be a good choice here.
> 
> I'm also looking at making it obvious to the author of the "template"
> DocBook document that manual changes to the contents of the <gentext>
> elements will be discarded at publishing time, so he better not wasted
> any time on doing it.
> 
> Are there any general rules or best practices for accomplishing this?

If you have a limited number of named generated items, then
another approach is to use entities for your dynamic text.

>   Signed &Location.City;, 
>   &Date.Long;: Christian

The entity declarations can be contained in a separate
file.  The entities file would be referenced in your DOCTYPE:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";
[
<!ENTITY % myents SYSTEM "myproject.ent" >
%myents;
]>

Then update the entity declarations in myproject.ent
just prior to processing your document.

I think it would be clear to an author that they
cannot make manual changes to such entities. 

Some authoring tools will expand such entity references
so they look like text while editing, but they
cannot be edited.
-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com