[whatwg] including section titles and IDs in HTML spec diffs [was: WHATWG on Google+]

[Michael[tm] Smith]

Ian Hickson <ian at hixie.ch>, 2011-11-22 00:40 +0000:

> I'm poking around at this. I'm not sure sections are the best way to 
> organise this, because self-contained features are often in various parts 
> of the spec, or end up sprouting new sections unexpectedly. So I'm looking 
> at annotating the spec source with specific topics, e.g. "WebSockets" or 
> "Navigation" or whatnot.
> 
> If people could e-mail me the lists of topics they would be interested in 
> being e-mailed diffs for, it would give me a good idea of what coarseness 
> would be helpful here, and thus whether this is a realistic idea.

Another thing that's a lot less work and could be done in the mean time is
to provide the titles of the sections affected by each spec change.

You can get GNU diff to give you those by using the -F option with a regexp
specifying what to look for, like this:

  diff -u -F '<h[1-6]' ...

Then the beginning of a chunk for a change to your "source" file will show,
e.g.:

  @@ -80803,29 +80833,9 @@   <h3>Activation</h3>

...and a chunk of a diff for your "index" file will show, e.g.:

  @@ -71056,27 +71083,11 @@   <h3 id=activation><span class=secno>8.

To make svn generate diffs like that, you need to configure it to use an
external diff command, and make that command be a script that wraps GNU
diff and feeds it the right args, like this:

-----------------------------------------------------------------
#!/bin/sh
# http://svnbook.red-bean.com/en/1.2/svn.advanced.externaldifftools.html
# svn passes the things we need to diff as the 6th and 7th args
diff -u -F '<h[1-6]' ${6} ${7}
-----------------------------------------------------------------

Call that script "diffwrap" or something and in your ~/.subversion/config
file, put this:

diff-cmd = /path/to/diffwrap

I don't know what setup is being use to generate the diffs for
http://html5.org/tools/web-apps-tracker but it could use that to expose the
affected section titles in its UI somehow, along with providing links back
to those sections of the spec.

  --Mike

-- 
Michael[tm] Smith
http://people.w3.org/mike/+