Should we write theory and implementation details in markdown format?

[bodduv]

Recently I have been looking through markdown and how it got popular. I have also looked through something called github pages through which we can generate site for github projects. I see that there are many advantages of using markdown for writing theory and implementation details (inside doc folder):

• Github can produce formatted output (in the case of latex we would have to compile it) => easier to review
• Can be used to generate Github pages
• Light weight
• Easier to read raw files than latex tex files (while being able to use latex math symbols)
• Using kramdown one can convert markdown files to tex files

One main attraction is that Github pages can use markdown documentation to generate website (hosted by github itself) with ease.

[davydden]

I would just stick with doxygen which also supports math symbols, separate standalone pages etc.

For now I would not bother much until we have something published on the topic.

[bodduv]

I think we should keep doxygen documentation inline with code. I am talking about the theory.tex file we have in doc folder.

[davydden]

Eventually I would switch it to an additional page in doxygen, which can be linked to from the home page.

[davydden]

*home/main index.html page of doxygen