Re: DOCBOOK: version control

[Bob Stayton <bobs at sco dot COM>]

> From: Norman Walsh <ndw@nwalsh.com>
> 
> / Jonathan Riddell <jr050@jriddell.org> was heard to say:
> | I have a book which has 1995, 1996 etc editions and it would be good to
> | keep these editions in the one file, with the text from one edition
> | outputted at any one time.
> | 
> | Is there an easy way of doing this?
> 
> Easy? Probably not. But it could conceivably be done with the
> effectivity markup:
> 
>   <para revision="1995">...</para>
>   <para revision="1996">...</para>
>   <para>Some common text <phrase revision="1995">foo</phrase><phrase
>         revision="1996">bar</phrase>...</para>
> 
> But a version control system like CVS is probably a better answer.

In the case of sequential editions, it isn't clear
why you would want all the editions in the
same file.  A revision control system like CVS could
retain older editions and provide a basis for
the next edition, as Norm says.

The effectivity tags are usually needed when you have
two active versions being developed at the same time.
If most of the text between the two versions is the
same, then keeping them both in the same file helps
keep them in synch.  Then you can mark only the
different parts with effectivity attributes like revision
or role.

To generate one or the other version, you need to
customize the stylesheets to look at the value of
that attribute (if it exists on an element) and
select only those that match what you want.
This is not a built-in feature of the stylesheets,
I don't think.  Are you using XSL or DSSSL?

One other thing to watch out for is to avoid putting
effectivity attributes on elements you cross reference to.
That is, elements that have an ID attribute that an xref or
link points to.  When the file is parsed, the cross
references appear to resolve through ID/IDREF, but when the
stylesheet is applied, the cross reference target might not
be included in the output, leaving broken links.
Also, your table of contents
may list sections that are not actually present in the
output.

Rather than customize the stylesheets to handle all
this, I would create a XSLT stylesheet to use as a
prefilter to select only the elements you want for
a particular version, that is, all the elements without
a revision attribute and those that have the right value.
Then apply the stylesheets to the output from the prefilter.
A Makefile can manage the process chain.

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

------------------------------------------------------------------
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: docbook-request@lists.oasis-open.org