Tooling for our documents (was Re: pagination: initial draft available)

Wow... Looking forward to the discussion on Monday!

However... Let me address a boring but necessary practical issue at this point: we will have to decide which tools we want to use if our plan is to publish W3C documents. There are three aspects to it.

1. We have to choose a tool to edit the document, and do it in a way that the documents would easily fulfill the requirements of W3C's publication rules. Like at all standard institutions, there are such rules at W3C, too...:-)

2. We should have some sort of a common environment and versioning system to store the editor's draft and make it possible for several of us to work together

3. Following bugs, issues

Following the known approach of "one standard is good, more is better", different groups at W3C use different tools for both:-). But, at this moment, the usual toolsets are as follows:

1. For editing: ReSpec[1] is currently the best tool around. It is a big javascript library; the editor uses HTML5, linking to that library, and the right format is created automatically. There are some conventions to be followed, but nothing very onerous. 

For completeness, there are some older tools based on XML (not docbook, but similar) but they seem to be out of fashion these days. Alternatively, we can use HTML directly, without any external aid, but that is for the masochists among us:-)

2. For versioning, we actually have a choice. 
	- W3C maintains a Mercurial repository. It is possible to set up a dpub repository (or even a task-force level repository) and use that for versioning
	- We can use git, more exactly a special area for W3C on github
	- Again just for completeness, we could use CVS on a special subdirectory of the W3C server (the W3C server is one giant CVS archive), but that would require setting up ssh for all the editors (which is usually messy) and is not really open for Invited Experts... (whereas the Mercurial and Github approaches are)

3. For bugs, we already have our tracker[2] set up for the group; it can store issues and action items. If necessary, we can also set up a bugzilla instance for the group, but I think that would be an overkill.

My personal choice would be to use ReSpec+Github+tracker. Some people on the group are also active in other groups at W3C, they can also advise. The point is: we have to choose, and the ones who will edit documents should have a priority on choosing...

Cheers

Ivan


[1] http://www.w3.org/respec/
[2] http://www.w3.org/2005/06/tracker/

----
Ivan Herman, W3C 
Home: http://www.w3.org/People/Ivan/
mobile: +31-641044153
FOAF: http://www.ivan-herman.net/foaf.rdf