Itemizing brings semantics and structure. Plus, the \preformatted
solution doesn't look good either IMO. FWIW I mostly care about what I
see when I open the man page in a terminal with ?<foo>. I don't care so
much about the PDF manual, never look at it.
So I'm going to switch from
\item{}{\code{show(x)}:
...
}
to
\item{\code{show(x)}:}{
...
}
as suggested by Henrik.
I actually tried the latter many years ago and compared with the former
and for some reason decided to go for the former. But now I like the
rendering of the latter better. Don't know if it has changed or if my
taste has changed ;-)
Anyways, that's hundreds of \items that I need to fix in a dozen of
packages. Not fun! Also the thing with the exact location of the colon
is very error prone. As Michael said, it would be nice to be able to
achieve this with a simpler/more natural syntax.
H.
On 30/11/2022 10:47, Deepayan Sarkar wrote:
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
--
Hervé Pagès
Bioconductor Core Team
hpages.on.git...@gmail.com
_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel
