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 <mtmor...@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
>
> ______________________________**_________________
> Bioc-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/**listinfo/bioc-devel<https://stat.ethz.ch/mailman/listinfo/bioc-devel>
>
[[alternative HTML version deleted]]
_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel
