Emacsist RSS --- If never, make it ever: C-h C-h

Tutorial for OrgLitProg


这里 查看更多 Emacs 相关推荐文章最新 Emacs 圈的动态. 欢迎关注微信公众账号: Emacsist

Hick 叽喳:

     总感觉 literate programming 这概念怪怪的 , 不得其要领...

Welcome to a brief tutorial on literate programming in org-mode.

The following began as the basis for a workshop for the PDX Emacs Hackers meetup, but since everyone couldn’t attend, I decided to expand it into a tutorial. I assume that you understand the basics of Emacs and as well as familiarity with org-mode for creating exported documents.

As you probably know, Org is pretty large, and being able to write, evaluate and connect blocks of source code is a daunting task on its own. I hope this tutorial is a good start, but if I glossed over something you think I should include, please let me know.

Warning:The examples are pretty lame.


During my workshop, I mentioned needing version v8.2.10 of org-mode (or better). Since org now comes with Emacs, you may already have a version, so type: C-h v and org-version, to see if everything in this tutorial will work (most things will, but…)

If you need a newer version, then type M-x package-refresh-contents

And then type: M-x package-install and org

That should do it. You may want to also install org-plus-contrib.

During this tutorial, I wanted to demonstration lots of languages you can use… but this means, you’d have to have a slew of interpreters installed, so in this tutorial, I hope you have the following:

  • Shell (sorry, this might be hard for you Windows people)
  • Python
  • Ruby

However, you’re a smart cookie, so feel free to translate these silly examples into your favorite language.


Before we dive into how org-mode does literate programming, perhaps I should briefly describe literate programming.

Why Literate Programming?

Literate Programming first invented by Donald Knuth in 1980’s in an attempt to emphasize communication to other members on your team. As Donald Knuth once wrote:

“Let us change our traditional attitude to the construction of programs. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.”

Wanting programs to be written for human understanding, with the order based on logic of the problem, ant not constrained to deficiencies in the programming language, we create a literate programming document that generates a document for people andand the source code files:


The idea is to invert code peppered with comments to prose interjected with the code.

While the resulting source code tangled from a literate programming document, may look the same to one coded directly, this idea did not result in an industry changer. Although it is used (to various degrees) in niche circles.

Why Org?

Knuth’s original literate programming approach was “text with minimal support, as only he wrote a programnoweb to create (weave) the documentation and write (tangle) the source code.

For literate programming to be truly useful, one needs help from an editor, for instance the iPython’s notebook. In the end, you still want text, as Carsten Dominik wrote:

“In the third millennium, does it still make sense to work with text files? Text files are the only truly portable format for files. The data will never get lost.”

So if you buy into literate programming, org-mode is fookin’ brilliant, especially since we already use org-mode for everything else, right?


Some of the advantages of using org-mode for your source:

  • Better documentation for your source code
  • Great for team communication over issues and problems
  • Clarify your own thoughts for complicated situations
  • Note-oriented REPL for investigating new libraries
  • Inter-language facility
  • Org’s organizational features, like Agendas

A Warning

The software world of the 1980s is quite different than the current landscape, as engineers are more connected and work in teams, but they don’t often use the same tools. If your team doesn’t use Emacs, you may still find org-mode’s approach useful.

First, it is a good way to work through complicated algorithms, and once you have something good, commit the resulting source code (as the prose you write become comments in the code).

Second, org-mode files can be a thoughtful repl as each block can be evaluated separately, and the results can be fed back to other blocks… but I’m getting a head of myself.

本文未收录完整, 更多详情参见 原文: http://www.howardism.org/Technical/Emacs/literate-programming-tutorial.html

原文出处: Howard Abrams
原文地址: http://www.howardism.org/Technical/Emacs/literate-programming-tutorial.html
原文时间: 2016-03-17 15:00
本文地址: http://emacsist.com/10806
整理时间: 2016-03-20 18:49

本文由 Hick 整理,转载请保留以上信息;
COPYLEFTThe articles on this site come from Internet, thanks to all the original authors.
      If anything about COPYRIGHT, or LEFT, please contact Emacsist at gmail dot com .