Re: infra docs

[Toshio Kuratomi]

On Wed, Aug 03, 2011 at 12:34:12PM -0400, seth vidal wrote:
>  Following up on the action item for the infra-docs/SOP migration
> from
>  the wiki to git I was wondering what opinions folks had on these two
>  markup mechanisms:
>  
>  markdown
>  
>  Restructured Text
>   
I like restructured text because I use it extensivel for my documentation
but I don't think that it or any other generic markup language is going to
be a good fit here.  The problem is that you can't just ignore features.  If
we wrote in restructured text or markdown and wanted to convert to html the
parsers would choke on invalid syntax or format things in somehwat
surprising ways.

>  
>  Suggestions include:
>  
>  1. having each page be plain text and have the following format:
>   Title: blah
>   Summary: blah blah blah
>   
>   Body goes here
>  
>  Then having a commit hook for the git repo  generate a simple index of
>  the above for browsing on a web site.
>  
>  
>  2. Just put the txt files in a dir and let you browse based on filename
>  and be done with it. - since a lot of us are going to just use git grep
>  ANYWAY, just roll with it.
>  
>   
3. Write/find a minimal txt2html parser that just understands headings and
has a hyperlink format and use that to create html versions of the txt
files. (with everything else in <pre></pre>)

4) Agree to follow some format for headings/hyperlinks that look good as
text and we could use with a parser at a later date.

I kinda like 4)  and I'd say just keep the wiki format for headings and
links might be the easiest way to transition the docs.

-Toshio