Writing my first CRAN vignette

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Writing my first CRAN vignette

Michael Dewey
In fact my first vignette full stop.

I am intending to use Sweave. I have read the Sweave documentation
and section 1.4 of the extensions manual and apart from (a) do not
use split = TRUE (b) and include all the source components, there
does not seem to be anything CRAN specific.

1 - Am I missing some other documentation?
2 - If I use a package from CTAN would that be considered within the
spirit if not the letter of open source? I am not asking for trained
legal advice here, it is the spirit of the rules.
3 - I assume including the .bbl file would be fine rather than making
a separate .bib file?

I am not envisaging doing anything complex: text, formulae, some
tables and one figure plus a few references.


Michael Dewey
[hidden email]
http://www.aghmed.fsnet.co.uk/home.html

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Writing my first CRAN vignette

Prof Brian Ripley
On 18/05/2014 13:33, Michael Dewey wrote:
> In fact my first vignette full stop.
>
> I am intending to use Sweave. I have read the Sweave documentation and
> section 1.4 of the extensions manual and apart from (a) do not use split
> = TRUE (b) and include all the source components, there does not seem to
> be anything CRAN specific.
>
> 1 - Am I missing some other documentation?

There is no such thing as a 'CRAN vignette'.  These days all
(non-internal-to-CRAN) CRAN-specific documentation is in the CRAN policies.

> 2 - If I use a package from CTAN would that be considered within the
> spirit if not the letter of open source? I am not asking for trained
> legal advice here, it is the spirit of the rules.

Provided it is available to people to reproduce things if the package
uses a FOSS licence.

> 3 - I assume including the .bbl file would be fine rather than making a
> separate .bib file?

No.  We have seen .bbl files which no longer worked after a TeXLive
update, and with a FOSS licence you need to supply the sources (and
normally the .bib file is the source).

>
> I am not envisaging doing anything complex: text, formulae, some tables
> and one figure plus a few references.
>
>
> Michael Dewey
> [hidden email]
> http://www.aghmed.fsnet.co.uk/home.html


--
Brian D. Ripley,                  [hidden email]
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Writing my first CRAN vignette

hadley wickham
In reply to this post by Michael Dewey
> I am intending to use Sweave. I have read the Sweave documentation and
> section 1.4 of the extensions manual and apart from (a) do not use split =
> TRUE (b) and include all the source components, there does not seem to be
> anything CRAN specific.

I'd strongly recommend using knitr instead - the biggest advantage is
that you can use markdown, which is substantially easier to use than
latex (and doesn't require such a massive toolchain)

Hadley


--
http://had.co.nz/

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Writing my first CRAN vignette

Dirk Eddelbuettel

On 18 May 2014 at 11:34, Hadley Wickham wrote:
| > I am intending to use Sweave. I have read the Sweave documentation and
| > section 1.4 of the extensions manual and apart from (a) do not use split =
| > TRUE (b) and include all the source components, there does not seem to be
| > anything CRAN specific.
|
| I'd strongly recommend using knitr instead - the biggest advantage is
| that you can use markdown, which is substantially easier to use than
| latex (and doesn't require such a massive toolchain)

Markdown is very useful. And it keeps getting better -- shiny-within-markdow
is / will rock very, very hard.

But there are also some things that I still much prefer to be in pdf form,
rather than (in however well-styled) html and browser content.  And some
paths in the toolchain that leads content from markdown to pdf are via latex,
so you end up using latex anyway. Which isn't really that hard to install on
any of the three main platforms as texlive bundles it pretty well.

And more generally, a vignette is (at least to me, but also some others)
still a 'paper' -- something that strives to be something like an academic
article (and occassionally even manages to get there).  

And for that form of written communication, I fear you will have to pry latex
from my cold dead hands.  

Dirk

--
Dirk Eddelbuettel | [hidden email] | http://dirk.eddelbuettel.com

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Writing my first CRAN vignette

Michael Dewey
In reply to this post by Prof Brian Ripley
At 14:57 18/05/2014, Prof Brian Ripley wrote:

>On 18/05/2014 13:33, Michael Dewey wrote:
>>In fact my first vignette full stop.
>>
>>I am intending to use Sweave. I have read the Sweave documentation and
>>section 1.4 of the extensions manual and apart from (a) do not use split
>>= TRUE (b) and include all the source components, there does not seem to
>>be anything CRAN specific.
>>
>>1 - Am I missing some other documentation?
>
>There is no such thing as a 'CRAN vignette'.  These days all
>(non-internal-to-CRAN) CRAN-specific documentation is in the CRAN policies.
>
>>2 - If I use a package from CTAN would that be considered within the
>>spirit if not the letter of open source? I am not asking for trained
>>legal advice here, it is the spirit of the rules.
>
>Provided it is available to people to reproduce things if the
>package uses a FOSS licence.
>
>>3 - I assume including the .bbl file would be fine rather than making a
>>separate .bib file?
>
>No.  We have seen .bbl files which no longer worked after a TeXLive
>update, and with a FOSS licence you need to supply the sources (and
>normally the .bib file is the source).

Thanks, that (and the other answers) will be very helpful.


>>I am not envisaging doing anything complex: text, formulae, some tables
>>and one figure plus a few references.
>>
>>
>>Michael Dewey
>>[hidden email]
>>http://www.aghmed.fsnet.co.uk/home.html
>
>
>--
>Brian D. Ripley,                  [hidden email]
>Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
>University of Oxford,             Tel:  +44 1865 272861 (self)
>1 South Parks Road,                     +44 1865 272866 (PA)
>Oxford OX1 3TG, UK                Fax:  +44 1865 272595

Michael Dewey
[hidden email]
http://www.aghmed.fsnet.co.uk/home.html

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Writing my first CRAN vignette

Ramon Diaz-Uriarte-2
In reply to this post by Dirk Eddelbuettel


On Sun, 18-05-2014, at 19:19, Dirk Eddelbuettel <[hidden email]> wrote:

> On 18 May 2014 at 11:34, Hadley Wickham wrote:
> | > I am intending to use Sweave. I have read the Sweave documentation and
> | > section 1.4 of the extensions manual and apart from (a) do not use split =
> | > TRUE (b) and include all the source components, there does not seem to be
> | > anything CRAN specific.
> |
> | I'd strongly recommend using knitr instead - the biggest advantage is
> | that you can use markdown, which is substantially easier to use than
> | latex (and doesn't require such a massive toolchain)
>
> Markdown is very useful. And it keeps getting better -- shiny-within-markdow
> is / will rock very, very hard.
>
> But there are also some things that I still much prefer to be in pdf form,
> rather than (in however well-styled) html and browser content.  And some
> paths in the toolchain that leads content from markdown to pdf are via latex,
> so you end up using latex anyway. Which isn't really that hard to install on
> any of the three main platforms as texlive bundles it pretty well.
>
> And more generally, a vignette is (at least to me, but also some others)

To me too. But still, with knitr he can use as much latex as with Sweave.


> still a 'paper' -- something that strives to be something like an academic
> article (and occassionally even manages to get there).  
>
> And for that form of written communication, I fear you will have to pry latex
> from my cold dead hands.

:-).


R.


>
> Dirk


--
Ramon Diaz-Uriarte
Department of Biochemistry, Lab B-25
Facultad de Medicina
Universidad Autónoma de Madrid
Arzobispo Morcillo, 4
28029 Madrid
Spain

Phone: +34-91-497-2412

Email: [hidden email]
       [hidden email]

http://ligarto.org/rdiaz

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel