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

From: <henrik.parn_at_bio.ntnu.no>
Date: Mon, 11 Jan 2010 16:10:11 +0100 (CET)


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

______________________________________________
R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Received on Tue 12 Jan 2010 - 08:01:36 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Wed 13 Jan 2010 - 08:40:13 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive