SciProgCentre/kmath

Consider AsciiDoc as format of documentation in the repository

CommanderTvis opened this issue · 8 comments

CommanderTvis commented
Consider AsciiDoc as format of documentation in the repository
altavir commented

Any reasons for that? Markdown is much more widely accepted and formats are more or less equivalent.

CommanderTvis commented

Any reasons for that? Markdown is much more widely accepted and formats are more or less equivalent.

There are.

  1. AsciiDoc is supported by GitHub, and this is the only place where format acceptance counts.
  2. There are LOTS of features that Markdown hasn't: table of contents, convenient element anchors for navigation, delimited blocks as well as other layout elements, text replacements (rendering -> as → and so on).
altavir commented

GitHub is not the only place that counts. Space is Markdown-oriented as well as a lot of other tools. So won't fix. If we want to us some kind of nicer format, we should finish SNARK first.

CommanderTvis commented

GitHub is not the only place that counts. Space is Markdown-oriented as well as a lot of other tools. So won't fix. If we want to us some kind of nicer format, we should finish SNARK first.

  1. GitHub only renders these formats, so we'll be forced to store both SNARK sources and compiled files.
    • Markdown
    • AsciiDoc
    • Textile
    • ReStructuredText
    • Rdoc
    • Org
    • Creole
    • MediaWiki
    • Pod
  2. SNARK requires tremendous efforts incomparable with just changing file extensions in /docs from .md to .adoc (because AsciiDoc is mostly a superset of Markdown).
  3. Markdown really limits any practical use of the documentation; for me, it really was a disincentive to improve it.
altavir commented

SNARK could be compiled to Markdown or even plain HTML (and you can use HTML in markdown for layouting etc). Why not use HTML?

CommanderTvis commented

SNARK could be compiled to Markdown or even plain HTML (and you can use HTML in markdown for layouting etc). Why not use HTML?

Pure HTML isn't displayed by GitHub.

altavir commented

Pure HTML in Markdown is displayed quite fine.

CommanderTvis commented

Pure HTML in Markdown is displayed quite fine.

OK, that's true, but there is still point (2).