7

I remember having read somewhere that the meta section is for the questions that are not directly related to TeX but can't find it back. However, I hope this is the right place for my question.

Knuth is famous for his Literate Programming and since I've read about it, I've made a habit of writing the how and why in my comments (which now represent about 60-70% of my code). I'd like to give a try to Literate Programming but all I can find about it on google describes the ideology, not how to do it. Does anyone know where to start?

6
  • Probably TeX: The Program (Reading, Massachusetts: Addison-Wesley, 1986), xviii+600pp. ISBN 0-201-13437-3 will be a good starting point to find how it may be done. Dec 26, 2013 at 5:56
  • Literate programming is 'like writing an essay rather than a program'. Write an essay about your program—defend it as you present it. Start from a problem description and then tackle each part of the problem using your words and then some high-level code, eventually getting down to the nitty-gritty. Usually makes for an anti-climactic ending, but it gets the job done. Dec 26, 2013 at 19:15
  • @SeanAllred the problem is: when that part is done, how do I get the program out of the essay/how do I compile my program to get a nice documentation? It's quite frustrating if I have to first write my program and after rewrite it in a well-formatted document that explains it... Dec 26, 2013 at 19:19
  • Ahhhh. In TeX terms, you're talking about how to use web — I recommend noweb if you're doing general language stuff, but the 'official' one is cweb for C-like languages (C, C++, Java). (I think plain web is just Pascal, but I'm not sure.) However, I'd really recommend using org-babel for this, if you're ready to take the plunge into the (seriously) wonderful world of emacs. :-) Dec 26, 2013 at 19:27
  • @SeanAllred Sorry but I already plunged into the (even) wonderful world of vim ;-). Thanks for pointing out *web, that's what I was looking for. I'll have a look at noweb Dec 26, 2013 at 19:40
  • <insert enflaming stab at eVil here> ;) Dec 26, 2013 at 19:42

1 Answer 1

5

I'm not sure Meta is the place for it, since Meta is 'questions about questions'/'questions about the site', but it can be moved if necessary.

Depending on the programming language you're using, you're going to want to take a look at either WEB (original by Knuth, supporting TeX over Pascal), CWEB (Silvio Levy with Knuth, supporting C, C++, and Java), or one of the various other tools available. (I personally recommend noweb in conjunction with org-babel—the combination is very easy to work with, and org supports documentation export to many different formats. LyX also apparently works with noweb, but I haven't tried it.)

I can only give advice on how to use org-babel, but the workflow for standalone web derivatives seems to be the same:

  1. Acquire a version of web that you'd like to use, making sure to go through a Hello, World example.
  2. Write literate program—comments and code all in one(?) file.
  3. Use tangle to extract source code and weave to extract documentation. I imagine this is done using

    ctangle literate-program.web
    cweave literate-program.web
    

    or the syntax your tool uses. (This can almost always be gotten with mytool --help.)

3
  • 7
    I didn't really understand the question, but seeing your answer, I think that the question could be either on our main TeX.SX site or Programmers.SE ;)
    – yo'
    Dec 26, 2013 at 21:04
  • 1
    If your language is R then knitr is your tool. Dec 26, 2013 at 21:27
  • 3
    Programmers.SE seems to be the better fit—this isn't TeX-specific or TeX-central. TeX is merely an output format here. Dec 26, 2013 at 22:24

Not the answer you're looking for? Browse other questions tagged .