Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

closed as too broad by gnat, MichaelT, Bart van Ingen Schenau, Dan Pichelman, amon Nov 29 at 10:55

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

1  
You might find yourself leaning to TeX at some point - I am not familiar enough with it to say for sure. Consider browsing the TeX Stack Exchange to see if it looks like it might work. –  MichaelT Jul 3 '13 at 16:21
    
Perhaps AsciiDoc would work for you. methods.co.nz/asciidoc/userguide.html –  Gilbert Le Blanc Jul 3 '13 at 18:10
1  
LaTeX LaTeX LaTeX!!! :D logical structuring of the document, stable work environment, your choice of editor, the benefits go on and on. And it is absolutely gorgeous. imgur.com/gRXqwiA.jpg One of the easiest and absolutely the most expressive markup languages available. Another option is DocBook, although I haven't used it. ... Seriously this is screaming LaTeX. Look for details over at TeX.SX! We're a very friendly bunch of people! :) –  Sean Allred Jul 4 '13 at 3:26
    
@vermiculus - LaTeX was my first thought too, but then I started to search how to convert it to HTML and found that it was pretty unreliable. LaTeX is a very powerful language with many extensions. HTML isn't. But then I've no experience with LaTeX at all. Maybe it's doable if I stick to some specific subset of it? –  Vilx- Jul 4 '13 at 8:36
    
@Vilx read the answer there. The poor guy tried to convert PDF to HTML, ie visual markup to logical markup. htlatex is a good solution. –  Sean Allred Jul 4 '13 at 12:31

2 Answers 2

Sphinx (an implementation of reStructuredText) has a Latvian internationalisation. I like it very much. The number of programming languages that it supports is however somewhat limited, and creating support for another language is possible but difficult.

share|improve this answer
    
The domains are indeed somewhat limited, but you only need an X domain if you document an API written in X (and even then you may get along without one). Syntax highlighting delegates to Pygments and thus supports more languages than most people have ever heard of. In other words, this doesn't seem like a potential problem to me. There are other potential problems which would need some plugins or raw HTML (collapsible sections, separate blocks on the side, 80x25 console output) but overall Sphinx seems like a good choice. –  delnan Jul 3 '13 at 17:18
    
Yes, a new domain must only be defined when an API should be documented in a standardised format. So Sphix will probably be a bit more useful than I thought for the purposes of the OP. –  rem Jul 3 '13 at 17:32
    
Certainly looks interesting! I'll check it out! –  Vilx- Jul 3 '13 at 18:30

Frrom what I can gather, this seems like a good introduction to Latvian in LaTeX, but then again, I don't know Latvian very well ;).

LaTeX is what you need, but to be honest, Org-mode is what you should use. Org-mode is a single-sourcing tool for Emacs; a very intuitive one. Consider:

* My First Heading
* My Second Heading
čēŗāņā šōmēthīņģ Ī dōņ't ŗēāļļy ķņōw whāt „Ī'm typīņģ„ būt Ī wīļļ ģō wīth īt.
** My third heading?
Mōŗē thāņ ļīķēļy ābšōļūtē ģībbēŗīšh.  I can type things!
#+BEGIN_SRC emacs-lisp
  (setq org-latex-packages-alist nil)
  (if (not (memq "inputenc" (mapcar 'cadr org-latex-packages-alist)))
      (add-to-list 'org-latex-packages-alist
                   '("utf8" "inputenc" t)))
  (if (not (memq "fontenc" (mapcar 'cadr org-latex-packages-alist)))
      (add-to-list 'org-latex-packages-alist
                   '("utf8" "fontenc" t)))
  (if (not (memq "xltxtra" (mapcar 'cadr org-latex-packages-alist)))
      (add-to-list 'org-latex-packages-alist
                   '("" "xltxtra" t)))
  (setq org-latex-pdf-process
        '("xelatex -interaction=nonstopmode %f"
          "xelatex -interaction=nonstopmode %f"
          "xelatex -interaction=nonstopmode %f"))
#+END_SRC

emacs buffer

pdf

html

I will add more content later, incl. images, hopefully margin notes, spoiler stuff (HTML only), cross-referencing, and an index. For now though, I have other business I need to attend to, but I sincerely hope you get the gist of Org-mode.

Note that Org uses LaTeX for its PDF export, and all aspects of this export can be controlled through the single source. (To be honest though, I find it easier (as one TeXnically inclined) to edit the source myself. It might be possible to specify the preamble directly, which would be a better solution.)

share|improve this answer
    
Why is "Latvian support" so important? I assume LaTeX handles Unicode just fine, right? Also - since I'm a programmer I've no qualms about learning a new markup language. Although I am too lazy to learn Emacs. Notepad++ is my editor of choice. Is LaTeX better edited through something else? –  Vilx- Jul 4 '13 at 19:25
    
@Vilx- Technically, LaTeX does not handle Unicode (by default, there are packages you can load to support them, ie fontspec and inputenc), but the stable fork XeLaTeX does. I was rushing per company when I wrote this, so I'll be improving this answer soon via edit. –  Sean Allred Jul 5 '13 at 20:31
    
I'd recommend using a dedicated LaTeX editor, but you can choose whatever you're most comfortable with. TeXMaker is a popular choice, as is TUG's TeXworks, but given TeX's age, the kings supreme are still Vim and Emacs. Through a graphical interface, Emacs isn't that bad, but that is another topic entirely ;) cf tex.stackexchange.com/questions/339/latex-editors-ides –  Sean Allred Jul 5 '13 at 20:40

Not the answer you're looking for? Browse other questions tagged or ask your own question.