[erlang-questions] Speaking of comments

[Ulf Wiger]

On 13 Dec 2010, at 16:32, Masklinn wrote:

> 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…).


http://github.com/uwiger/erl2latex was inspired by a script John Hughes 
used to convert erlang source to PDF via LaTEX.

Some form of documentation, eating my own dog food, can be found in:
https://github.com/uwiger/erl2latex/raw/master/doc/erl2latex.pdf

It got a bit more complex than I had originally intended, since I wanted it
to do a fair job on legacy code. This introduced all sorts of escaping issues.

It was really interesting to work with this, since I noticed that it changes the
way you look at your code - the code really becomes (part of) the documentation.

I'm not going to claim that the above document illustrates that. I quit working 
on the code at some point, as I got distracted by other things. But I remember 
the feeling, and I've been missing it since then.

If I may quote Joe, he wrote this after trying it:

"I like it *very much* It's strange, I've tried edoc (didn't like it - the output 
is ugly) - I wrote my own literate programming system (never used it much - 
the code is weirdly ordered)

Used a full book markup system (for the prag book) - overkill for module 
documentation.

Somehow erl2latex strikes the right balance between effort and result - 
small effort nice result. (edoc = big effort, no benefit) (book production 
system, big effort, big benefit) …
...
Actually I like this so much I think I'll be using it a lot …"

I don't know if he actually did, but it was a nice thing to say. :)

BR,
Ulf W

Ulf Wiger, CTO, Erlang Solutions, Ltd.
http://erlang-solutions.com