Source files for documentation

[alexarje]

Could you add the source files (markdown?) for the documentation on Github? This would be very useful so that it can be reused elsewhere

[balintlaczko]

The embedded documentation is actually an HTML page (or rather two pages: getStarted and readme) residing in the documentation folder. Unfortunately [jweb] cannot render .md files, or (probably) anything else than an HTML. And even with that, it's more reliable with pre-HTML5 stuff, for example video tags won't work properly - hence my hacky solution with swapping between the gifs and the pngs with a play icon... :) But - (as far as I remember) Github can render HTML files(?) as the readme file, so we can try doing that. If that turns out to be just asking for more problems, I can just make a markdown version of the whole thing. Also, in the HTML, I kept myself from using any frontend frameworks (which could have made the code much more elegant and maintainable) due to my shaken trust in [jweb]...

[alexarje]

Yes, HTML is good for the embedded documentation in Max, but I think it would be very useful to reuse the information in other places (GitHub wiki, UiO pages, Carpentry courses, etc.). And then it would make sense so have the original documentation files in markdown, and then set up a pandoc convert to other formats. Would that work?

[balintlaczko]

Ah I see your point now! Yes, it would be really good to have one central place for the docs, and everything which serves them (in different websites, the embedded docs, etc) would just update itself when that central thing changes. The only issue I don't see solved yet is how to do the trick with swapping the pngs with the gifs (to "emulate" a video) with JS. (This I only have to do because of a known issue with [jweb] that it won't play back normal HTML5 video tags...) If it is possible to set up pandoc in a way to get the specific markup the JS script works with - or just have those parts left as HTML inside the md without confusing pandoc with this - we can do this more or less easily.

[balintlaczko]

What I can do now, just to have something until we come up with a framework, is to make an md out of the html without the png/gif thing. I could also just leave the gifs there but I am a bit afraid that it would be eye-soaring to see all those big, infinitely looping gifs on one page...

[balintlaczko]

Done!