[Rd] documentation for 'open': some clarification?

[Prof Brian Ripley]

On Thu, 14 Apr 2005, Na Li wrote:

>
> I'm been doing more and more of file text parsing inside R instead of
> coping with Perl.  For that, I need open a file and read it line-by-line.
> I found the documentation for 'open' isn't very clear.

You appears to have missed almost all the documentation.

> Right now it has
>
> ,----[ *help(R)[open]* ]
> |  'open' opens a connection.  In general functions using connections
> |  will open them if they are not open, but then close them again, so
> |  to leave a connection open call 'open' explicitly.
> `----
>
> It seems that one has to call 'open' to open a live connection that can be
> parsed line by line (using readLines() or scan() to read).  But open()
> cannot be directly applied to a file name.

Not surprising, as it is documented as

      open(con, ...)
      ## S3 method for class 'connection':
      open(con, open = "r", blocking = TRUE, ...)

      con: a connection.
            ^^^^^^^^^^^

> In fact, one only needs supply the 'open' argument in file() with
> something other than the empty string,

Or use 'open(con)', but you are asking about the usage of something that 
you never need to use, as should have been clear from all the examples, 
e.g. those in ?readBin (which is in the SeeAlso) that get on fine without 
it.

> ,----
> | > con <- file ("S200.dat")
> | > isOpen (con)
> | [1] FALSE
> | > con <- file ("S200.dat", open = "r")
> | > isOpen (con)
> | [1] TRUE
> `----
>
> It is not clear to me how 'open()' is supposed to be used.  It took me a
> while to figure this out

Have you figured it out?

> and I thought it might be worthwhile to add one
> sentence or two to make it more clear in the doc.

Help pages are not tutorials: there is a reference on the help page, and 
an article in R-news.  (I have raised several times the idea of a 
technical papers section with such articles, but other do not share my 
enthusiasm.)

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595