[erlang-questions] Speaking of comments
Fri Dec 17 07:06:42 CET 2010
On Tue, 14 Dec 2010 02:32:02 +1100, Masklinn <> wrote:
> On 2010-12-13, at 16:08 , Iñaki Garay wrote:
>>>> On Wed, Dec 8, 2010 at 8:45 PM, Edmond Begumisa
>>>>> I've thought -- now and then, in the back of my mind -- about
>>>>> comments from actual source all-together (for all languages) and
>>>>> putting them in companion files that the editor lines up
>>>>> side-by-side. More
>>>>> like annotating than just traditional commenting.
>> It was my understanding that this is called literate programming, as
>> envisioned by Knuth, although he includes the comment markup in the
>> same file as the code, and uses a preprocessor to extract either the
>> documentation or the code.
>> Knuth's original program was for C and is called CWEB.
> That's exactly the reverse of literate programming: literate programming
> puts prose first and code second (so instead of marking up the comments,
> you mark up the code).
> Knuth's own WEB (and CWEB) is extremely complex (out-of-order with macro
> expansions and hypertext references) and rather unlike usual program
> writing, a simpler literate idea can be found in Literate Haskell (lhs)
> where lines of code are prefixed (with `> `) and everything else is
> comment, yielding rather interesting executable documents.
> Python also has something similar (though extremely reduced in scope) in
> its "doctests": code lines are prefixed with 4 spaces and sequentially
> executed, everything else is non-executable text. Doctests can be used
> either in docstrings (documentary comments, providing executable
> examples in the APIDoc) or as free-standing documents (documentation,
> papers, etc…).
> The core idea stays the same: the core idea of literate programming is
> that the modules are first and foremost used to communicate with humans
> via prose, and the code is the second-class citizen.
> As to edmond's idea of having code and comments side-by-side, he might
> be rather interested in Pycco  which produces literate-style
Pycco this looks nice. Rendering wise, it's very close to what I had in
> Though it's a generator (it extracts and formats comments within the
> source file) it does produce something similar to what was described,
> and it seems to be erlang-compatible.
Yes, that's the difference. It would be good to have this kind of thing
available while editing and not have to go through a generation step.
- Edmond -
>  http://fitzgen.github.com/pycco/
> erlang-questions (at) erlang.org mailing list.
> See http://www.erlang.org/faq.html
> To unsubscribe; mailto:
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/
More information about the erlang-questions