Re: [whatwg] New HTML5 spec-editing tools released

[Manu Sporny]

Joe D Williams wrote:
>> http://wiki.github.com/html5/spec
>
> I think this is really great, Manu. However, I think it needs the mode
> where only the new stuff is provided. That is, content that is identical
> to the main spec is just not really a factor is evaluating added or
> revised, or changed material. I think the main button for showing
> candidate text should be that just the new/revised is shown.

You're right - we do need an easy and automatic mechanism to create
diffs between specs in the new HTML5 spec-editing tools. I was
eventually going to coordinate with W3C staff to use their HTML diffing
marking program (since they do this on a regular basis). There seems to
be a variety of programs out there to perform HTML diffs:

http://esw.w3.org/topic/HtmlDiff

> in which, essentially, only the replacement text is shown. That may be
> an old way to do it, but it provides focus for the reviewer who is
> familiar with the rest of the document. Then, when the candidate is
> approved, if everything ishooked in, the editors might well choose to
> use the process you describe here to publish a complete current draft.

Other things that we could do to make the reviewing process easier:

* Generate very focused HTML diffs, showing only what changed and hiding
everything that didn't change. Give minimal context (1-4 paragraphs at
most), highlight terms.
* Provide a "jump-to-next/previous-change" button/index

Thanks for the feedback, Joe - I'll try to put something together that
provides automatic diffs during the coming weeks.

-- manu


-- 
Manu Sporny (skype: msporny) (twitter: manusporny)
President/CEO - Digital Bazaar, Inc.
blog: Bitmunk 3.1 Released - Browser-based P2P Commerce
http://blog.digitalbazaar.com/2009/06/29/browser-based-p2p-commerce/

[whatwg] New HTML5 spec-editing tools released

[Manu Sporny]

The newest version of the microsection spec-editing tools have been made
available:

http://wiki.github.com/html5/spec

These tools, microsplit and microjoin, are capable of:

* Taking Ian's latest HTML5 spec as an input document and splitting it
  up into microsections.
* Re-mixing, removing and adding microsections specified from another
  source (for example: RDFa, John Foliot's summary suggestions, etc.)
* Producing one or more output specifications (such as Ian's HTML5 spec,
  HTML5-rdfa, HTML5-johnfoliot-summary, etc.)

This process:

* Does not impact Ian's current editing workflow.
* Empowers additional editors to modify the HTML5 specification without
  stomping on each other's changes.
* Enables alternate HTML5 specifications to be authored while
  automatically updating the alternates with Ian's spec changes.
* Is currently used to produce the HTML5+RDFa specification.
* Provides a mechanism that can be used to generate specification
  language that is specific, and that can be used to form consensus
  around the HTML5 specification at the W3C.
* Enables thoughtful and well-mannered dissent.

There is even a pretty picture that describes the workflow:

http://wiki.github.com/html5/spec

Anyone is free to clone the repository, use the tools, generate
remixed/updated/altered specifications and propose them as alternatives.

I am seeking thoughts and suggestions about these tools - how they might
help or hinder, as well as improvements that should be considered.

-- manu

-- 
Manu Sporny
President/CEO - Digital Bazaar, Inc.
blog: Bitmunk 3.1 Released - Browser-based P2P Commerce
http://blog.digitalbazaar.com/2009/06/29/browser-based-p2p-commerce/