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

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.

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?

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.

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.

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

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.

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.

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.

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>