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

[Duncan Murdoch]

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