[Bioc-devel] Updates to BiocStyle formatting

Leonardo Collado Torres lcollado at jhu.edu
Mon Aug 7 20:32:27 CEST 2017

Hi Andrzej,

Could you let us know when you make the change which BiocStyle version
implemented the change? That way we can update our description files.

In the meantime, I switched my vignettes to use
BiocStyle::html_document2 although I need to use figure captions and
references to take advantage of all the things html_document2 has to


On Mon, Aug 7, 2017 at 8:05 AM, Andrzej Oleś <andrzej.oles at gmail.com> wrote:
> Dear Bioconductor Developers,
> We would like that in the next release most of the vignettes which use
> BiocStyle benefit from the updated formatting introduced over the last
> year. For this, all BiocStyle format functions will be switched to the new
> style. This transition will happen on Friday, August 18.
> BiocStyle 2.0
> =============
> The new style was developed in collaboration with a professional graphics
> designer with the aim to address some of the shortcomings of the original
> implementation (e.g., inconsistent formatting both within the document and
> across output formats; non-distinctive structuring elements, for example
> running head and figure captions). Additionally, we introduced new
> features, including:
> -   Common formatting regardless of input (Rnw/Rmd) and output format
> -   Consistent layout providing a clear separation between content and
> structuring elements emphasized by horizontal alignment
> -   Standardized way of specifying author affiliations
> -   Cross references in R Markdown based on the bookdown syntax
> -   Support for recent additions to R Markdown (floating TOC, code folding,
> ...)
> -   Footnotes typeset as margin notes
> The updated style is invoked through `BiocStyle::latex2`,
> `BiocStyle::pdf_document2` and `BiocStyle::html_document2` functions. Feel
> free to have a look at some live examples, for example, at [PureCN.pdf](
> http://bioconductor.org/packages/devel/bioc/vignettes/PureCN/inst/doc/PureCN.pdf)
> (PDF from Rnw source), or [A-vsn.html](
> http://bioconductor.org/packages/devel/bioc/vignettes/vsn/inst/doc/A-vsn.html)
> (HTML from Rmd source).
> Switch to the new style
> =======================
> To streamline the process, the transition will happen automatically by
> replacing the previous format functions by the new ones as follows.
> Functions whose name ends with "2": `BiocStyle::latex2`,
> `BiocStyle::pdf_document2` and `BiocStyle::html_document2` will be renamed
> by stripping the trailing "2" such that they replace their old
> counterparts, e.g. `BiocStyle::latex`. At the same time, the latter ones
> will be archived by appending `_old` to their names so that, for example,
> `BiocStyle:latex` will become `BiocStyle::latex_old`. Function names with
> the trailing "2" will be kept until the release as aliases. Both these and
> the "old" functions will be marked as deprecated, and made defunct after
> the release following the [Function Deprecation Guidelines](
> http://bioconductor.org/developers/how-to/deprecation/). The following list
> summarizes the changes.
>     BiocStyle::latex          -> BiocStyle::latex_old
>     BiocStyle::latex2         -> BiocStyle::latex
>     BiocStyle::pdf_document   -> BiocStyle::pdf_document_old
>     BiocStyle::pdf_document2  -> BiocStyle::pdf_document
>     BiocStyle::html_document  -> BiocStyle::html_document_old
>     BiocStyle::html_document2 -> BiocStyle::html_document
> How does this affect me?
> ========================
> Scenario 1: Already using the new style (`latex2`, `pdf_document2` or
> `html_document2`)
> ---------------------------------------------------------------------------------------
> Congratulations, thank you for test driving the new style! Once these
> functions get deprecated, please rename your BiocStyle format function
> calls by removing the trailing "2".
> Scenario 2: Currently using the original style (`latex`, `pdf_document` or
> `html_document`)
> -------------------------------------------------------------------------------------------
> Typically, no special action will be needed. We worked hard to provide as
> much backwards compatibility as possible, so your vignette should compile
> with the new style right out of the box. However, some vignettes might
> require some small tweaks to build after the update. This affects mostly
> PDF output because of the more complex LaTeX macro definitions and the
> additional dependencies of the new style. Should you experience any
> problems, please first make sure that the source of your vignette meets the
> guidelines described in [Bioconductor LaTeX Style 2.0](
> https://bioconductor.org/packages/devel/bioc/vignettes/BiocStyle/inst/doc/LatexStyle2.pdf)
> (for .Rnw vignettes) or [Authoring R Markdown Vignettes](
> https://bioconductor.org/packages/devel/bioc/vignettes/BiocStyle/inst/doc/AuthoringRmdVignettes.html)
> (for .Rmd vignettes). Any remaining issues should be reported as a [GitHub
> issue](https://github.com/Bioconductor/BiocStyle/issues). As an interim
> solution you can still use the previous format function renamed
> to `*_old` in order to build your package.
> Kind regards,
> Andrzej Oleś
>         [[alternative HTML version deleted]]
> _______________________________________________
> Bioc-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel

More information about the Bioc-devel mailing list