[Bioc-devel] Updates to BiocStyle formatting

Andrzej Oleś andrzej.oles at gmail.com
Sat Aug 19 00:52:38 CEST 2017

Dear Bioconductor Developers,

As announced previously, the style functions have been updated to the new
formatting in BiocStyle version 2.5.19.

Package maintainers who already use the new style (`latex2`,
`pdf_document2` or `html_document2`) are now encouraged to update their
vignettes by stripping the trailing "2" from BiocStyle function calls.

In case you experience any problems with building your BiocStyle documents,
we kindly ask you to first make sure that your vignette meets the
guidelines described in [Bioconductor LaTeX Style 2.0](
(for .Rnw vignettes) or [Authoring R Markdown Vignettes](
(for .Rmd vignettes). Any remaining issues should be reported as a [GitHub
issue](https://github.com/Bioconductor/BiocStyle/issues). As a temporary
solution you can still use one of the deprecated format functions
(`latex_old`, `pdf_document_old` or `html_document_old`), but please be
warned that the "old" functions will be made defunct after the release.

Best regards,
Andrzej Oleś

On Mon, Aug 7, 2017 at 2:05 PM, 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]]

More information about the Bioc-devel mailing list