[LONG] Change bars in policy docs (hence all debiandoc docs)

[Aaron Van Couwenberghe <avancouw@calpoly.edu>]

Hi all -

  You might remember that a while back, I said I would look into writing a
script that produced a policy document with change bars (highlighting
additions and omissions, with context yanking). It's been a while, and I
just now looked into it ;). I have two options as far as how to go about it,
but I need help choosing the right path.

  First, I'm going to need to keep a history of policy revision diffs. these
will of course be diffs between the SGML's. The idea I have is mind is a
script that takes an 'initial' and 'final' revision, and patches the
existing document down, yielding two more documents (of the specified
revisions). Next I need a diff between these two, so I diff them. Now I've
got:

policy-x.x.x.x.sgml
policy-y.y.y.y.sgml
policy-x.x.x.x-y.y.y.y.sgml.diff

Here is where the dilemma begins. the output as I imagine it will be
stylized HTML, with red hyperlinks being policy additions, and blue
hyperlinks being omissions. The hyperlinks themselves will yank context in
and out, the 'out-of-context' doc giving a rundown of changes in section
numbers, and showing only as much context as is contained in the diff.

There are two ways to get here. an ugly hack with html output that will need
maintainence regularly, and modification of the DebianDoc sgml DTD. the
problem is that I'm not quite sure if the DTD mods will work.

approach 1: Instead of diffing the SGML sources, translate to HTML and deal
purely with the HTML. This would be a PITA, but a little more straightforward.
Output two sets of HTML, diff them, use the diff to add change bars to the
higher revision HTML set, then translate the diff directly into HTML. The
context html and out-of-context html would have tags all over the place
within one another to allow hyperlinking to look like 'yaking context in and
out'.

approach 2: Add <addition></addition> <omission></omission> tags to the DTD.
Output formats should make additions and omissions different colors from the
rest of the text; hyperlink-capable output formats should add relevant tags
and hyperlinks to their output, under certain circumstances (that is, if the
user intends for this whole context diff thing to happen). Then take the
diff and build a brand new .sgml with additions and omissions listed by
section number. IE
  <section> Section title/number ----> pulled from the original .sgml after
            looking over the diff to decide which section this
            addition/omission came from.
    context text.....
    <addition> any lines in the diff with + indicators go here
    context text....
    delimiter of some kind? HR?
    context text....
    <omission> any lines in the diff with - indicators
    context text....
  </section>

... then pass all of this through jade.
My problem is I don't know where to start with #2. Is it possible?
Problem: <addition> and <omission> must know what section number they belong
to and which addition/omission number they are, both in the summary document
produced by the diff and the actual document. This is so both sets of docs
can have matching anchor tags and hyperlinks. I've no idea if this is
possible.

note, approach 2 would allow this tool to work on any debiandoc book (or
sgml, whatever you prefer to call it).

Does anyone have any words of wisdom, criticism, or features they would like
to see in such a system?
-- 
..Aaron Van Couwenberghe... ..avancouw@calpoly.edu.. ..aaronv@debian.org..
	Berlin:			http://www.berlin-consortium.org
	Debian GNU/Linux:	http://www.debian.org