On Wed, Nov 30, 2022 at 9:51 PM Martin Morgan <mtmorgan.b...@gmail.com> wrote:
> I recently made the change Henrik suggests in the ‘devel’ but not > ‘release’ branch of BiocParallel, so the manuals can be compared. Take a > look at the ‘Constructor’ and ‘Accessors: Logging and results’ sections of > the ‘SnowParam-class.Rd’ man page, starting on p. 53 of the PDF. > > > https://bioconductor.org/packages/release/bioc/manuals/BiocParallel/man/BiocParallel.pdf > > > https://bioconductor.org/packages/devel/bioc/manuals/BiocParallel/man/BiocParallel.pdf > > I think in \item{<foo>}{bar} the <foo> is not wrapped, so runs off the > margin in the devel ‘Constructor’ section. This should ideally use \preformatted{}, but R-exts says that "Due to limitations in LaTeX as of this writing, this macro may not be nested within other markup macros other than \dQuote and \sQuote, as errors or bad formatting may result." Still, in this particular case, and possibly others like it, free-format text (instead of itemizing) might work better: \section{Constructor}{ \preformatted{SnowParam(workers = snowWorkers(), type=c("SOCK", "MPI"), tasks = 0L, stop.on.error = FALSE, progressbar = FALSE, RNGseed = NULL, timeout = Inf, exportglobals = TRUE, exportvariables = TRUE, log = FALSE, threshold = "INFO", logdir = NA_character_, resultdir = NA_character_, jobname = "BPJOB", manager.hostname = NA_character_, manager.port = NA_integer_, ...)} Returns an object representing a SNOW cluster. The cluster is not created until \code{bpstart} is called. Named arguments in \code{...} are passed to \code{makeCluster}. } Even if we retain the status quo, the \item{}{\code{...}{}} version of this (as in the release branch) is by no means nice-looking. Best, -Deepayan The shorter items in the ‘Accessors: Logging and results’ section look > almost identical, with a little extra (unnecessary) indentation under the > original formatting. > > I changed the ‘Accessors: Back-end control’ to an itemized list, since > there was no description associated with each item. This adds bullets. > > The commit is at > > > https://code.bioconductor.org/browse/BiocParallel/commit/4e85b38b92f2adb68fe04ffb0476cbc47c1241a8 > > (as well as https://github.com/Bioconductor/BiocParallel...) > > Martin > > From: Bioc-devel <bioc-devel-boun...@r-project.org> on behalf of Martin > Maechler <maech...@stat.math.ethz.ch> > Date: Wednesday, November 30, 2022 at 6:28 AM > To: Michael Lawrence (MICHAFLA) <lawrence.mich...@gene.com> > Cc: bioc-devel@r-project.org <bioc-devel@r-project.org>, Kurt Hornik < > kurt.hor...@wu.ac.at> > Subject: Re: [Bioc-devel] S4 Methods Documentation Convention Triggers > Warnings > >>>>> Michael Lawrence \(MICHAFLA\) via Bioc-devel > >>>>> on Mon, 28 Nov 2022 12:11:00 -0800 writes: > > > It may be worth revisiting why we arrived at this convention in the > first > > place and see whether the Rd system can be enhanced somehow so that > we can > > achieve the same effect with a more natural syntax. > > > Michael > > > Yes, I agree. > > It may be that in the distant past, Henrik's suggestion > (a version of which I am using myself a lot in *.Rd -- mostly > *not* related to S4) > did not work correctly, but I know it has worked for years now, > as I use it "all the time". > and not just I. > > If I grep in R's *base* package alone, > > inside ...../R/src/library/base/man/ > > grep --color -nH --null -e '\\item{\\code{<file:///item%7b/code%7b>' *.Rd > > starts with > > agrep.Rd > > [[alternative HTML version deleted]] > > _______________________________________________ > Bioc-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/bioc-devel > [[alternative HTML version deleted]] _______________________________________________ Bioc-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel