>>>>> 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{' *.Rd
starts with
agrep.Rd 42: \item{\code{cost}:}{maximum number/fraction of match cost
agrep.Rd 44: \item{\code{all}:}{maximal number/fraction of \emph{all}
agrep.Rd 46: \item{\code{insertions}:}{maximum number/fraction of
insertions}
gives *many* matches for the base/man/options.Rd page
and (in Emacs where I use the very powerful M-x grep ) end saying
Grep finished with 265 matches found at Wed Nov 30 12:25:01
Martin
> On Mon, Nov 28, 2022 at 11:25 AM Deepayan Sarkar
<deepayan.sar...@gmail.com>
> wrote:
>> On Sun, Nov 27, 2022 at 12:30 PM Dario Strbenac via Bioc-devel <
>> bioc-devel@r-project.org> wrote:
>>
>> > Good day,
>> >
>> > For a long time, it has been a convention to document S4 methods in the
>> > format:
>> >
>> > \section{Displaying}{
>> > In the code snippets below, \code{x} is a GRanges object.
>> > \describe{
>> > \item{}{
>> > \code{show(x)}:
>> > Displays the first five and last five elements.
>> > }
>> > }
>> > }
>> >
>> > In R Under Development, this is now a warning:
>> >
>> > * checking Rd files ... WARNING
>> > checkRd: (5) GRanges-class.Rd:115-165: \item in \describe must have
>> > non-empty label.
>> >
>>
>> > This affects my own package as well as the core Bioconductor packages
>> > which I used as inspiration for designing my pacakge documentation
seven
>> > years ago. What should the new convention be? Or could R developers be
>> > convinced to get rid of this check before this prototype is released?
>> >
>>
>> The warning is primarily meant for \items inside \arguments, as in HTML
>> output these now have an id that can be used to link to specific
arguments.
>> The code is shared with \describe, which is why the warning is showing up
>> here.
>>
>> So I guess it might be possible to fine-tune the warning to accept this
>> kind of usage inside \describe. But I think this is a horrible
>> "convention", and unless this is really widespread that wouldn't be my
>> first choice.
>>
>> An alternative to Henrik's suggestion is to just use \itemize instead of
>> \describe and drop the first {} after \item.
>>
>> Best,
>> -Deepayan
_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel
