From henrik.parn at bio.ntnu.no  Mon Jan 11 16:10:11 2010
From: henrik.parn at bio.ntnu.no (henrik.parn at bio.ntnu.no)
Date: Mon, 11 Jan 2010 16:10:11 +0100 (CET)
Subject: [Rd] Documentation: format of read.table help text (PR#14180)
Message-ID: <20100111151011.CA760282EFC7@mail.pubhealth.ku.dk>

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 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



[Rd] Documentation: format of read.table help text (PR#14180)
henrik.parn at bio.ntnu.no