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

Tue Jul 23 01:33:30 CEST 2013

On 07/16/2013 05:46 PM, Kasper Daniel Hansen wrote:
> This is a great idea.
>
> Comments
>
> 1) Latex dependencies.  Hopefully this style will be adopted throughout Bioc, so
> any latex dependencies will be actual dependencies for building and checking
> packages.  Not everyone works on a system where everything is installed, nor
> does everyone know how to fix a latex installation (this is especially true for
> inexperienced latex users, who should be some of the prime beneficiaries of this
> work).   In my specific instance, I had to install sectsty and titling.
>
> I therefore suggest including (most of) the dependencies inside the inst/sty
> directory, if the sty license allows it - otherwise I suggest dropping the latex
> package in question.
>
> In general, Latex errors can be pretty hard to track down and R CMD check (on a
> build server) provides very little information.  My current opinion is that
> making the pdf look nice is not worth too many dependencies.
>
> I am happy to help with this.

OK, I think we can get rid of the sectsty and titling dependencies; I'll work on 
this.

>
> 2) The link command \Rpkg is almost the same as \Rpackage, which I am going to
> confuse many times..  First, I think it should say CRAN and not R and second, I
> would recommend doing something like \linkCRAN, \linkBioc.  Perhaps also include
> Rforge?

I changed \Rpkg to \CRANpkg; I stuck with the \Biocpkg naming convention.

> 3) we should include some bibtex as well.  I have some code for including a PMID
> link and a DOI link based on bibtex-entries, so you can have
>    doi =          {10.1038/ng.865},
>    pubmed =       {21706001}
> and get it typeset with hyperlinks, which I like a lot (see for example the
> bsseq vignette).  The hyperlinks are (in my opinion) extremely nice to have in
> vignettes.

There might be a bit of discussion / divergent opinion about this, and I'm 
afraid that this will lead to lack of use and feature bloat.

> 4) The package ought to include a clean template a user can just copy and paste
> with like
>   \author{NAME1 \and NAME2}
> so it is easy to modify.  Also, it (in my opinion) should have the Compiled:
> today, Revised: eons ago, which Martin has used in his vignettes and which are
> pretty useful to the user (apologies if someone else started the trend)
>
> This template should also be downloadable from the Bioconductor webpage somewhere.

Agree.

>
> 5) We should expand the vignette with tips and tricks for vignette writing. I
> have some in mind

Happy to hear of / incorporate these.

> 6) aesthetics.  One can debate this endlessly.  Still, I dislike the colored
> section headings.
>
> 7) Is it worth thinking about having some Bioconductor picture / link / subtitle
> like "This document is part of the Bioconductor package XX" for branding?
>   Probably not, but wanted to mention it.

I won't do anything about 6 or 7 yet.

> 8) Finally, the \Rcode, \Rclass, \Rfunction, \Robject lines of macros.  I used
> to have these as well (and also \Rmethod) but have since decided it is not worth
> it.  Having them makes totally sense from a programming perspective, but it
> tends to slow down my writing a lot, since I have to stop and think "am I
> referencing an object or a class or, and what is the macro".  Equally important,
> I have realized that the context usually makes the distinction clear, and if I
> really care I would never trust the typesetting to show the difference (since
> people use different conventions) but would alway say something like "produces
> an object of class \code{GRanges}.".  I suggest dropping them all and just use
> \code or perhaps \Rcode.  This is essentially equivalent to me no longer using
> \code{"GRanges"} inside Rd files (which many people don't use) for classes and
> just use \code{GRanges}.
>
> We should have macros that will help the reader, but not so many that it makes
> writing slower.  As I said in the beginning of this paragraph, this opinion is
> formed based on actually having used the macros for a while and then dropping
> them, so it is not completely guesswork.

I'm mostly on the same page about this, and suggest reducing these to \Rcode{} 
(\texttt markup) and \Rclass{} (\textit markup) which are more conceptually 
distinct than the others.

> 9) I believe the \inclfig macro depends on the user not changing the output plot
> file names.  This should be mentioned in the vignette - for example I sometimes
> (in Sweave, but almost never in vignettes) changing the output so that all plots
> appear in a "plots" subdirectory.  We should do this, because many people copy
> and paste code from other sources.

yes, for instance knitr puts everything in figure/. This has been updated.

Thanks for the comments Kasper.

> Best,
> Kasper
>
>
>
>
> On Sun, Jul 14, 2013 at 11:23 AM, Martin Morgan <mtmorgan at fhcrc.org
> <mailto:mtmorgan at fhcrc.org>> wrote:
>
>     Developers --
>
>     Sweave-style vignettes often include copy-pasted versions of basic LaTeX
>     macros and other commands. We've created the BiocStyle package to make it
>     easy to add these macros, and a consistent style, to Bioconductor vignettes
>     -- just add Suggests: BiocStyle to your package DESCRIPTION, and the
>     following lines inside the preamble (between \documentclass{article} and
>     \begin{document}) of your vignette
>
>     <<style, eval=TRUE, echo=FALSE, results=tex>>=
>     BiocStyle::latex()
>     @
>
>     Details, including illustration of macros and styles, are in the package
>     vignette
>
>
>     http://bioconductor.org/__packages/devel/bioc/vignettes/__BiocStyle/inst/doc/LatexStyle.__pdf
>     <http://bioconductor.org/packages/devel/bioc/vignettes/BiocStyle/inst/doc/LatexStyle.pdf>
>
>     and on the ?latex help page. Suggestions welcome. Perhaps this can be
>     extended for non-Sweave vignettes.
>
>     Martin
>     --
>     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 <tel:%28206%29%20667-2793>
>
>     _________________________________________________
>     Bioc-devel at r-project.org <mailto:Bioc-devel at r-project.org> mailing list
>     https://stat.ethz.ch/mailman/__listinfo/bioc-devel
>     <https://stat.ethz.ch/mailman/listinfo/bioc-devel>
>
>

-- 
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