Re: [R] Block comments in R?
On 10/9/2006 10:06 AM, hadley wickham wrote: >> Current .Rd documentation has some obvious problems: >> >> - the parser strips comments out of examples when it runs them >> - there's no way to put images into the documentation >> - the keywords aren't much use >> - there's isn't a definition anywhere of what the format really is, so >> it's hard to know >> whether something will work other than by trying it -- and it may break >> with the next release. >> - there's no way to link from a help man page to a vignette or other >> form of documentation. > > The main thing I don't like about the current system is the amount of > duplication - you have to supply a lot of information in the > documentation that is also encoded in the function (ie. everything in > the codoc check). This makes it unnecessarily painful when updating > documentation to reflect minor changes. The large distance between > code and documentation also makes it easy to forget to update the > documentation when changing the code. These are things that are > helped by inline documentation (which I am using) Inline documentation isn't the only way to achieve what you want: better editing tools would help too. I don't know if ESS helps with this, but I could imagine a smart editor would be able to help with the updates in each direction. The big problem with this solution is that there is such a variety of editors in use, and most people are convinced that everyone else has made a big mistake in choosing theirs. However, there was talk in the summer about adding more keywords to .Rd files, to expand in various ways. A keyword that expanded to the arg list of a function might be a nice way to avoid duplication. If we had a way to put argument descriptions into the R file it could do a better job, but it would be tricky: e.g. what if the "file" arg in two objects to be documented in the same .Rd had different descriptions? I agree with Richard that we don't want to force separate man pages for every documented object. Duncan Murdoch __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
On 10/9/2006 7:58 PM, Richard A. O'Keefe wrote:
> I wrote:
> > R is, and should remain, editor-neutral.
> > Amongst other things, it should NOT acquire misfeatures
> > in order to support editors that happen not to support comment-region.
> > Block comments are indeed editor-neutral,
> > but they do not solve any problem that R currently has,
> > and they ARE in practice highly error-prone.
>
> Apparently I am *still* failing to communicate, because
> Duncan Murdoch <[EMAIL PROTECTED]> replied:
> I think they are only error-prone in editors that don't recognize them
> and highlight them as comments.
I think you're communicating fine, just failing to convince. You give
examples below where block comments in various languages can give
unexpected results. But I can construct examples in R where prefix
comments give results that are hard to predict unless you know the
parser very well. For example:
a <- "this string contains
# five
words"
Does it really contain five words, or just four? I wouldn't recommend
using code like that, but if I were writing it in a syntax-highlighting
editor that actually worked, it would be very clear to me what the
answer was. As would the examples you give below. Sometimes block
comments fail to correctly surround arbitrary text, but as long as the
user receives immediate feedback, this isn't really a problem.
Duncan Murdoch
>
> There is indeed an error-proneness to do with syntax highlighting
> in editors (specifically vim). However, since "block COMMENTS" are COMMENTS,
> then an editor that DOES recognise them SHOULD highlight them as comments.
> (Because that's what they are.)
>
> But the really major error-proneness I was speaking of has nothing to do
> with editors or highlighting. It is the simple fact that people *will*
> try to use block comments to comment out code, and they just plain don't
> *work* for that job. And part of the problem is that people are trying
> to tackle two very different tasks with the same tool.
>
> Text task:
> Attach a large amount of commentary to a chunk of code,
> the commentary being in some notation *other than* the programming
> language the commentary is embedded in.
>
> For this task, something like
> /* ...
> ...
> ...
> */
> is quite attractive. Some people think it is better to do
> /* ...
>* ...
>* ...
>*/
> but if you are willing to put cruft at the beginning of each
> line, why aren't you willing to use end-of-line comments for this
> purpose?
>
> Block comments do not work reliably for the text task. In fact,
> this is really _the_ major reason why syntax highlighting exists.
> Precisely because the notation in which the comments are written
> is *not* the programming language the commentary is embedded in,
> that notation (be it English, Tagalog, or Etruscan) has no
> particular reason to avoid the magic closing sequence.
>
> This was a nightmare in Algol 60 (where one form of comment, by no
> means the only one, used 'comment' and ';') because ';' was a very
> natural thing to put in English (French, Dutch, ...) text.
>
> It remains a nightmare in C, where one often has occasion to talk
> about files, and of course $LIB/*/*.R is a perfectly natural thing
> to want to mention in a comment.
>
> Code task:
> Given a chunk of code which is temporarily unwanted, hide it from
> the compiler so that it will not be compiled, but leave it present
> in the source file so that it can quickly be recovered.
>
> If you use the *same* block comment brackets for this task as for
> the text task, and if comment brackets do not nest (as they do not
> in PL/I, Pascal, C, ...) then you are in immediate trouble, because
> you cannot use /* ... */ to comment out a chunk of code that contains
> either a text task comment or a code task comment.
>
> If comment brackets do nest, as they do in ML (*...*), Haskell {-...-},
> and Common Lisp #|...|# then you are still in trouble, because nothing
> prevents the code you are trying to comment out containing the magic
> delimiter in a string. For example, if you try to comment out
> (defvar magic-end "|#")
> in Common Lisp, you get
> #|(defvar magic-end "|#")|#
>^^
> which ends too soon. (It is also a problem if the magic starter is
> inside a string.)
>
> To fix this, when the processor processes a nesting comment, it needs
> to understand that it IS processing programming-language text, so that
> it can safely skip strings. But then you cannot use the *same*
> block comments for the code and text tasks.
>
> So if you want to use block comments for the text task, you need
> - nesting comment brackets
> - which are distinct from the brackets used for textual comments.
>
> This i
Re: [R] Block comments in R?
I wrote:
> R is, and should remain, editor-neutral.
> Amongst other things, it should NOT acquire misfeatures
> in order to support editors that happen not to support comment-region.
> Block comments are indeed editor-neutral,
> but they do not solve any problem that R currently has,
> and they ARE in practice highly error-prone.
Apparently I am *still* failing to communicate, because
Duncan Murdoch <[EMAIL PROTECTED]> replied:
I think they are only error-prone in editors that don't recognize them
and highlight them as comments.
There is indeed an error-proneness to do with syntax highlighting
in editors (specifically vim). However, since "block COMMENTS" are COMMENTS,
then an editor that DOES recognise them SHOULD highlight them as comments.
(Because that's what they are.)
But the really major error-proneness I was speaking of has nothing to do
with editors or highlighting. It is the simple fact that people *will*
try to use block comments to comment out code, and they just plain don't
*work* for that job. And part of the problem is that people are trying
to tackle two very different tasks with the same tool.
Text task:
Attach a large amount of commentary to a chunk of code,
the commentary being in some notation *other than* the programming
language the commentary is embedded in.
For this task, something like
/* ...
...
...
*/
is quite attractive. Some people think it is better to do
/* ...
* ...
* ...
*/
but if you are willing to put cruft at the beginning of each
line, why aren't you willing to use end-of-line comments for this
purpose?
Block comments do not work reliably for the text task. In fact,
this is really _the_ major reason why syntax highlighting exists.
Precisely because the notation in which the comments are written
is *not* the programming language the commentary is embedded in,
that notation (be it English, Tagalog, or Etruscan) has no
particular reason to avoid the magic closing sequence.
This was a nightmare in Algol 60 (where one form of comment, by no
means the only one, used 'comment' and ';') because ';' was a very
natural thing to put in English (French, Dutch, ...) text.
It remains a nightmare in C, where one often has occasion to talk
about files, and of course $LIB/*/*.R is a perfectly natural thing
to want to mention in a comment.
Code task:
Given a chunk of code which is temporarily unwanted, hide it from
the compiler so that it will not be compiled, but leave it present
in the source file so that it can quickly be recovered.
If you use the *same* block comment brackets for this task as for
the text task, and if comment brackets do not nest (as they do not
in PL/I, Pascal, C, ...) then you are in immediate trouble, because
you cannot use /* ... */ to comment out a chunk of code that contains
either a text task comment or a code task comment.
If comment brackets do nest, as they do in ML (*...*), Haskell {-...-},
and Common Lisp #|...|# then you are still in trouble, because nothing
prevents the code you are trying to comment out containing the magic
delimiter in a string. For example, if you try to comment out
(defvar magic-end "|#")
in Common Lisp, you get
#|(defvar magic-end "|#")|#
^^
which ends too soon. (It is also a problem if the magic starter is
inside a string.)
To fix this, when the processor processes a nesting comment, it needs
to understand that it IS processing programming-language text, so that
it can safely skip strings. But then you cannot use the *same*
block comments for the code and text tasks.
So if you want to use block comments for the text task, you need
- nesting comment brackets
- which are distinct from the brackets used for textual comments.
This is one of the few things that C gets right, although a sickening
number of C programmers get it wrong. C has /*..*/ for the text task
and #if 0 #endif for the code task. The standard says clearly that
the stuff bracketed by #if 0 ... #endif is code, not text.
So anyone who wants to add block comments to R had better figure out
exactly _why_ they want to do this, because if they really want to handle
both the text task and the code task the comment system they end up with
will NOT be one that is familiar to most programmers. (As noted, most C
programmers haven't really understood that /*...*/ shouldn't be used for
code.)
R source code is mostly C, which only supports block comments (using
the
strict compiler options we use);
End-of-line comments were added to C++, and subsequently to C99 (hey, it's
seven years since C99 came out; haven't we waited long enough for this Rachel?)
because block comments are so broken.
_
Re: [R] Block comments in R?
Apparently misunderstanding me, On 10/8/06, Richard A. O'Keefe <[EMAIL PROTECTED]> wrote: > Amongst other things, it should NOT acquire misfeatures > in order to support editors that happen not to support comment-region. ... One can only comment from one's experience. We have found the concept of inline documentation, and block comments in specific, to be very valuable in our work. Indeed I cannot think of a problem caused by this practice, but I can think of many problems caused by the absence of such practice. jab -- John Bollinger, CFA, CMT www.BollingerBands.com If you advance far enough, you arrive at the beginning. __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
On 10/9/06, hadley wickham <[EMAIL PROTECTED]> wrote: > > Current .Rd documentation has some obvious problems: > > > > - the parser strips comments out of examples when it runs them > > - there's no way to put images into the documentation > > - the keywords aren't much use > > - there's isn't a definition anywhere of what the format really is, so > > it's hard to know > > whether something will work other than by trying it -- and it may break > > with the next release. > > - there's no way to link from a help man page to a vignette or other > > form of documentation. > > The main thing I don't like about the current system is the amount of > duplication - you have to supply a lot of information in the > documentation that is also encoded in the function (ie. everything in > the codoc check). This makes it unnecessarily painful when updating > documentation to reflect minor changes. The large distance between > code and documentation also makes it easy to forget to update the > documentation when changing the code. These are things that are > helped by inline documentation (which I am using) > > Hadley The biggest problem I find with the current system is that the error or warning messages in R CMD check often leave you without a good idea of where the problem occurred and one is left removing half the package and dividing successively until its found. __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
> Current .Rd documentation has some obvious problems: > > - the parser strips comments out of examples when it runs them > - there's no way to put images into the documentation > - the keywords aren't much use > - there's isn't a definition anywhere of what the format really is, so > it's hard to know > whether something will work other than by trying it -- and it may break > with the next release. > - there's no way to link from a help man page to a vignette or other > form of documentation. The main thing I don't like about the current system is the amount of duplication - you have to supply a lot of information in the documentation that is also encoded in the function (ie. everything in the codoc check). This makes it unnecessarily painful when updating documentation to reflect minor changes. The large distance between code and documentation also makes it easy to forget to update the documentation when changing the code. These are things that are helped by inline documentation (which I am using) Hadley __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
On 10/8/2006 8:03 PM, Richard A. O'Keefe wrote:
> Apparently misunderstanding the argument,
> BBands <[EMAIL PROTECTED]> wrote:
> Should R be editor specific? Or should it be editor neutral?
>
> R is, and should remain, editor-neutral.
> Amongst other things, it should NOT acquire misfeatures
> in order to support editors that happen not to support comment-region.
>
> In my view blocks comments are a desirable, editor-neutral approach.
>
> Block comments are indeed editor-neutral,
> but they do not solve any problem that R currently has,
> and they ARE in practice highly error-prone.
I think they are only error-prone in editors that don't recognize them
and highlight them as comments. Some editors support comment-region,
some don't; some highlight block comments properly, some don't. The
editors built into R don't handle either of these.
R source code is mostly C, which only supports block comments (using the
strict compiler options we use); it also includes Fortran, which only
supports prefix comments, Perl with both types, Bourne shell code with
prefixes, and some others (including S, of course).
So R users are likely familiar with both styles of comments, and they
probably have their own preferred style. I don't think it's urgent to
support both, but it would likely make some peoples' work easier, and
wouldn't hurt anyone else too much.
Duncan Murdoch
>
> Note that most of the more recent languages have some form of block
> comment capability.
>
> http://en.wikipedia.org/wiki/Comment#Summary
>
> That list is not a list of "more recent languages"; it is a list containing
> both old languages and new ones. Some of the entries (such as the one for
> Algol 60), are clearly wrong. (In fact the Algol one is doubly wrong,
> because the language always was Algol, not ALGOL.) So is the Scheme entry
> wrong: there are no block comments in any official version of Scheme and
> never have been. The list is missing Burroughs Algol (% end of line
> comments), Prolog (%...\n and /*...*/), Pop-2 (!...! or !...\n), and many
> others. If you want to be pedantic, the list is technically wrong about
> C and C++. We also find COBOL, with some interesting variants, missing.
> Texinfo is another one that's wrong. Quite a lot of entries are wrong.
> If "more recent languages" just means languages that are still in use,
> it's a pity APL isn't there; the APL "lamp" character (comments are supposed
> to be illuminating, no?) U+235D is cute.
>
> We find
> - languages which have copied PL/I (/* ... */)
> - languages which have copied BCPL (//)
> - languages which have copied Pascal (* ... *)
> - languages which have copied sh (#)
> - languages which have copied Burroughs Algol (%)
> - Fortran (only ever end-of-line comments, first C and now !)
> - BASIC (only end-of-line ' and REM comments, and you would certainly
> have to call VB.net "recent")
> - eclectic languages
>
> - languages designed for high reliability, notably Ada and Eiffel (--)
>
> Basically, most language designers have pretty much blindly followed
> designs from the 1960s, with the notable exception of Ada and Eiffel.
>
> The Haskell experience is instructive. The Haskell designers thought they
> could put in nesting block comments {-...-} and make them work. But it
> took several iterations of fiddling with the details, and they *still*
> don't work in every case.
>
> __
> R-help@stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
"Richard A. O'Keefe" <[EMAIL PROTECTED]> writes:
> We find
> - languages which have copied PL/I (/* ... */)
> - languages which have copied BCPL (//)
> - languages which have copied Pascal (* ... *)
Not to stick my head further into the discussion at this point, but
actually, original Pascal has {...} for comments. The diglyphs (* and
*) were used on systems like Pascal 1100 in Copenhagen, where the
UNIVAC "Fieldata" 6-bit (!) character set didn't contain curlies. (We
also used (. .) for array indexing because [\] had been replaced by
Danish characters.)
> - languages which have copied sh (#)
> - languages which have copied Burroughs Algol (%)
> - Fortran (only ever end-of-line comments, first C and now !)
> - BASIC (only end-of-line ' and REM comments, and you would certainly
> have to call VB.net "recent")
> - eclectic languages
>
> - languages designed for high reliability, notably Ada and Eiffel (--)
--
O__ Peter Dalgaard Øster Farimagsgade 5, Entr.B
c/ /'_ --- Dept. of Biostatistics PO Box 2099, 1014 Cph. K
(*) \(*) -- University of Copenhagen Denmark Ph: (+45) 35327918
~~ - ([EMAIL PROTECTED]) FAX: (+45) 35327907
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
Apparently misunderstanding the argument,
BBands <[EMAIL PROTECTED]> wrote:
Should R be editor specific? Or should it be editor neutral?
R is, and should remain, editor-neutral.
Amongst other things, it should NOT acquire misfeatures
in order to support editors that happen not to support comment-region.
In my view blocks comments are a desirable, editor-neutral approach.
Block comments are indeed editor-neutral,
but they do not solve any problem that R currently has,
and they ARE in practice highly error-prone.
Note that most of the more recent languages have some form of block
comment capability.
http://en.wikipedia.org/wiki/Comment#Summary
That list is not a list of "more recent languages"; it is a list containing
both old languages and new ones. Some of the entries (such as the one for
Algol 60), are clearly wrong. (In fact the Algol one is doubly wrong,
because the language always was Algol, not ALGOL.) So is the Scheme entry
wrong: there are no block comments in any official version of Scheme and
never have been. The list is missing Burroughs Algol (% end of line
comments), Prolog (%...\n and /*...*/), Pop-2 (!...! or !...\n), and many
others. If you want to be pedantic, the list is technically wrong about
C and C++. We also find COBOL, with some interesting variants, missing.
Texinfo is another one that's wrong. Quite a lot of entries are wrong.
If "more recent languages" just means languages that are still in use,
it's a pity APL isn't there; the APL "lamp" character (comments are supposed
to be illuminating, no?) U+235D is cute.
We find
- languages which have copied PL/I (/* ... */)
- languages which have copied BCPL (//)
- languages which have copied Pascal (* ... *)
- languages which have copied sh (#)
- languages which have copied Burroughs Algol (%)
- Fortran (only ever end-of-line comments, first C and now !)
- BASIC (only end-of-line ' and REM comments, and you would certainly
have to call VB.net "recent")
- eclectic languages
- languages designed for high reliability, notably Ada and Eiffel (--)
Basically, most language designers have pretty much blindly followed
designs from the 1960s, with the notable exception of Ada and Eiffel.
The Haskell experience is instructive. The Haskell designers thought they
could put in nesting block comments {-...-} and make them work. But it
took several iterations of fiddling with the details, and they *still*
don't work in every case.
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
Rolf Turner wrote: > I must say I agree with Richard O'Keefe who wrote: > > >> I wrote: >> R documentation comments really belong >> in [.Rd] files where help() can find them. >> >> Barry Rowlingson <[EMAIL PROTECTED]> replied: >> R documentation comments belong in .Rd files at the moment, but how >> joyous would it be if they could be included in the .R files? >> >> How joyous? About as joyous as a root canal job without anaesthetic. >> > > > > > (a) I don't speak Python and I don't believe I ever will; I'm > not sure what Python does; I don't want to know. R does what > I want to do. I don't want to have to learn Python syntax to > do something with which I am very happy doing the R way > currently. > To be fair, I don't think anyone proposed that. As I read it, the suggestion was to take Python's idea of inline documentation into R, not necessarily an identical implementation. > (b) Modularity is a ***Good Thing***. Code should be code, > documentation should be documentation. They should click > together but be kept separate. > I tend to like comments in code. Rd-style documentation has a different purpose, but not all that different. I tend not to put so many comments into my R code because I spend the time writing .Rd files, but then it's inconvenient to see the docs when I'm working on the code. > (c) The R documentation system is neat, efficient, well > thought out, and well constructed. It is an intrinsic part > of the nature of R. (It's one of the --- many --- reasons I > like R better than Splus, which I no longer use.) Changing > the R documentation system to something (Monty?) Pythonesque > would change the nature of R and make it uglier. > I'd rather wait to see an actual proposal before I decided if it was uglier or more beautiful. Current .Rd documentation has some obvious problems: - the parser strips comments out of examples when it runs them - there's no way to put images into the documentation - the keywords aren't much use - there's isn't a definition anywhere of what the format really is, so it's hard to know whether something will work other than by trying it -- and it may break with the next release. - there's no way to link from a help man page to a vignette or other form of documentation. None of these would be addressed by inline help, but other people may have other complaints. I think it was DSC 2001 where R Core decided to replace the .Rd system with something better; I would say it's a reasonable prediction that that won't happen soon, but incremental improvements to .Rd have happened, and we should think about other ones. Duncan Murdoch __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
I must say I agree with Richard O'Keefe who wrote: > I wrote: > R documentation comments really belong > in [.Rd] files where help() can find them. > > Barry Rowlingson <[EMAIL PROTECTED]> replied: > R documentation comments belong in .Rd files at the moment, but how > joyous would it be if they could be included in the .R files? > > How joyous? About as joyous as a root canal job without anaesthetic. (a) I don't speak Python and I don't believe I ever will; I'm not sure what Python does; I don't want to know. R does what I want to do. I don't want to have to learn Python syntax to do something with which I am very happy doing the R way currently. (b) Modularity is a ***Good Thing***. Code should be code, documentation should be documentation. They should click together but be kept separate. (c) The R documentation system is neat, efficient, well thought out, and well constructed. It is an intrinsic part of the nature of R. (It's one of the --- many --- reasons I like R better than Splus, which I no longer use.) Changing the R documentation system to something (Monty?) Pythonesque would change the nature of R and make it uglier. cheers, Rolf __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
I wrote:
R documentation comments really belong
in [.Rd] files where help() can find them.
Barry Rowlingson <[EMAIL PROTECTED]> replied:
R documentation comments belong in .Rd files at the moment, but how
joyous would it be if they could be included in the .R files?
How joyous? About as joyous as a root canal job without anaesthetic.
I used to be a fan of including thorough documentation in code.
Then JavaDoc hit the world, and many of the languages I use are following
suit with their own EDoc or PlDoc or whateverDoc mess.
I have read far more Java than I ever wanted to, and the more Java I read
the more I *hate* JavaDoc, and the more I am convinced that if you want
to mix documentation and code you need *really* sophisticated tools (like
Web in its various incarnations) or really simple tools (like Haskell's
"Bird Tracks", a notation I have adapted to my own use for several other
languages).
.Rd files are semisophisticated; if JavaDoc is a reliable guide, then
shoving that stuff into .R files would be horrible.
Do I need to point out the single biggest difference between JavaDoc
and .Rd? Maybe I do. .Rd files are *USEFUL*. (Because of references,
examples, consistency checking, &c, and because they can describe closely
related GROUPS of functions rather than being nailed to specific methods.
The right documentation about the right topics at the right level of
detail.) JavaDoc-style documentation seems to systematically encourage
bulky documentation of low utility.
Okay, this is all part of my incessant whining to make R more like
Python, but I've found managing separate .Rd and .R files a pain. If .R
files could have embedded documentation you'd have one source for code,
documentation, tests etc. I did play about with this in the Splus days,
attaching documentation strings to functions with attributes, but it
was
just kludgy without a proper mechanism.
Let me point out that right now there is NOTHING stopping anyone mixing
.Rd and .R and test cases as they wish. How? Here's how:
$poomat.1
.TH POOMAT 1 "Oct 2006" "Version 1.0" "USER COMMANDS"
.SH NAME
poomat - poor man's Tangle
.SH SYNOPSIS
.B poomat
file ...
.SH DESCRIPTION
.B poomat
extracts several interleaved files (such as documentation,
source code, and test cases) from a single file. You can
pack several files together using shell archives, tar files,
or ZIP files, but those are distribution formats, not meant
to be edited as single files.
.B poomat
lets you scatter a file in pieces, interleaved with other
pieces, so that a function, the documentation for the function,
and the test cases for the function can all be in one place.
.SH OPTIONS
None.
.B poomat
concatenates its input files just like
.IR cat (1)
or
.IR awk (1)
and writes to files named in the input.
.SH INPUT LANGUAGE
The input to
.B poomat
is a sequence of chunks. Each chunk is introduced by a line
consisting of a dollar sign in column 1, immediately followed
by a file name. The first chunk for any file name creates a
new file; remaining chunks for the same file are appended to it.
.SH BUGS
Unlike
.IR tangle (1),
.IR ctangle (1),
and other Literate Programming tools, there is no facility for
re-ordering chunks. Nor is there any macro facility.
.PP
It is up to you to make sure that the file names are portable.
Stick to 8.3 file names without any directory affixes and you
should be right.
$INSTALL
Edit the first line of the poomat file to refer to the right
version of awk (nawk, gawk, mawk) for your system, and then
move the poomat file to some directory in your $PATH.
$poomat
#!/usr/ucb/nawk -f
BEGIN { output = "/dev/stdout" }
/^[$]/ { output = substr($0, 2); next }
{ print >output }
Yes, I do mean the whole thing is a three-line AWK script.
Yes, I do mean it is language-independent, and doesn't NEED to be built
into R or anything else.
Yes, I do mean that the source code, documentation, and test cases get
separated as part of the build process. So?
For people interested in doing stuff like that with C or C++, it really
doesn't take a lot of work to make poomat notice a
/[.][chCH][pxPX+]?[pxPX+]?$/ suffix and emit a #line directive.
OK, here it is:
/^[$]/ {
output = substr($0, 2)
if (/[.][chCH][pxPX+]?[pxPX+]?$/)
print "#line", FNR+1, "\"" FILENAME "\"" >output
next
}
So your C or C++ debugger can refer back to the original file.
Maybe that should be in the official version, but R doesn
Re: [R] Block comments in R?
Hi all, Indeed, block comment is more clean and elegant than line by line. If the R interpreter will recognizes it (I'm not sure if already recognizes), we will spend no more than few hours to make the syntax of the main editors compatible, isn't it? Regards, -- Jose Claudio Faria Brasil/Bahia/Ilheus/UESC/DCET Estatística Experimental/Prof. Adjunto mails: [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] tel: 73-3634.2779 __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
"And of course vim, emacs, nedit, tinn-r..." Should R be editor specific? Or should it be editor neutral? In my view blocks comments are a desirable, editor-neutral approach. Note that most of the more recent languages have some form of block comment capability. http://en.wikipedia.org/wiki/Comment#Summary jab -- John Bollinger, CFA, CMT www.BollingerBands.com If you advance far enough, you arrive at the beginning. __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
Cool, didn't know that! Thanks, Stefano On Fri, Oct 06, 2006 at 01:46:03PM +0200, Martin Maechler wrote: Stefano> To uncomment Ctrl-x r d well, if we really talk emacs --- we shouldn't here -- you definitely should learn to use M-; It does use "##" in ESS (as you should for "full line comments") Martin -- Stefano Calza, PhD Researcher - Biostatistician *Sezione di Statistica Medica e Biometria Dipartimento di Scienze Biomediche e Biotecnologie Università degli Studi di Brescia - Italy Viale Europa, 11 25123 Brescia email: [EMAIL PROTECTED] Phone: +390303717653 Fax: +390303717488 *Dept. Medical Epidemiology and Biostatistics (MEB) Karolinska Institutet, SE-17177 Stockholm Sweden phone:+46-8-524 82279 Civilization is the limitless multiplication of unnecessary necessities. -- Mark Twai __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
> "Stefano" == Stefano Calza <[EMAIL PROTECTED]> > on Fri, 6 Oct 2006 12:55:38 +0200 writes: Stefano> And of course in emacs you can select the region to comment then hit Stefano> Ctrl-x r t and type #: all the lines in that region will have a # at the Stefano> beginnig Stefano> To uncomment Ctrl-x r d well, if we really talk emacs --- we shouldn't here -- you definitely should learn to use M-; It does use "##" in ESS (as you should for "full line comments") Martin Stefano> Stefano __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
> > Commenting code out and providing documentation comments are easily > > done with a good editor, although R documentation comments really belong > > in files where help() can find them. > > R documentation comments belong in .Rd files at the moment, but how > joyous would it be if they could be included in the .R files? This is how I do al my package documentation, using a home-made comment parser based on javadoc. It doesn't cover all situations, but it works well enough for me, and has dramatically increased the quanity and quality of documentation that I write. Hadley __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
And of course in emacs you can select the region to comment then hit
Ctrl-x r t and type #: all the lines in that region will have a # at the
beginnig
To uncomment Ctrl-x r d
Stefano
On Fri, Oct 06, 2006 at 07:05:52PM -0400, Jim Lemon wrote:
And of course for NEdit, all one needs to do is select:
Preferences | Default Settings | Customize menus | Macro Menu
Then select the "New" option at the top of the menu list,
Give it a name (I call this r_comment),
Enter the following code:
replace_in_selection("^","#","regex")
click on "Apply" and then "OK"
You will have an item named "r_comment" on your macro menu
Simply select the area you wish to comment out and run the macro.
To remove comments, you can program another macro (r_nocomment)
replace_in_selection("#","")
You can give both of these a keystroke invocation if you wish.
Happy commenting!
Jim
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide
http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
Note that if you only have block comments in a language, its much harder to do this: http://www.xkcd.com/c156.html Barry __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
Richard A. O'Keefe wrote: > > Commenting code out and providing documentation comments are easily > done with a good editor, although R documentation comments really belong > in files where help() can find them. R documentation comments belong in .Rd files at the moment, but how joyous would it be if they could be included in the .R files? Okay, this is all part of my incessant whining to make R more like Python, but I've found managing separate .Rd and .R files a pain. If .R files could have embedded documentation you'd have one source for code, documentation, tests etc. I did play about with this in the Splus days, attaching documentation strings to functions with attributes, but it was just kludgy without a proper mechanism. Is there an R 3.0 roadmap? Barry __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
And of course for NEdit, all one needs to do is select:
Preferences | Default Settings | Customize menus | Macro Menu
Then select the "New" option at the top of the menu list,
Give it a name (I call this r_comment),
Enter the following code:
replace_in_selection("^","#","regex")
click on "Apply" and then "OK"
You will have an item named "r_comment" on your macro menu
Simply select the area you wish to comment out and run the macro.
To remove comments, you can program another macro (r_nocomment)
replace_in_selection("#","")
You can give both of these a keystroke invocation if you wish.
Happy commenting!
Jim
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
Please let's not waste any time trying to figure out how to add block comments to R. In any guise they are highly error prone. Although its precursors (PL/I and Pascal) had block comments and did not have end-of-line comments, the programming language Ada was explicitly designed to have end-of-line comments and not block comments, as block comments were thought too easy to write incorrectly and too easy to misread. As just one example, the version of vim I have does syntax highlighting, BUT "Vim doesn't parse the whole file", so if you have code in the middle of a block comment it may be highlighed incorrectly. Commenting code out and providing documentation comments are easily done with a good editor, although R documentation comments really belong in files where help() can find them. In the text editor I use, comment-region (using end-of-line comments) and uncomment-region (ditto) are just two keystrokes each; it's LESS effort than writing block comment delimiters would be. Also, when writing a big comment, the newline key automatically copies *( *)? to the beginning of a new line, so again it is less typing to make a block comment using end-of-line comments than /* ... */ or anything like that, and of course fill-paragraph and justify-paragraph (two keystrokes each) can cope with the comment marks (a change from lines with comment marks to ones without, or vice versa, constitutes a paragraph break). __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
+1 for Python style comments. """ your comments here and some more ... and some related info """ jab -- John Bollinger, CFA, CMT www.BollingerBands.com If you advance far enough, you arrive at the beginning. __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
There are two places that I find the current way it works to be
less than ideal although its not that bad either:
1 .when one wants to define strings that have quotes then
one must be careful to use double quoted strings to contain
single quotes and single quoted strings to contain double quotes
or if one needs both then one is into the complexities of multiple
backslashes. Enhancing sQuote and dQuote might help somewhat
in this regards to allow them to be used in more situations but
having an extended syntax might be the best.
2. Sometime I like to define a file inline so that it is
defined like this:
Lines <- "1 2
3 4"
read.table(textConnection(Lines))
I haven't hit the size limit on the character string yet (I usually do this
with small config style files) but suspect that I may if I start using this
for data. What is the limit anyways?
On 10/5/06, Martin Maechler <[EMAIL PROTECTED]> wrote:
> > "Duncan" == Duncan Murdoch <[EMAIL PROTECTED]>
> > on Thu, 05 Oct 2006 11:13:03 -0400 writes:
>
>Duncan> On 10/5/2006 10:57 AM, Martin Maechler wrote:
>>>
>>> <##
>>> ...
>>> ##>
>>>
>>> but I'm not yet fond of the general idea.
>>> Martin
>
>Duncan> Is that just because you don't need it, or that you see something
>Duncan> objectionable in it?
>
> The combination: It complicates the S language (slightly) which
> I think is "too expensive" given that I don't see the need for
> it ("smart editors ..."; if(FALSE) { .. }).
>
> {But my feelings are not very strong here probably mostly
> because I haven't thought very long about it.}
>
> Martin
>
> __
> R-help@stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.
>
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
> "Duncan" == Duncan Murdoch <[EMAIL PROTECTED]>
> on Thu, 05 Oct 2006 11:13:03 -0400 writes:
Duncan> On 10/5/2006 10:57 AM, Martin Maechler wrote:
>>
>> <##
>> ...
>> ##>
>>
>> but I'm not yet fond of the general idea.
>> Martin
Duncan> Is that just because you don't need it, or that you see something
Duncan> objectionable in it?
The combination: It complicates the S language (slightly) which
I think is "too expensive" given that I don't see the need for
it ("smart editors ..."; if(FALSE) { .. }).
{But my feelings are not very strong here probably mostly
because I haven't thought very long about it.}
Martin
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
Seth Falcon wrote: > > My wtf feature request is to add a multiline string delimiter ala > Python like """. > Anything that makes R more like Python syntax gets a +1 from me. How about getting rid of curly brackets for blocks and using indenting in R? Time to attack gram.y with a sledgehammer... Barry __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
On 10/5/2006 10:57 AM, Martin Maechler wrote: > > <## > ... > ##> > > but I'm not yet fond of the general idea. > Martin Is that just because you don't need it, or that you see something objectionable in it? Duncan Murdoch __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
> "PD" == Peter Dalgaard <[EMAIL PROTECTED]> > on 05 Oct 2006 16:12:50 +0200 writes: PD> Seth Falcon <[EMAIL PROTECTED]> writes: >> Uwe Ligges <[EMAIL PROTECTED]> writes: >> > Use an editor that comments out a whole block which is what I do all the >> > time, e.g. use Tinn-R, Emacs or WinEdt, to mention just a few of >> > them. >> >> This, of course, works. The if(FALSE) approach does not because it >> requires the "comment" to be syntactically correct. The multiline >> string trick is _almost_ there, the problem is that both " and ' are >> fairly common in text and having to escape that is a pain. >> >> My wtf feature request is to add a multiline string delimiter ala >> Python like """. PD> Still gives you problems with nested comments. *IF* we want to go down PD> that route, we should have directional symbols like PD> <<< PD> dsaldfysdfk PD> (which would likely drive version control users up the wall...) i.e. all of R-core ... PD> or PD> /# kdlsfk PD> dfkjsdfl #/ PD> (but those character combinations have a marginal risk of being used PD> in existing code). or <## ... ##> but I'm not yet fond of the general idea. Martin PD> -- PD> O__ Peter Dalgaard Øster Farimagsgade 5, Entr.B PD> c/ /'_ --- Dept. of Biostatistics PO Box 2099, 1014 Cph. K PD> (*) \(*) -- University of Copenhagen Denmark Ph: (+45) 35327918 PD> ~~ - ([EMAIL PROTECTED]) FAX: (+45) 35327907 __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
> Still gives you problems with nested comments. *IF* we want to go down > that route, we should have directional symbols like > > <<< > dsaldfysdfk > >>> What about heredocs? (http://en.wikipedia.org/wiki/Heredoc) Hadley __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
Seth Falcon <[EMAIL PROTECTED]> writes: > Uwe Ligges <[EMAIL PROTECTED]> writes: > > Use an editor that comments out a whole block which is what I do all the > > time, e.g. use Tinn-R, Emacs or WinEdt, to mention just a few of > > them. > > This, of course, works. The if(FALSE) approach does not because it > requires the "comment" to be syntactically correct. The multiline > string trick is _almost_ there, the problem is that both " and ' are > fairly common in text and having to escape that is a pain. > > My wtf feature request is to add a multiline string delimiter ala > Python like """. Still gives you problems with nested comments. *IF* we want to go down that route, we should have directional symbols like <<< dsaldfysdfk >>> (which would likely drive version control users up the wall...) or /# kdlsfk dfkjsdfl #/ (but those character combinations have a marginal risk of being used in existing code). -- O__ Peter Dalgaard Øster Farimagsgade 5, Entr.B c/ /'_ --- Dept. of Biostatistics PO Box 2099, 1014 Cph. K (*) \(*) -- University of Copenhagen Denmark Ph: (+45) 35327918 ~~ - ([EMAIL PROTECTED]) FAX: (+45) 35327907 __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
Uwe Ligges <[EMAIL PROTECTED]> writes: > Use an editor that comments out a whole block which is what I do all the > time, e.g. use Tinn-R, Emacs or WinEdt, to mention just a few of > them. This, of course, works. The if(FALSE) approach does not because it requires the "comment" to be syntactically correct. The multiline string trick is _almost_ there, the problem is that both " and ' are fairly common in text and having to escape that is a pain. My wtf feature request is to add a multiline string delimiter ala Python like """. 8-P + seth __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
Robin Hankin wrote:
>
> On 5 Oct 2006, at 10:05, Uwe Ligges wrote:
>
>>
>>
>> Wee-Jin Goh wrote:
>>> Hello list,
>>>
>>> Is there any way to perform a block comment in R? In C++, anything in
>>> between a /* and */ is considered a comment, and it allows
>>> programmers to comment out chunks of code for testing and debugging.
>>> Is there such a feature in R?
>>
>>
>> This has frequently been asked on the list. Try to google for it. You
>> will find answers like
>>
>> if(FALSE){"
>> code block
>> commented
>> "}
>>
>>
>
>
> That method doesn't work for me:
>
> if(FALSE){"
>
> if(1<2)
> print("1<2")
> else
> print("1>2")
>
> "}
Use an editor that comments out a whole block which is what I do all the
time, e.g. use Tinn-R, Emacs or WinEdt, to mention just a few of them.
Or you can go ahead and use
if(FALSE){
if(1<2)
print("1<2")
else
print("1>2")
}
or
if(FALSE){'
if(1<2)
print("1<2")
else
print("1>2")
'}
Uwe
>
> returns an error. How would I comment out that block of (incorrect) code?
>
>
>
>
>
>
>
>> or "use a good editor that supports commenting and uncommenting blocks".
>>
>>
>> Uwe Ligges
>>
>>
>
> --
> Robin Hankin
> Uncertainty Analyst
> National Oceanography Centre, Southampton
> European Way, Southampton SO14 3ZH, UK
> tel 023-8059-7743
>
>
>
>
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
On 5 Oct 2006, at 10:05, Uwe Ligges wrote:
>
>
> Wee-Jin Goh wrote:
>> Hello list,
>>
>> Is there any way to perform a block comment in R? In C++, anything in
>> between a /* and */ is considered a comment, and it allows
>> programmers to comment out chunks of code for testing and debugging.
>> Is there such a feature in R?
>
>
> This has frequently been asked on the list. Try to google for it. You
> will find answers like
>
> if(FALSE){"
> code block
> commented
> "}
>
>
That method doesn't work for me:
if(FALSE){"
if(1<2)
print("1<2")
else
print("1>2")
"}
returns an error. How would I comment out that block of (incorrect)
code?
> or "use a good editor that supports commenting and uncommenting
> blocks".
>
>
> Uwe Ligges
>
>
--
Robin Hankin
Uncertainty Analyst
National Oceanography Centre, Southampton
European Way, Southampton SO14 3ZH, UK
tel 023-8059-7743
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Re: [R] Block comments in R?
Wee-Jin Goh wrote:
> Hello list,
>
> Is there any way to perform a block comment in R? In C++, anything in
> between a /* and */ is considered a comment, and it allows
> programmers to comment out chunks of code for testing and debugging.
> Is there such a feature in R?
This has frequently been asked on the list. Try to google for it. You
will find answers like
if(FALSE){"
code block
commented
"}
or "use a good editor that supports commenting and uncommenting blocks".
Uwe Ligges
> Cheers,
> Wee-Jin
>
> __
> R-help@stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
[R] Block comments in R?
Hello list, Is there any way to perform a block comment in R? In C++, anything in between a /* and */ is considered a comment, and it allows programmers to comment out chunks of code for testing and debugging. Is there such a feature in R? Cheers, Wee-Jin __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
