R devel - Jun 2021 - Small Fix: Greatly Increase Clarity/Utility of R Package Help/Manual Overview Pages

?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 at childrens.harvard.edu

	[[alternative HTML version deleted]]

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 at childrens.harvard.edu
> 
> 	[[alternative HTML version deleted]]
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>