henrik.parn at bio.ntnu.no
2010-Jan-11 15:10 UTC
[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 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
William Dunlap
2010-Jan-12 17:04 UTC
[Rd] Documentation: format of read.table help text (PR#14180)
> -----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 intuitiveIt 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 >
Duncan Murdoch
2010-Jan-12 18:53 UTC
[Rd] Documentation: format of read.table help text (PR#14180)
On 11/01/2010 10:10 AM, henrik.parn at bio.ntnu.no wrote:> Dear R developers, > > I find the format of descriptions of the arguments in the read.table > help text slightly inconsistent. >"Slightly inconsistent" is not a bug. Your bug report is quite likely to be ignored because of that and because of the lack of an offer to actually do the work it entails, regardless of the validity of your observations. A way to have attention paid to it is to choose a consistent style, then edit every man page in one of the base packages to follow it, and submit the patches to all those files, with an offer to do the rest once the style is accepted. Expect that there will be one or more rounds of discussion about whether your style really is usable. Writing a style guide would really help. Sound like too much work? I agree. Duncan Murdoch> 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 > >