[erlang-questions] Speaking of comments

[Joe Armstrong]

2010/12/13 Ulf Wiger <ulf.wiger@REDACTED>:
>
> 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. :)

I've changed my mind (again) - what I currently like best
is to invent a specific xml markup for each documentation task
then convert the xml to PDF using apache fop, or html using xslt.

Wiki text/edoc etc. are just toooo simplistic. I now like xslt-fo more
than LaTeX
(since the input has a proper parser tree and can be transformed) -
apache fop has a few warts though - time to hack on erlguten a bit
more :-)

/Joe




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