[Rd] Small Fix: Greatly Increase Clarity/Utility of R Package Help/Manual Overview Pages

[Sebastian Meyer]

Just in case others (like me) don't instantly know what this is about.

This only affects the html help.
Compare the HTML index page for the base package "graphics"

https://stat.ethz.ch/R-manual/R-patched/library/graphics/html/00Index.html

with the index page for the base package "grDevices"

https://stat.ethz.ch/R-manual/R-patched/library/grDevices/html/00Index.html

The latter is split by first letter, the former isn't as it only lists
98 <= 100 help pages.

I don't really have a preference for either (but I also rarely use the
html help system). Using a threshold seems reasonable to avoid blowing
up the index of a small package like "splines" but provide some anchors
for a large package like "stats". 50 may be too low as a threshold.
Looking at package "parallel" with its 45 entries

https://stat.ethz.ch/R-manual/R-patched/library/parallel/html/00Index.html

the listing doesn't seem long enough to benefit from alphabetic
sectioning. Probably a matter of taste.

Best regards,

	Sebastian


Am 29.06.21 um 13:07 schrieb Marsh, Samuel:
> ?Hi,
> 
> 
> I would like to suggest a single line (2 characters) fix that I feel would greatly improve the readability and usefulness of the overview R package help/manual pages.  Currently the overall help/manual page for a package is organized into alphabetized table of contents with linked headers by letter only if the package contains more than 100 functions, otherwise the functions are simply listed with no line breaks.  This makes for a more difficult user experience with moderately sized packages 50-99 functions that could be improved.  I would suggest changing the threshold for creating this alphabetized table of contents to 50 instead of 100.
> 
> 
> I've provided info on the current code that specifies this parameter below:
> 
> It would appear that all that needs to be changed is the "> 100" parameter on this line:
> https://github.com/wch/r-source/blob/80a7ca3b605b34d207ed3465c942f39a37e89f6e/src/library/tools/R/install.R#L2770
> 
> 
> Or to list the code directly:
> 
> In the .writePkgIndices function the line is:
> use_alpha <- (nrow(M) > 100)?
> 
> 
> It appears to me the only change needed would be to set "nrow(M) > 50".  I believe this very small fix would greatly improve user experience for a growing number of moderately-sized packages whose manual/help pages would still greatly benefit from greater readability/organization.
> 
> 
> Thank you!
> 
> Sam
> 
> 
> --
> Samuel E. Marsh, Ph.D.
> Postdoctoral Fellow
> Laboratory of Dr. Beth Stevens
> F.M. Kirby Neurobiology Research Center
> Boston Children's Hospital
> Harvard Medical School
> samuel.marsh using childrens.harvard.edu
> 
> 	[[alternative HTML version deleted]]
> 
> ______________________________________________
> R-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>