[Bioc-devel] S4 Methods Documentation Convention Triggers Warnings

[Henrik Bengtsson]

> Anyways, that's hundreds of \items that I need to fix in a dozen of packages. Not fun!

A great opportunity to freshen up your 'sed' skills. (I think it's
possible to use 'sed' here, but 100% sure)

/Henrik

On Thu, Dec 1, 2022 at 12:27 PM Hervé Pagès <hpages.on.github using gmail.com> wrote:
>
> 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.bioc using 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-bounces using r-project.org> on behalf of Martin
> >> Maechler <maechler using stat.math.ethz.ch>
> >> Date: Wednesday, November 30, 2022 at 6:28 AM
> >> To: Michael Lawrence (MICHAFLA) <lawrence.michael using gene.com>
> >> Cc: bioc-devel using r-project.org <bioc-devel using r-project.org>, Kurt Hornik <
> >> Kurt.Hornik using 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 using r-project.org mailing list
> >> https://stat.ethz.ch/mailman/listinfo/bioc-devel
> >>
> >       [[alternative HTML version deleted]]
> >
> > _______________________________________________
> > Bioc-devel using r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/bioc-devel
>
> --
> Hervé Pagès
>
> Bioconductor Core Team
> hpages.on.github using gmail.com
>
> _______________________________________________
> Bioc-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel