[erlang-questions] Multi-line comments in Erlang
Zvi
Matlab/Octave has single line comments, like Erlang (i.e. starting
with '%' sign). But it also have multi-line comments, like for
example:
%{
this is example
of multi-line
comments in Matlab
%}
which is equivalent to:
%this is example
%of multi-line
%comments in Matlab
How difficult is to add comments like this to Erlang?
Thanks,
Zvi
________________________________________________________________
erlang-questions (at) erlang.org mailing list.
See http://www.erlang.org/faq.html
To unsubscribe; mailto:erlang-questio...@erlang.org
James Churchman
Zvi .
It's just simple change to Erlang source code parser.
Probably this should be submitted as EEP, so OTP team will consider it.
Rapsey
multiple lines.
Sergej
James Churchman
Robert Virding
Robert
--
Robert Virding, Erlang Solutions Ltd.
Robert Virding
Robert
----- "James Churchman" <jamesch...@gmail.com> wrote:
Richard O'Keefe
On 8/12/2010, at 4:32 AM, Zvi wrote:
> Hi,
>
> Matlab/Octave has single line comments, like Erlang (i.e. starting
> with '%' sign). But it also have multi-line comments, like for
> example:
>
> %{
> this is example
> of multi-line
> comments in Matlab
> %}
>
> which is equivalent to:
>
> %this is example
> %of multi-line
> %comments in Matlab
>
> How difficult is to add comments like this to Erlang?
It's worth remembering that Erlang syntax is based on Prolog syntax,
and Prolog has always had PL/I-style /*...*/ comments. Somewhere on
the way to Erlang, such comments were deliberately *removed* from
the language.
/* ... */ comments have no known advantages over % comments;
with adequate editing tools it is equally easy to "comment out"
or "comment in" a region either way and they are equally easy
to type or reformat.
However, /* ... */ comments come with several risks, which can
be ameliorated by syntax colouring to be sure, but not all programmers
can see.
Jesper Louis Andersen
>
> /* ... */ comments have no known advantages over % comments;
> with adequate editing tools it is equally easy to "comment out"
> or "comment in" a region either way and they are equally easy
> to type or reformat.
Is it, in Prolog acceptable to nest layers of /* .. */ ? It tend to be
that case which is hard to implement. Today, I see little need for
them. Most editors are fully capable of handling comment sections
spanning multiple lines with ease and the vicious idea of commenting
out code as a kind of revision control was luckily abolished with the
introduction of proper rev. control.
--
J.
Richard O'Keefe
On 8/12/2010, at 12:41 PM, Jesper Louis Andersen wrote:
> On Tue, Dec 7, 2010 at 11:14 PM, Richard O'Keefe <o...@cs.otago.ac.nz> wrote:
>>
>> /* ... */ comments have no known advantages over % comments;
>> with adequate editing tools it is equally easy to "comment out"
>> or "comment in" a region either way and they are equally easy
>> to type or reformat.
>
> Is it, in Prolog acceptable to nest layers of /* .. */ ?
No, most definitely NOT. I did say they were PL/I-style comments,
which do not nest. Nesting comments are one of those clever ideas
that turn out to be really dumb, because they don't actually work.
> It tend to be
> that case which is hard to implement.
As it happens, my Prolog tidier has code to convert plain bracketed
comments to standard form *and* nesting bracketed comments to
standard form. As you can see, there is not a great deal of
difference.
static void
com2plain(FILE * card, FILE *line, int astcom, int endcom) {
int c;
int state;
enter_comment
for (state = 1; (c = getc(card)) >= 0; ) {
if (c == endcom && state != 0) break;
state = c == astcom;
copy_comment(c);
}
leave_ast_comment
if (c < 0) SyntaxError(eofinrem);
}
static void
com2nest(FILE * card, FILE *line, int begcom, int astcom, int endcom) {
int c;
int state;
int level;
enter_comment
for (state = 1, level = 1; (c = getc(card)) >= 0; ) {
if (c == endcom && state == 1) {
if (--level == 0) break;
} else
if (c == astcom && state == 2) {
level++;
}
state = c == astcom ? 1 : c == begcom ? 2 : 0;
copy_comment(c);
}
leave_ast_comment
if (c < 0) SyntaxError(eofinrem);
}
Today I'd do that a bit differently, of course.
> Today, I see little need for them.
________________________________________________________________
Stefan Marr
On 07 Dec 2010, at 23:14, Richard O'Keefe wrote:
> /* ... */ comments have no known advantages over % comments;
> with adequate editing tools it is equally easy to "comment out"
> or "comment in" a region either way and they are equally easy
> to type or reformat.
Very general statement, very specific response: Yes they do!
At least for me they are extremely helpful to document parts where I need to work around different compilers in C/C++. Inline comments with /**/ to annotate these things is the only way to keep track of all those nasty things...
However, that is neither related to the original question nor related to its usefulness in Erlang...
Best Regards
Stefan
David Mercer
> Nesting comments are one of those clever ideas
> that turn out to be really dumb, because they don't actually work.
I'll bite, mainly because I've sometimes thought nesting comments would be
helpful, for instance, when commenting out large blocks of code, but it is
rare that I get to work with a language that supports them. Since you're
almost always right about such things, why do you say that they don't
actually work?
Cheers,
David
Edmond Begumisa
comments from actual source all-together (for all languages) and instead,
putting them in companion files that the editor lines up side-by-side.
More like annotating than just traditional commenting.
Has this sort of thing been done before? Is there a particular editor that
can give me this out of the box? (I admittedly haven't explored a large
number of editors)
Using Erlang as an example, I've secretly wanted something like...
foo.erl
foo.cts
Then an editor that could give me two panes while keeping the two files in
sync...
foo -> | This function does...
blah | This part is buggy...
balh |
Also, in the right pane, I've wanted nestable trees with flexible levels
of detail. Heck, why not even rich text? "FIX ME" in bold red. Take it
further: login-name awareness, source-control/bug-tracker integration
(this programmer said this, that programmer said that.)
It seems a shame that in 2010, it's still so limiting what we can do with
comments in our source code!
- Edmond -
--
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/
Bengt Kleberg
For commenting out code, it is possible to use:
-ifdef(never_defined).
...code
-endif().
bengt
Frédéric Trottier-Hébert
I've found the lack of multiline comments annoying in the past, but most of the time, having the editor (vim in my case) handle it for me has been fine most of the time. It fails at commenting only part of a line when doing very specific tests and debugging, but that's about it.
--
Fred Hébert
http://www.erlang-solutions.com
Richard O'Keefe
On 8/12/2010, at 1:26 PM, Stefan Marr wrote:
> Hi:
>
> On 07 Dec 2010, at 23:14, Richard O'Keefe wrote:
>> /* ... */ comments have no known advantages over % comments;
>> with adequate editing tools it is equally easy to "comment out"
>> or "comment in" a region either way and they are equally easy
>> to type or reformat.
> Very general statement, very specific response: Yes they do!
> At least for me they are extremely helpful to document parts where I need to work around different compilers in C/C++.
You can do that equally well with // comments.
> Inline comments with /**/ to annotate these things is the only way to keep track of all those nasty things...
On the contrary, the very first time I ever saw such annotation comments
was in Burroughs Algol, using % comments. Prolog programmers often use
%FIXME% or something like that.
Richard O'Keefe
On 9/12/2010, at 3:39 AM, David Mercer wrote:
> On Tuesday, December 07, 2010, Richard O'Keefe wrote:
>
>> Nesting comments are one of those clever ideas
>> that turn out to be really dumb, because they don't actually work.
>
> I'll bite, mainly because I've sometimes thought nesting comments would be
> helpful, for instance, when commenting out large blocks of code, but it is
> rare that I get to work with a language that supports them. Since you're
> almost always right about such things, why do you say that they don't
> actually work?
Here is a Haskell example. Something very like this actually bit me.
comment_close = "-}"
Comment that out:
{-
comment_close = "-}"
-}
OOPS! The comment ends at the first -}, not the second.
Before you say "but the first -} is in a quoted string",
recall that nesting comments are completely general, they are
NOT limited to escaping valid syntax in the programming language
in question.
I define "work" in this context as "you can comment out an
arbitrary chunk of text without having to worry about what is
inside it".
My text editor has a "comment out region" command that
handles comments of the form LX ... XR. What it does is
to add extra spaces around Xs, so that this example
would be treated as
{-
comment_close = " - }"
-}
and the "comment in region" command deletes single spaces
on either side of an X. This *does* work, because it
guarantees that LX or XR brackets will never be found
inside the comment. But that means it doesn't *need* nesting
comments at all.
Zvi .
And even if you do use tools, many times you work not on your machine or on
target headless environments, with only basic editor available, or with
editor that you know poorly or which didn't configured with your macros,
etc.
2. Comments are essentially Natural language (let's say US English)
document, embedded into Programming language (Erlang) document.
Therefore, embedded document should be left intact. Ideally I would like
comments to be something, like HEREDOC.
3. Free format is the king! Language designers shouldn't dictate programmers
how to format and ident their code.
How differnt is starting comment line from '%' in Erlang, from putting 'C'
or '*' in the first column in FORTRAN?
4. In other languages, that doesn't have multiline comments I often use
ifdef(false) macro, or outright if(false) to "comment out" parts of code. I
think it's uglier, than proper multiline comments, but still better than
comment every single line.
Zvi
Daniel Goertzen
quoted strings for multiline comments. It works well, but they are exposed
to the interpreter which smells a bit. What if erlang had HEREDOCs *plus* a
way to mark any string as a comment. Some illustrations, using Python's
triple quoting as HEREDOC format.
X="""
This is
a multiline heredoc
""",
...
%"""
This is
a multiline comment
"""
myfun(X, Y %"An inline comment", Z) -> ...
So comment and string delimiting uses the exact same logic, but you stick a
% in front to mark it as a comment instead of a string.
Dan.
Zvi
On Dec 9, 5:58 pm, Daniel Goertzen <daniel.goert...@gmail.com> wrote:
> Thank you for reminding me about HEREDOCs. In Python, I often use triple
> quoted strings for multiline comments. It works well, but they are exposed
> to the interpreter which smells a bit. What if erlang had HEREDOCs *plus* a
> way to mark any string as a comment. Some illustrations, using Python's
> triple quoting as HEREDOC format.
>
> X="""
> This is
> a multiline heredoc
> """,
> ...
>
> %"""
> This is
> a multiline comment
> """
>
> myfun(X, Y %"An inline comment", Z) -> ...
>
> So comment and string delimiting uses the exact same logic, but you stick a
> % in front to mark it as a comment instead of a string.
>
> Dan.
>
> On Thu, Dec 9, 2010 at 3:48 AM, Zvi . <zvi.avra...@gmail.com> wrote:
> > 1. The beauty of dynamic languages is that you don't need tools and IDEs!
> > And even if you do use tools, many times you work not on your machine or on
> > target headless environments, with only basic editor available, or with
> > editor that you know poorly or which didn't configured with your macros,
> > etc.
>
> > 2. Comments are essentially Natural language (let's say US English)
> > document, embedded into Programming language (Erlang) document.
> > Therefore, embedded document should be left intact. Ideally I would like
> > comments to be something, like HEREDOC.
>
> > 3. Free format is the king! Language designers shouldn't dictate
> > programmers
> > how to format and ident their code.
> > How differnt is starting comment line from '%' in Erlang, from putting 'C'
> > or '*' in the first column in FORTRAN?
>
> > 4. In other languages, that doesn't have multiline comments I often use
> > ifdef(false) macro, or outright if(false) to "comment out" parts of code. I
> > think it's uglier, than proper multiline comments, but still better than
> > comment every single line.
>
> > Zvi
>
> > On Tue, Dec 7, 2010 at 8:20 PM, Rapsey <rap...@gmail.com> wrote:
>
> > > Is it that important? Any proper programming editor can comment/uncomment
> > > multiple lines.
>
> > > Sergej
>
> > > On Tue, Dec 7, 2010 at 5:49 PM, Zvi . <zvi.avra...@gmail.com> wrote:
>
> > >> Why do you think it's not possible?
> > >> It's just simple change to Erlang source code parser.
> > >> Probably this should be submitted as EEP, so OTP team will consider it.
>
> > >> On Tue, Dec 7, 2010 at 6:25 PM, James Churchman <
> > >> >wrote:
>
> > >> > not posible in erlang, but many editors (eg i use textmate) will
> > comment
> > >> > and uncomment multiple lines with % on each line..
> > >> > On 7 Dec 2010, at 15:32, Zvi wrote:
>
> > >> > > Hi,
>
> > >> > > Matlab/Octave has single line comments, like Erlang (i.e. starting
> > >> > > with '%' sign). But it also have multi-line comments, like for
> > >> > > example:
>
> > >> > > %{
> > >> > > this is example
> > >> > > of multi-line
> > >> > > comments in Matlab
> > >> > > %}
>
> > >> > > which is equivalent to:
>
> > >> > > %this is example
> > >> > > %of multi-line
> > >> > > %comments in Matlab
>
> > >> > > How difficult is to add comments like this to Erlang?
>
> > >> > > Thanks,
> > >> > > Zvi
>
> > >> > > ________________________________________________________________
> > >> > > erlang-questions (at) erlang.org mailing list.
> > >> > > Seehttp://www.erlang.org/faq.html
> > >> > > To unsubscribe; mailto:erlang-questions-unsubscr...@erlang.org
Banibrata Dutta
> I think Python using '#' for comments.
>
Single line comments start with '#', but multi-line is done using """..."""
Richard O'Keefe
On 9/12/2010, at 10:48 PM, Zvi . wrote:
> 1. The beauty of dynamic languages is that you don't need tools and IDEs!
What has this to do with >dynamic< languages?
The only language I use an IDE for is Smalltalk (which is dynamic).
Erlang/OTP comes with lots of tools.
As for editors, excluding help files, the editor I use is
13100 lines, 6770 SLOC, 381 kiB in size and originally ran
on PDP-11s and used to run on MS-DOS.
> 2. Comments are essentially Natural language (let's say US English)
> document, embedded into Programming language (Erlang) document.
People who ask for multiline and nesting comments often want them to
contain program text.
> Therefore, embedded document should be left intact.
This is not a valid conclusion. People who use Javadoc, Haddock (for
Haskell), PlDoc (for Prolog), or ErlDoc (for Erlang) *want* their
natural language text to be marked up in various ways and transformed
for display. There has long been a fashion in C for writing
/* long comments
* with stars at the
* beginning of every line
* and a lopside end
*/
which I have always found ugly. But the existence of that fashion
shows that there are many people who find value in their commentary
being explicitly marked.
> Ideally I would like comments to be something, like HEREDOC.
Other people want a clear and unambiguous separation between
what is commentary and what is not, so that you can look at
_any_ line in a file and instantly tell what you are looking at.
>
> 3. Free format is the king!
A non-sequitur. Ada is free format, but it has only -- end of line
comments. Fortran 95 is free format, but it has only ! end of line
comments.
> Language designers shouldn't dictate programmers
> how to format and ident their code.
Somebody forgot to tell Larry Wall and Guido van Rossum that;
they also forgot to tell the Haskell designers and the Occam designers.
> How differnt is starting comment line from '%' in Erlang, from putting 'C'
> or '*' in the first column in FORTRAN?
Very different. % in Erlang is like ! in Fortran: you can put it in
any column you choose.
>
> 4. In other languages, that doesn't have multiline comments I often use
> ifdef(false) macro, or outright if(false) to "comment out" parts of code.
This contradicts your earlier statement that the contents of multiline
comments are natural language text.
> I
> think it's uglier, than proper multiline comments, but still better than
> comment every single line.
Erlang also has -if.
Woody Peterson
On Dec 9, 2010, at 12:58 PM, Richard O'Keefe wrote:
> People who ask for multiline and nesting comments often want them to
> contain program text.
Furthermore, people who want lots of commented program text often want
it for "historical" purposes. Lean on your SCM and just delete it
outright.
Ryan Zezeski
On Dec 9, 2010, at 4:48 AM, "Zvi ." <zvi.a...@gmail.com> wrote:
>
>
> 3. Free format is the king! Language designers shouldn't dictate programmers
> how to format and ident their code.
> How differnt is starting comment line from '%' in Erlang, from putting 'C'
> or '*' in the first column in FORTRAN?
>
> Zvi
>
Really? If free format is king then why does every lang have common code conventions? For example, I hate CamelCase but that doesn't mean I'm going to start naming my variables camel_case in Java because my coworkers would take me out back and beat me.
There should always be a middle ground between extremes but without some type of common conventions our code would be a tower of babel, more so than it already is. People make certain assumptions, and when you break those assumptions confusion, contempt, and even bugs can ensue.
I don't see the need for multiline comments as described in this thread. Any reputable editor can handle it. I know I have no problems in Emacs or Vim.
I also know in the past multiline comments in C++ has bitten me because I nested them in order to comment out code. As has been said, good SCM takes care of this for you, git stash and branch come to mind.
-Ryan
Bengt Kleberg
A variable with _ in it is easier to read than one without. Why would
your co-workers harm you for making their life easier?
bengt
David Mercer
> Furthermore, people who want lots of commented program text often want
> it for "historical" purposes. Lean on your SCM and just delete it
> outright.
I can't speak for anyone else, but I usually want to comment out chunks of
source code during a debugging process.
Masklinn
> Thank you for reminding me about HEREDOCs. In Python, I often use triple
> quoted strings for multiline comments. It works well, but they are exposed
> to the interpreter which smells a bit.
But even if that weren't the case, *nothing* guarantees comments aren't bubbled to the runtime. XML comments are part of its DOM, Haskell's comments are used to provide options to the interpreter or compiler, …
Anthony Shipman
> for display. There has long been a fashion in C for writing
> /* long comments
> * with stars at the
> * beginning of every line
> * and a lopside end
> */
> which I have always found ugly. But the existence of that fashion
> shows that there are many people who find value in their commentary
> being explicitly marked.
I believe that it was Rob Pike who recommended the stars to make comment
blocks stand out. This was way back in the '80s when it was common to print
out code on 132 column paper and pore over it off-line. Nowadays we have
syntax colouring and the stars can be abandoned.
--
Anthony Shipman Mamas don't let your babies
a...@iinet.net.au grow up to be outsourced.
Edmond Begumisa
I don't know about using non-ASCII for actual source-code as the author
suggests. I'm not a language designer so I have no opinion this (though in
relation to this, I've sometimes wondered about alternatives to programing
languages revolving around English -- it must really irritate non-English
speakers, especially those coming from languages using non-latin
alphabets.)
What I would love is very rich and flexible ways of attaching annotations
or "running commentary" to source code. I would think this could be done
without changing the language in question. Probably more of an Editor/IDE
feature than a language feature.
One can envisage some sort of open file format (maybe mark-up based) that
accompanies source code which various editors/IDEs could start
reading+writing to and render next to the actual source code. That would
probably be more acceptable to people and less disruptive.
- Edmond -
On Thu, 09 Dec 2010 02:46:46 +1100, Toby Thain <to...@telegraphics.com.au>
wrote:
> On 08/12/10 10:15 AM, Edmond Begumisa wrote:
>> I've thought -- now and then, in the back of my mind -- about removing
>> comments from actual source all-together ...
>> Also, in the right pane, I've wanted nestable trees with flexible levels
>> of detail. Heck, why not even rich text? "FIX ME" in bold red.
>
> I wonder if you have seen this:
> http://developers.slashdot.org/article.pl?sid=10/10/31/2127201
>
> --Toby
>
>
>> Take it
>> further: login-name awareness, source-control/bug-tracker integration
>> (this programmer said this, that programmer said that.)
>>
>> It seems a shame that in 2010, it's still so limiting what we can do
>> with comments in our source code!
>>
>> - Edmond -
>>
>> On Thu, 09 Dec 2010 01:39:42 +1100, David Mercer <dme...@gmail.com>
>> wrote:
>>
>>> On Tuesday, December 07, 2010, Richard O'Keefe wrote:
>>>
>>>> Nesting comments are one of those clever ideas
>>>> that turn out to be really dumb, because they don't actually work.
>>>
Banibrata Dutta
> wrote:
> I've thought -- now and then, in the back of my mind -- about removing
> comments from actual source all-together (for all languages) and instead,
> putting them in companion files that the editor lines up side-by-side. More
> like annotating than just traditional commenting.
>
>
It's an interesting thought, as it removes clutter -- especially so for a
programmer who is already well versed with the code.
Most modern editors have features allowing the view to show all comments
collapsed, expanded, and some even done so selectively.
> Has this sort of thing been done before? Is there a particular editor that
> can give me this out of the box? (I admittedly haven't explored a large
> number of editors)
>
> Using Erlang as an example, I've secretly wanted something like...
>
> foo.erl
> foo.cts
>
Challenge would be to ensure 100% (fail-proof) lock-step update of the .erl
and .cts files in VCS... ideally triggered from a single command.
Zvi
no need to turn this into religious war and no need to imply that your
process or software engineering practices are better than mine. If
majority of people doesn't like multiline/HEREDOC comments - so be it.
I have no idea, why people imply, that I should use emacs/vim or that
I use multiline comments to comment executable code or that I don't
use git or ClearCase.
Language design usually doesn't have anything to do with editors,
IDEs, DVCS or your organization coding conventions. Unless it's some
kind of exotic language fused into IDE/executable environment.
The reason I posted this is because I found out, that Matlab/Octave
supports this style of comment (%{ ... %}), even that it's IDE has
perfect support for commenting and uncommenting entire sections of
source files with end of line comments (... % COMMENT).
Now Matlab is not the best example of programming language, but I
think in this particular feature they did it right.
Zvi
On Dec 10, 1:21 am, Ryan Zezeski <rzeze...@gmail.com> wrote:
________________________________________________________________
Edmond Begumisa
<banibra...@gmail.com> wrote:
> On Wed, Dec 8, 2010 at 8:45 PM, Edmond Begumisa
> <ebeg...@hysteria-tech.com
>> wrote:
>
>> I've thought -- now and then, in the back of my mind -- about removing
>> comments from actual source all-together (for all languages) and
>> instead,
>> putting them in companion files that the editor lines up side-by-side.
>> More
>> like annotating than just traditional commenting.
>>
>>
> It's an interesting thought, as it removes clutter -- especially so for a
> programmer who is already well versed with the code.
I agree. I've frequently wanted to add more running commentary on a piece
of code then stopped myself because of the verboseness it would introduce.
It would be nice to be able to add comments "on the side" without
affecting the readability/compactness of a function, especially for a
language as terse as Erlang. It would also be nice to be able to do this
with headings-body, nesting/depths and user-name tags (like comments on a
blog) plus richness of content (e.g. many times I've wished I could stick
a PNG diagram from some spec into a comment.)
Treating annotations and source-code as two different (but related) things
might be the answer.
> Most modern editors have features allowing the view to show all comments
> collapsed, expanded, and some even done so selectively.
>
Exactly! This is the concept I would like to see expanded on. Collapsible
annotation. But as pointed out in that article Toby posted, were not
making much use of the space to the right of our editors. That seems like
the perfect place to display comments (of the commentary variety), and
offers potential for some flexibility (e.g. more than one comment could be
placed next to a single line or chunk of code like next to the function
name - hovering the mouse over each heading could then show the detail.)
I also don't like that many editors force me to think about wrapping when
writing English comments (writing English is not the same as writing
code). With the editor split into two panes, code on one side, rich
English/Swedish/Hindi/Chinese/Arabic on the other, different wrapping +
rtl/ltr could be used.
>
>> Has this sort of thing been done before? Is there a particular editor
>> that
>> can give me this out of the box? (I admittedly haven't explored a large
>> number of editors)
>>
>> Using Erlang as an example, I've secretly wanted something like...
>>
>> foo.erl
>> foo.cts
>>
>
> Challenge would be to ensure 100% (fail-proof) lock-step update of the
> .erl
> and .cts files in VCS... ideally triggered from a single command.
>
True. As a VCS user, you'd generally have start thinking of each file as
two files.
Raimo Niskanen
> On Wed, Dec 8, 2010 at 8:45 PM, Edmond Begumisa <ebeg...@hysteria-tech.com
> > wrote:
>
> > I've thought -- now and then, in the back of my mind -- about removing
> > comments from actual source all-together (for all languages) and instead,
> > putting them in companion files that the editor lines up side-by-side. More
> > like annotating than just traditional commenting.
> >
> >
> It's an interesting thought, as it removes clutter -- especially so for a
> programmer who is already well versed with the code.
> Most modern editors have features allowing the view to show all comments
> collapsed, expanded, and some even done so selectively.
>
>
> > Has this sort of thing been done before? Is there a particular editor that
> > can give me this out of the box? (I admittedly haven't explored a large
> > number of editors)
> >
> > Using Erlang as an example, I've secretly wanted something like...
> >
> > foo.erl
> > foo.cts
> >
Many moons ago at Ericsson there was a hiearchical editor named Exco used.
Its concept was that you write your code as a specification where each
heading could be expanded into sub-headings, and at the leaf level
was the source code. Then you pre-processed your Exco document to
extract the leaf level, to compile.
While editing you expanded/compressed headlines (highlited)
with simple keystrokes.
This was in the 24x80 VAX and early Unix days, so side-by-side
panels would have been futile, and color coding was green only.
It would nevertheless be another possibility for your editor suggestion.
Preprocess the readable document to get the source code. You could even
use a specialized comment style in .erl files to get a .erl file that
displays fine in your special editor yet is readable by itself.
--
/ Raimo Niskanen, Erlang/OTP, Ericsson AB
Iñaki Garay
>> > wrote:
>>
>> > I've thought -- now and then, in the back of my mind -- about removing
>> > comments from actual source all-together (for all languages) and instead,
>> > putting them in companion files that the editor lines up side-by-side. More
>> > like annotating than just traditional commenting.
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.
A search for 'erlang literate programming' revealed that Joe
Armstrong has looked into this at some time [0], but I don't know if
it's still active.
[0] http://www.sics.se/~joe/ericsson/literate/literate.html
cheers,
Iñaki Garay.
Jesper Louis Andersen
<ebeg...@hysteria-tech.com> wrote:
> I don't know about using non-ASCII for actual source-code as the author
> suggests. I'm not a language designer so I have no opinion this (though in
> relation to this, I've sometimes wondered about alternatives to programing
> languages revolving around English -- it must really irritate non-English
> speakers, especially those coming from languages using non-latin alphabets.)
If anyone is serious about moving from a ASCII/UTF8 text
representation of programs to something else, *now* is the time to
act. One reason I hate Java with a passion is that the language is
outright impossible to write in Vim or Emacs. You need IDE integration
which severely limits your options. In other words, you are not free
to pick your weapon of choice, but must choose something utterly
inferior like bent spoon or broken stick. Succinctness is power before
it gives you freedom to choose the weapon.
However, most of the weapons we use, be it vim or emacs, are rather
old and this hampers the format by which they can accept code. The
only way to break that problem is the appearance of a disruptive
technology which shuns the norm for something new. In this technology
you can write a collaborative text editor on the web and hopefully
make it as powerful, or more powerful, than emacs or vim. And only
then will there be a new weapon to wield - breaking the text-stream
input norm of programming languages.
And somehow, even with the emerging new devices and systems, I doubt
there is a chance it will happen despite.
--
J.
Masklinn
>>> On Wed, Dec 8, 2010 at 8:45 PM, Edmond Begumisa <ebeg...@hysteria-tech.com
>>>> wrote:
>>>
>>>> I've thought -- now and then, in the back of my mind -- about removing
>>>> comments from actual source all-together (for all languages) and instead,
>>>> 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.
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 [0] which produces literate-style documentation. 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.
[0] http://fitzgen.github.com/pycco/
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
Tony Arcieri
> wrote:
> I've thought -- now and then, in the back of my mind -- about removing
> comments from actual source all-together (for all languages) and instead,
> putting them in companion files that the editor lines up side-by-side. More
> like annotating than just traditional commenting.
You mean like this?
http://jashkenas.github.com/docco/
--
Tony Arcieri
Medioh! Kudelski
Nahuel Greco
--
Sent from my mobile device
Saludos,
Nahuel Greco.
Joe Armstrong
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
>
>
>
>
________________________________________________________________
Masklinn
>
> Wiki text/edoc etc. are just toooo simplistic. I now like xslt-fo more
> than LaTeX
Alain O'Dea
requirements. Check out
https://github.com/AlainODea/simple_cache/commit/0a85f413a85ea589d612c2ab0853ac932626f3a1
to see how I used Otto annotate the interesting bits of a commit I
made. If these GitHub annotations are available in the REST API it
would make for a powerful editor/IDE enhancement.
Richard O'Keefe
On 9/12/2010, at 4:15 AM, Edmond Begumisa wrote:
> I've thought -- now and then, in the back of my mind -- about removing comments from actual source all-together (for all languages) and instead, putting them in companion files that the editor lines up side-by-side. More like annotating than just traditional commenting.
>
> Has this sort of thing been done before? Is there a particular editor that can give me this out of the box? (I admittedly haven't explored a large number of editors)
http://www.xemacs.org/Documentation/beta/html/lispref_52.html
I believe Eclipse and NetBeans also have some kind of annotation support.
For XML documents, Amaya supports the Annotea protocol.
>
> It seems a shame that in 2010, it's still so limiting what we can do with comments in our source code!
_We_, kimosabe?
My strictures against nesting comments do NOT apply to annotated annotations.
Richard O'Keefe
On 13/12/2010, at 8:19 PM, Edmond Begumisa wrote:
> Interesting article.
>
> I don't know about using non-ASCII for actual source-code as the author suggests. I'm not a language designer so I have no opinion this (though in relation to this, I've sometimes wondered about alternatives to programing languages revolving around English -- it must really irritate non-English speakers, especially those coming from languages using non-latin alphabets.)
MADCAP used a non-ASCII character set, including 2d structures.
APL used (and uses) a non-ASCII character set. It has no keywords.
I have seen Algol 60 programs written in French and Chinese.
I've also read Pascal in French (including French keywords)
and seen Simula 67 in Danish.
IBM mainframe compilers have for a long time allowed DBCS (double byte character sets).
Algol 60 was a comparatively straightforward case. Technically, keywords in
that language are single characters, and their rendering as boldface or
underlined English words is just one of many possible hardware representations.
>
> What I would love is very rich and flexible ways of attaching annotations or "running commentary" to source code.
Well, you _could_ use NuWeb, or NoWeb, or FunnelWeb, and add whatever annotations you like.
> I would think this could be done without changing the language in question.
Has very often been done. People have even written programs with commentary in Microsoft Word
and used a VBA macro to strip out and save separately the text with the 'Program' style. I
have my own very simple program for extracting <pre> sections, possibly restricted to a
particular class, from HTML so that
html4.0 foo.htm | pre >foo.erl
can let you extract code from commentary. How simple?
#include <stdio.h>
#include "dvm2.h"
int main(int argc, char **argv) {
char *wanted = argc > 1 ? argv[1] : (char*)0;
xml e0 = load_esis_through(stdin, 0);
int last_was_nl;
for_each_named_descendant(e0, "pre", e1)
if (wanted != 0 && !has_value(e1, "class", wanted)) continue;
last_was_nl = 1;
for_each_text_descendant(e1, e2)
fwrite(text_of(e2), 1, x_size(e2), stdout);
if (x_size(e2) != 0)
last_was_nl = text_of(e2)[x_size(e2)-1] == '\n';
end_each_text_descendant
if (!last_was_nl) putc('\n', stdout);
end_each_named_descendant
return 0;
}
That simple. Doing the same kind of thing using xmerl would be very little harder.
Now you could handle parallel comments in HTML using
<table width="100%">
<col width="50%" align="left"/>
<col width="50%" align="left"/>
<tbody> <!-- repeat for each chunk -->
<tr>
<td><pre>code</pre></td>
<td><p>comments</p></td>
</tr>
</tbody>
</table>
The limit has been our ingenuity, not our tools.\
Richard O'Keefe
On 13/12/2010, at 10:40 PM, Zvi wrote:
> The reason I posted this is because I found out, that Matlab/Octave
> supports this style of comment (%{ ... %}), even that it's IDE has
> perfect support for commenting and uncommenting entire sections of
> source files with end of line comments (... % COMMENT).
> Now Matlab is not the best example of programming language, but I
> think in this particular feature they did it right.
Interestingly, they did it DIFFERENTLY from Modula-2, Lisp, Haskell,
SML, and other languages I know that have nesting comments.
From the MatLab manual:
Block Comments.
To write comments that require more than one line, use the block comment operators, %{ and %}:
%{
This next block of code checks the number of inputs
passed in, makes sure that each input is a valid data
type, and then branches to start processing the data.
%}
Note
The %{ and %} operators must appear alone on the lines that immediately precede and follow
the block of help text. Do not include any other text on these lines.
White space is apparently allowed, but
x = x {% +1 %};
is not legal, and as for
{%
s = '%}';
%}
well, the manual does not make it clear whether this is an error (because there is
other text on the first %} line, or whether the first '%}' line simply is not recognised
as an end-of-comment line.
This is an interesting variation, but it means that these comments are useless
for commenting out subexpressions.
Of course, like every other nesting comment proposal I've ever seen,
this one IS still broken.
Theorem: There exists a valid block of MatLab code such that
adding a '%{' line at the beginning and a '%}' line at the end
does not result in a valid block comment. Further, there exists
such a block that contains no string literals or line continuations.
Proof:
x = 1;
%}
y = 2;
The second line here is a valid end-of-line comment.
As Zvi says, the MatLab IDE *will* comment/uncomment blocks correctly using
end-of-line comments.
Tony Arcieri
> You guys need to take a look to the image-based Smalltalk philosophy.
Smalltalk philosophy is great, but docco is a tool that can generate exactly
this sort of "literate programming" style side-by-side documentation today
from the codebase of many existing languages, including Erlang. Just pump
your Erlang source code through docco and it will spit out documentation
with comments and source code side-by-side.
docco's web site itself is an example of the output docco generates:
Edmond Begumisa
Sounds painful. But then, I've never been one for specs (I've never worked
on humongous projects.)
> While editing you expanded/compressed headlines (highlited)
> with simple keystrokes.
>
> This was in the 24x80 VAX and early Unix days, so side-by-side
> panels would have been futile, and color coding was green only.
>
> It would nevertheless be another possibility for your editor suggestion.
> Preprocess the readable document to get the source code.
Ahh, is see. Work backwards. Extract the source from the markup rather
than the markup from the source. Interesting approach.
It might make source-control a bit tricky though since most tools interact
at the file level (you normally want to know what changes were made to
each source file.) Hmmmm... possibly one could commit only the result of
the preprocessing and not the original mashed documents.
> You could even
> use a specialized comment style in .erl files to get a .erl file that
> displays fine in your special editor yet is readable by itself.
>
Yes, this is an option. Why do I suspect it might be easier for editors to
implement this using two different files? Especially if it's a feature
being tacked on-top of existing code.
For example, if a line is added in the middle of a function, you want a
corresponding change to the annotation. Also, for graphical editors, the
annotation/comment file could be loaded separately into a separate widget
with different features (e.g For Komodo Edit, Mozilla's html editor widget
could come in handy here while the actual source would remain in the
scintilla source-editor widget.)
- Edmond -
--
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/
________________________________________________________________
Edmond Begumisa
Many things are popping into my head at the same time!
- Edmond -
--
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/
________________________________________________________________
Edmond Begumisa
Pycco this looks nice. Rendering wise, it's very close to what I had in
mind.
> 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 -
> [0] http://fitzgen.github.com/pycco/
> ________________________________________________________________
> erlang-questions (at) erlang.org mailing list.
> See http://www.erlang.org/faq.html
> To unsubscribe; mailto:erlang-questio...@erlang.org
>
--
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/
________________________________________________________________
Edmond Begumisa
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 -
--
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/
________________________________________________________________
Edmond Begumisa
wrote:
>
> On 13/12/2010, at 8:19 PM, Edmond Begumisa wrote:
>
>> Interesting article.
>>
>> I don't know about using non-ASCII for actual source-code as the author
>> suggests. I'm not a language designer so I have no opinion this (though
>> in relation to this, I've sometimes wondered about alternatives to
>> programing languages revolving around English -- it must really
>> irritate non-English speakers, especially those coming from languages
>> using non-latin alphabets.)
>
> MADCAP used a non-ASCII character set, including 2d structures.
> APL used (and uses) a non-ASCII character set. It has no keywords.
> I have seen Algol 60 programs written in French and Chinese.
> I've also read Pascal in French (including French keywords)
> and seen Simula 67 in Danish.
> IBM mainframe compilers have for a long time allowed DBCS (double byte
> character sets).
>
> Algol 60 was a comparatively straightforward case. Technically,
> keywords in
> that language are single characters, and their rendering as boldface or
> underlined English words is just one of many possible hardware
> representations.
Educative. Now I can stop wondering :)
>>
>> What I would love is very rich and flexible ways of attaching
>> annotations or "running commentary" to source code.
>
> Well, you _could_ use NuWeb, or NoWeb, or FunnelWeb, and add whatever
> annotations you like.
>
I've had a look. I like these tools. What I don't like is having to go
through a separate generation step to use their output. I think it would
be useful to have these sort of rich annotations for *consumption* in
Editors/IDEs. To be able to both edit and view them while coding.
Also, I'm lazy (this is also why I don't use edoc as much as I should.) I
just want to start typing rich annotations straight into my editor. I want
someone else to take care of the markup. If I have to write markup while
I'm programming, it reduces the chances that I'll adequately comment my
code.
Though we're not really talking about the same thing, I see your point.
- Edmond -
--
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/
________________________________________________________________
Edmond Begumisa
wrote:
>
> On 9/12/2010, at 4:15 AM, Edmond Begumisa wrote:
>
>> I've thought -- now and then, in the back of my mind -- about removing
>> comments from actual source all-together (for all languages) and
>> instead, putting them in companion files that the editor lines up
>> side-by-side. More like annotating than just traditional commenting.
>>
>> Has this sort of thing been done before? Is there a particular editor
>> that can give me this out of the box? (I admittedly haven't explored a
>> large number of editors)
>
> http://www.xemacs.org/Documentation/beta/html/lispref_52.html
AHA!! *This* looks close what I want. Nice :)
I've never been an emacs guy (you either are or your not.) This is a good
excuse to revisit emacs!
>
> I believe Eclipse and NetBeans also have some kind of annotation support.
> For XML documents, Amaya supports the Annotea protocol.
>>
>> It seems a shame that in 2010, it's still so limiting what we can do
>> with comments in our source code!
>
> _We_, kimosabe?
>
> My strictures against nesting comments do NOT apply to annotated
> annotations.
>
I didn't mean to comment on your comment! Just raising something I had
thought about.
- Edmond -
>
> ________________________________________________________________
> erlang-questions (at) erlang.org mailing list.
> See http://www.erlang.org/faq.html
> To unsubscribe; mailto:erlang-questio...@erlang.org
>
--
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/
________________________________________________________________
Edmond Begumisa
(output is not for consumption in the editor.)
Superimpose that screenshot over your favorite editor; imagine being able
to edit the left-panel without writing markup; imagine a few blog-style
comments from your fellow developers then we're onto something.
- Edmond -
On Tue, 14 Dec 2010 13:37:13 +1100, Tony Arcieri <tony.a...@medioh.com>
wrote:
- Edmond -
--
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/
________________________________________________________________
Richard O'Keefe
On 17/12/2010, at 7:39 PM, Edmond Begumisa wrote:
>> Well, you _could_ use NuWeb, or NoWeb, or FunnelWeb, and add whatever annotations you like.
>>
>
> I've had a look. I like these tools. What I don't like is having to go through a separate generation step to use their output. I think it would be useful to have these sort of rich annotations for *consumption* in Editors/IDEs. To be able to both edit and view them while coding.
I note that Haskell supports both the 'Bird tracks' approach to literate programming (where the
codes is the lines beginning with "> " and the annotation is everything else) and a LaTeX
approach (where the code is in special blocks). Whether this is done by the Haskell parser proper
or by a separate preprocessing program is really none of the programmer's business.
I don't quite see what you mean by not having rich annotations for consumption in Editors/IDEs.
One edits the annotated document, not the source code alone. Line numbers in error messages
relate back to the original document, not the source code (this is no different from using
something like Yacc or Happy or Yecc).
>
> Also, I'm lazy (this is also why I don't use edoc as much as I should.) I just want to start typing rich annotations straight into my editor. I want someone else to take care of the markup.
If you are just typing, it is by definition not rich. You have to do *SOMETHING* to provide the
extra information in rich annotations, and whether it is markup like `...` or <foo/.../ or gestural
like Cmd-Option-LeftShift-7 makes little difference.
Robert Raschke
>
> On 17/12/2010, at 7:39 PM, Edmond Begumisa wrote:
> >> Well, you _could_ use NuWeb, or NoWeb, or FunnelWeb, and add whatever
> annotations you like.
> >>
> >
> > I've had a look. I like these tools. What I don't like is having to go
> through a separate generation step to use their output. I think it would be
> useful to have these sort of rich annotations for *consumption* in
> Editors/IDEs. To be able to both edit and view them while coding.
>
>
The point of those tools is that the code you write can be in any order,
specifically the order best suited for exposition.
The likes of JavaDoc and Doxygen essentially killed any attempts at getting
decent Literate Programming tools. This, together with the fact that you
cannot simply go and debug your code using trial and error in the IDE (which
appears to be the crack cocaine for programmers) means that LP will never
take off.
It'll remain something for devotees.
Robby