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 <mtmor...@fhcrc.org
<mailto: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 <tel:%28206%29%20667-2793>
_________________________________________________
Bioc-devel@r-project.org <mailto:Bioc-devel@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
_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel
