Footnotes not being resolved in BiocStyle::html_document output format

[PeteHaitch]

Footnotes, at least those defined using the inline_notes pandoc extension, don't appear to be properly resolved when using BiocStyle::html_document output format. They do appear to work when using html_document output format, so this suggests to me it's something going wonky with BiocStyle rather than rmarkdown.

An example is given in https://github.com/Bioconductor/BiocStyle/blob/master/vignettes/AuthoringRmdVignettes.Rmd#margin-notes, which doesn't appear to be rendered in https://bioconductor.org/packages/release/bioc/vignettes/BiocStyle/inst/doc/AuthoringRmdVignettes.html#10_margin_notes.

[aoles]

Thanks Peter for reporting this, I was able to reproduce the described problem.

For the record, footnotes used to work in BioC 3.6; doesn't seem to directly related to rmarkdown or bookdown as I still get the same behavior with archived versions listed in sessionInfo. This might indicate some pandoc issue. Unfortunately, it doesn't seem possible to recover which version of pandoc was used to render the vignette in BioC 3.6 because https://github.com/Bioconductor/BBS/issues/56 hasn't been implemented yet..

EDIT: Probably related to the issue fixed in https://github.com/rstudio/tufte/commit/92fc9a236f24f0ba5f538ac80a00cee7b4fe5001.

[PeteHaitch]

Thanks, @aoles. Can confirm this works locally, but I don't see the change reflected on the BioC website (specifically for, https://bioconductor.org/packages/devel/bioc/vignettes/SummarizedExperiment/inst/doc/Extensions.html). Any ideas?

[aoles]

That's because one needs to rebuild the affected package vignettes with the updated version of BiocStyle, both in release and devel. As this would happen only on package version bump, we will probably need to bump versions of all the packages which use footnotes in their BiocStyle-enabled Rmd vignettes (CC @mtmorgan @vobencha @lshep).

UPDATE:

The potentially affected packages can be listed by executing the shell script from biocbuild user directory on malbec builders:

grep -l "BiocStyle::html_document" bbs-*/MEAT0/*/vignettes/*.Rmd \
| xargs grep -l "\^\[" \
| awk -F"/" '{print $3}' \
| uniq

Taking into account that BiocStyle itself is already fixed, this leaves us with the following lists of pkgs.

release: beachmat CAGEr ctsGE DropletUtils GENIE3 hpar mdgsa MEAL microbiome MSnbase pRoloc STATegRa synapter transcriptogramer vsn RforProteomics

devel: CAGEr ctsGE DropletUtils GENIE3 hpar mdgsa MEAL microbiome MSnbase pRoloc STATegRa SummarizedExperiment synapter vsn RforProteomics

UPDATE 2

I've just made sure with the following script that all of the release packages listed above didn't have any version bump yet, so they need to be rebuild. In devel, beachmat has been recently updated such that it already renders footnotes properly, so I've removed it from the devel list.

grep -l "BiocStyle::html_document" bbs-*/MEAT0/*/vignettes/*.Rmd \
| xargs grep -l "\^\[" \
| awk -F"/" '{print $1"/"$2"/"$3"/DESCRIPTION"}' \
| uniq \
| xargs grep "Version: "

[lshep]

I performed a version bump on the above list of packages - They should all get updated on tomorrow's build.

[aoles]

Thanks Lori! Most of the vignettes rebuilt fine, however, for some reason CAGEr, microbiome and RforProteomics in both release and devel still don't display footnotes properly.

UPDATE

The problem is specific to pandoc 2.0 and relates to footnotes spreading across multiple lines. It boils down to https://github.com/rstudio/tufte/issues/57 because BiocStyle uses a similar approach as tufte to process footnotes. The pandoc option --wrap preserve is set by bookdown::html_document2.

[PeteHaitch]

FYI SummarizedExperiment also still doesn't display footnotes properly (https://bioconductor.org/packages/devel/bioc/vignettes/SummarizedExperiment/inst/doc/Extensions.html)

[aoles]

Thanks @PeteHaitch! The reason why footnotes in SummarizedExperiment are still broken is that the package failed to rebuild after the update (the vignette displayed on the website is for version 1.11.3 which is from two weeks ago, just before the fix in BiocStyle was introduced).

There are, however, still issues with CAGEr and RforProteomics. As described in my previous comment, the problem was due to multi-line footnotes, a separate issue from the original problem from the beginning of this thread. I believe this has been fixed too in the recent update to BiocStyle. @lshep, would you mind triggering a rebuild of theses two packages in both release and devel?

microbiome turned out to be a false positive. It's vignette doesn't use footnotes, the search just matched to a comment describing how to use them.

Cheers, Andrzej

[PeteHaitch]

Woops, I misunderstood the issue. Thanks for clarifying!

[PeteHaitch]

Confirming this is now fixed in SummarizedExperiment. Thanks again!