[Bioc-devel] S4 Methods Documentation Convention Triggers Warnings

[Hervé Pagès]

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