What markup languages are good for programming articles/tutorials?

Posted by Vilx- on Programmers See other posts from Programmers or by Vilx-
Published on 2013-07-03T16:00:39Z Indexed on 2013/07/03 17:17 UTC
Read the original article Hit count: 709

I very much wish to write a programming tutorial in my native language (Latvian). There are far too few of those. I am however unsure on what markup language to use for writing it. Here are a few things I would like to achieve:

  • The same source can be compiled to both HTML for online viewing and printed form (PDF?). In HTML form it would allow superior interaction and appearance (see below), while the print form would look good on paper (layout etc).
  • I have the idea that the tutorial could be multi-language. Different students have different requirements in their schools. For example, some schools teach Java, some teach C#. You could choose the language on the top of the HTML page and the relevant code snippets (and occasionally pieces of text) would swap out. Most of the text is the same anyway, only the language syntax is a bit different.
  • The text would occasionally contain images too of course and these would need to be included in both the HTML and the printed version
  • In the HTML version the code snippets should get automatic syntax coloring which should ideally be the same as in the recommended IDE for the tutorial. In case there are ambiguities, hints for the syntax colorer should be possible, but I don't want to do the whole coloring by hand.
  • "Output" syntax coloring which would emulate a standard 80x25 text console (since many of the initial programs would be console applicatioins)
  • Collapsible sections for answers to questions (aka "spoiler tags")
  • Automatically generated index/table-of-contents
  • Links to other parts of the tutorial (rendered as links in HTML and as references in print version)
  • "Side note" sections, rendered as separate blocks on the side.
  • Other functions useful in publications that I'm not aware of :)

I know this is a bit much to ask, but is there something close enough that I could take it as a starting point and add the necessary features myself? Or is there something in the whole list (like the desire to have both HTML and print versions from the same source) that makes it all fundametally infeasible?

© Programmers or respective owner

Related posts about tutorial

Related posts about writing