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
Attachment:
pgpiYTYcIkRul.pgp
Description: PGP signature
_______________________________________________ infrastructure mailing list infrastructure@xxxxxxxxxxxxxxxxxxxxxxx https://admin.fedoraproject.org/mailman/listinfo/infrastructure
