[Bioc-devel] BiocStyle for styling Sweave (and other?) vignettes

[Martin Morgan]

Thanks Renaud for your comments.

On 07/21/2013 11:52 PM, Renaud wrote:
> Hi,
>
> this package is a nice idea indeed. For what is worth, I developed a similar
> feature within the pkgmaker package (on CRAN), especially to enable easy
> CRAN/Bioc package referencing/linking, with the inclusion of an extra bib file
> generated on the fly from \cite-like commands (although the parsing is currently
> done externally, before running knitr). But this could be tuned using a similar
> trick as Carl's knitrcitation package to add citations within each call to a
> \cite command.
> The package's REFERENCE.bib file is also included and available for citations.
>
> It works pretty much like BioCStyle with the injection of a raw latex preamble
> that defines extra link, citation commands.
> I use it in all my packages' vignettes (e.g.
> https://github.com/renozao/NMF/blob/master/pkg/vignettes/NMF-vignette.Rnw):
>
> % add preamble from pkgmaker
> <<pkgmaker_preamble, echo=FALSE, results='asis'>>=
> pkgmaker::latex_preamble()
>
> @
>
> % REFERENCES
> \usepackage[citestyle=authoryear-icomp
> , doi=true
> , url=true
>
> , maxnames=1
> , maxbibnames=15
> , backref=true
> , backend=bibtex]{biblatex}
> \AtEveryCitekey{\clearfield{url}}
>
> <<bibliofile, echo=FALSE, results='asis'>>=
> pkgmaker::latex_bibliography('NMF')
> @
> \bibliography{Rpackages}
>
>
> This proved to be very useful to me and I believe the idea can be push quite far
> in standardising vignettes.
> Other comments:
>
> 1) It would be nice if the package was a CRAN package though so that it can
> benefit to all R package developers, without depending on having Bioc
> repositories enabled, (rename? :)), with an option to enable a fully "branded"
> Bioconductor style (e.g. Mention to "This package is par to Bioconductor ...").
> Or alternatively, still name it BiocStyle, but with an option to disable the
> "branding", but give access to all useful features (refernecs, links, etc...).

I think we'll stick with a Bioconductor package for the moment... We'll see how 
it develops.

> 2) One should avoid to lock the user into too restrictive coding pattern,
> especially the style and commands should be compatible with knitr, which makes a
> really good job highlighting, caching, , multiple figures inclusion, etc...

yes, if there are specific suggestions from knitr users we're happy to incorporate.

>
> 3) Support to non Latex vignettes would be good, Rmd and slideshows.

Agree here too.

> 4) Styling could be made even more transparent if vignette engines were allowed
> to some config files that lies in the package vignettes/ subdirectory, which
> enables choosing a style without modifying the vignette sources. I believe this
> would be easily implementable for knitr vignettes (just need to log an issue to
> Yihui, maybe this even already exists...). For example this would allow
> Bioconductor building farm to build packages with a special styling on the fly:
> the developers would not even have to change their code!!

Maybe a little out of scope for the moment.

Thanks for the comments! Martin

>
> This is all exciting :D
>
> Bests,
> Renaud
>


-- 
Computational Biology / Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N.
PO Box 19024 Seattle, WA 98109

Location: Arnold Building M1 B861
Phone: (206) 667-2793