id	summary	reporter	owner	description	type	status	priority	milestone	component	version	resolution	keywords	cc	launchpad_bug
1227	Conversion of HTML docs to .rst	p-static	marlowe	"Following the conversion of the text-based docs to reStructuredText, it would make sense for consistency's sake to convert all the HTML-based documentation as well. This would also make the HTML docs more useful for people browsing through the source on the command line.

There's one sticking point before I start working on this: URLs. We want to have links in the documents such that they work as expected in HTML, and do something useful in any other format we convert the docs to. There are a lot of ways we could go with this:

* Have relative links that point to the rST versions of the docs. This is probably the least useful choice, because the HTML pages wouldn't work right.

* Have relative links that point to the HTML versions of the docs. (This is what they do now.) Downside is that somebody looking at the rST version of the doc wouldn't actually be directed to a useful resource, and the links wouldn't work if the HTML version hadn't been generated yet.

* Do some voodoo with the doc generation and convert the links. I'm not sure how much voodoo this would require; I think rST has some basic #define-style support for string substitution, but I'd have to try it out before knowing for sure that this option is feasible.

* Have absolute links pointing to the latest version of the HTML doc in Trac's VCS viewer. This is slightly hackish, and means that users viewing an outdated version of the documentation won't see anything useful by default, but it also gives us useful links in any format that we choose to use.

No matter which option we choose, it's probably unavoidable that generated docs will have to be committed to source control. :( Links directly into Trac's VCS viewer are used heavily, and these ones are probably widely distributed - we should avoid breaking them if possible. (This is why people don't usually store user-facing documents in the VCS and distribute them from there :)"	enhancement	closed	minor	1.9.0	documentation	1.8.0	fixed	docs	zooko