[erlang-questions] Speaking of comments

[Edmond Begumisa]

"I noticed that it changes the way you look at your code"

Intriguing revelation.

Maybe an editor that enabled you to write the comments without having to  
write markup could help spread the use of such tools.

- Edmond -


On Tue, 14 Dec 2010 03:20:06 +1100, Ulf Wiger  
<ulf.wiger@REDACTED> wrote:

>
> 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
>
>
>


-- 
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/