[Rd] Documentation: format of read.table help text (PR#14180)

[William Dunlap]

> -----Original Message-----
> From: r-devel-bounces at r-project.org 
> [mailto:r-devel-bounces at r-project.org] On Behalf Of 
> henrik.parn at bio.ntnu.no
> Sent: Monday, January 11, 2010 7:10 AM
> To: r-devel at stat.math.ethz.ch
> Cc: R-bugs at r-project.org
> Subject: [Rd] Documentation: format of read.table help text (PR#14180)
> 
> Dear R developers,
> 
> I find the format of descriptions of the arguments in the read.table 
> help text slightly inconsistent.
> 
> For example, the logical arguments comes in seven different formats, 
> more or less explicit about the consequences of a TRUE (or FALSE):
> 
> 1. check.names 	logical. If TRUE then the names...
> 2. blank.lines.skip  logical: if TRUE blank lines...
> 3. flush 	logical: if TRUE, scan...
> 
> 4. header 	a logical value indicating whether...
> 
> 5. allowEscapes 	logical. Should C-style [...] ?
> 6. stringsAsFactors logical: should character [...] ?
> 
> 7. strip.white 	logical. Used only when...
> 
> 
> First, I believe that a consistent style would make the help 
> text easier 
> to follow. Second, I believe that an explicit style (sth 
> like: "logical. 
> If TRUE/FALSE then...") is more intuitive 

It would also be nice if the argument description indicated
if the argument should have length one or if it could be a
general vector.

E.g. a style guide could say the default is that
arguments are general vectors but that
   stringsAsFactors logical scalar.  If TRUE ...
would tell us that stringsAsFactors had to be of length
one (so you cannot say that some columns are to be factors
and others not).  The code phrase could be '<type> scalar'
or 'a <type>' but having a common phrase would help.

Bill Dunlap
Spotfire, TIBCO Software
wdunlap tibco.com 

> and thus preferable 
> over the 
> other styles. This might apply to other help pages as well.
> 
> I fully understand that the choice of style in help text is a 
> matter of 
> taste and not of very high priority. Nevertheless, I just wish to 
> mention it as a potential for improvement.
> 
> 
> Thank you for your great work with R!
> 
> 
> Best regards,
> 
> Henrik
> 
> 
> R version 2.10.1 (2009-12-14)
> i386-pc-mingw32
> 
> locale:
> [1] LC_COLLATE=English_United Kingdom.1252  LC_CTYPE=English_United 
> Kingdom.1252    LC_MONETARY=English_United Kingdom.1252 LC_NUMERIC=C 
> 
> [5] LC_TIME=English_United Kingdom.1252
> 
> attached base packages:
> [1] grDevices datasets  splines   graphics  stats     tcltk     utils 
>    methods   base
> 
> other attached packages:
> [1] svSocket_0.9-48 TinnR_1.0.3     R2HTML_1.59-1   Hmisc_3.7-0 
> survival_2.35-7
> 
> loaded via a namespace (and not attached):
> [1] cluster_1.12.1  grid_2.10.1     lattice_0.17-26 svMisc_0.9-56 
> tools_2.10.1
> 
> -- 
> Henrik Pärn
> Centre for Conservation Biology
> Department of Biology
> Norwegian University of Science and Technology
> NO-7491 Trondheim
> Norway
> 
> Office: +47 73596285
> Fax: +47 73596100
> Mobile: +47 90989255
> 
> E-mail: henrik.parn at bio.ntnu.no
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>