[tahoe-dev] [tahoe-lafs] #1227: Conversion of HTML docs to .rst

[tahoe-lafs]

#1227: Conversion of HTML docs to .rst
-------------------------+--------------------------------------------------
 Reporter:  p-static     |           Owner:  nobody   
     Type:  enhancement  |          Status:  new      
 Priority:  minor        |       Milestone:  undecided
Component:  unknown      |         Version:  1.8.0    
 Keywords:               |   Launchpad Bug:           
-------------------------+--------------------------------------------------
 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 :)

-- 
Ticket URL: <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1227>
tahoe-lafs <http://tahoe-lafs.org>
secure decentralized storage