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?

closed as off-topic by Werner, Martin Schröder, yo', barbara beeton, Andrew Swann Jan 3 '14 at 12:55

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "This question does not appear to be about TeX - LaTeX Stack Exchange or the software that powers the Stack Exchange network within the scope defined in the help center." – Werner, Martin Schröder, yo', barbara beeton, Andrew Swann
If this question can be reworded to fit the rules in the help center, please edit the question.

  • 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. – Przemysław Scherwentke Dec 26 '13 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. – Sean Allred Dec 26 '13 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... – lvaneesbeeck Dec 26 '13 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. :-) – Sean Allred Dec 26 '13 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 – lvaneesbeeck Dec 26 '13 at 19:40
  • <insert enflaming stab at eVil here> ;) – Sean Allred Dec 26 '13 at 19:42
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.)

  • 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 '13 at 21:04
  • 1
    If your language is R then knitr is your tool. – Ethan Bolker Dec 26 '13 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. – Sean Allred Dec 26 '13 at 22:24

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