From: Intransition Date: 2011-08-09T02:56:34+09:00 Subject: Re: Help out with the next version of ruby-lang.org On Aug 7, 6:03 pm, Alex Chaffee wrote: > This sounds great. I've been using Markdown as a source file format > for all my static content [1] and it's been a joy, especially in > combination with Showoff for slides and Erector for web pages. > > But Markdown isn't perfect. There are several gaps and ambiguities in > the language, and often you have to insert raw HTML, which sucks. At > the suggestion of some colleagues at an open source teaching company > [2] I've been looking into using AsciiDoc instead. Before you get too > far into your porting process you should probably evaluate it as an > alternative to Markdown. > > In addition to the richer and saner syntax, one thing AsciiDoc has > over Markdown is that there seem to be more professional publishing > companies that use it (e.g. O'Reilly) so there's a good tool chain for > converting AsciiDoc into DocBook, PDF, etc. > > To be clear, this isn't a full-throated endorsement, but I'm strongly > considering making the leap and I'd love to hear your opinions and > experiences, and share mine. Personally I would like to see a fast (read c-based) standalone RDoc markup tool with some beefed up markup support (like markdown's `code` brackets). The doc tool used may seem secondary, but I actually think that a solid Ruby-based tool would give a boost to Ruby documentation efforts, letting Ruby steer it's own ship and improve it's documentation (and websites) on it's own terms.