DOCBOOK-APPS: Re: DOCBOOK: Indicating Edits

[Michael Smith <smith@xml-doc.org>]

[moved here from docbook@lists.oasis-open.org]

Norman Walsh <ndw@nwalsh.com> writes:

> / Jamie Smedsmo <jsmedsmo@gis.umn.edu> was heard to say:
> | it and added text another color).  Are there any tags in DocBook that indicate
> | edits or
> | lead to this type of formatting?  What do other people do for editing?
> 
> DocBook provides a common attribute, RevisionFlag, for this purpose, but
> maintaining it by hand (without good tools support) is tedious. Instead,
> I make changes then use diffmk to build the diff'd version:
> 
>  http://www.sun.com/xml/developers/diffmk/

I starting using diffmk only recently, but wish I'd had it a long time
ago -- highly recommend it to anybody who hasn't tried it yet.

It allows you to do exactly what Jamie describes: show deletes in
strike-through, added text in one color, changed text in another.

For anybody who tries it: I don't think the docs say it, but easy way
to transform the diff'd XML to HTML and get colors and strikethrough
is: instead of docbook.xsl/chunk.xsl, or your XSL customization layer,
process with changebars.xsl (standard in XSL stylesheet distribution).

changebars.xsl transforms the revisionflag="" attributes to class=""
on <div> and <span> elements in the HTML, and to handle the style
information, embeds a CSS stylesheet, e.g.:

  <style type="text/css">
    div.added    { background-color: yellow; }
    div.deleted  { text-decoration: line-through;
                   background-color: #FF7F7F; }
    ...

So use changebars.xsl and you don't have to do any customizing at all.

Once you've got everything set up, generating a color-coded diff
document is just a two-step process that takes only a few seconds:

  1. Run "diffmk -docytpe docbook <old.xml> <new.xml> <diffs.xml>"
  2. Run XSLT engine on diffs.xml w/ changebars.xsl to get diffs.html

But Jamie also mentioned:

> I am trying to edit documents that other people have written with
> DocBook SGML.

diffmk is XML-based (uses XML::DOM and XML::Parser), so if you want to
use it with SGML docs, you might first need to normalize and XML-ify
them -- that is, make sure they're also well-formed XML.