R package documentation

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

R package documentation

Sébastien Bihorel-3
Dear R users,

I am currently writing the documentation for my first package. I have
created a short user manual using sweave/pdflatex which is distinct from the
manual/summary-of-package-functions created by R CMD CHECK. I was wondering
how could I seamlessly combine both documents.

Thanks for your help

Sebastien

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Reply | Threaded
Open this post in threaded view
|

Re: R package documentation

Tobias Verbeke-2
Hi Sébastien,

Sébastien Bihorel wrote:

> I am currently writing the documentation for my first package. I have
> created a short user manual using sweave/pdflatex which is distinct from the
> manual/summary-of-package-functions created by R CMD CHECK. I was wondering
> how could I seamlessly combine both documents.

It is common to have
- technical documentation in your .Rd files (in the man/ directory
     of your package)
- functional documentation as a so-called vignette (Sweave file
     documenting concrete use of your package) in the
     inst/doc directory of your package.

http://cran.r-project.org/doc/manuals/R-exts.html#Writing-package-vignettes

Combining both documents into one file is not common.

I hope this helps,
Tobias

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Reply | Threaded
Open this post in threaded view
|

Re: R package documentation

Sébastien Bihorel-3
Hi Tobias,

The .R files that I have created for all my functions are somehow used to
generate a package manual pdf when I used R CMD CHECK. This is what I'd like
to add in my vignette. It might be uncommon, but I saw this was done for
several package documentations (e.g. PBS collections) and I kind of like
this combination.

Sebastien

On Wed, Apr 14, 2010 at 6:52 AM, Tobias Verbeke <
[hidden email]> wrote:

> Hi Sébastien,
>
>
> Sébastien Bihorel wrote:
>
>  I am currently writing the documentation for my first package. I have
>> created a short user manual using sweave/pdflatex which is distinct from
>> the
>> manual/summary-of-package-functions created by R CMD CHECK. I was
>> wondering
>> how could I seamlessly combine both documents.
>>
>
> It is common to have
> - technical documentation in your .Rd files (in the man/ directory
>    of your package)
> - functional documentation as a so-called vignette (Sweave file
>    documenting concrete use of your package) in the
>    inst/doc directory of your package.
>
> http://cran.r-project.org/doc/manuals/R-exts.html#Writing-package-vignettes
>
> Combining both documents into one file is not common.
>
> I hope this helps,
> Tobias
>
>
        [[alternative HTML version deleted]]


______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Reply | Threaded
Open this post in threaded view
|

Re: R package documentation

Tobias Verbeke-2
Hi Sébastien,

Sébastien Bihorel wrote:

> The .R files that I have created for all my functions are somehow used
> to generate a package manual pdf when I used R CMD CHECK. This is what
> I'd like to add in my vignette. It might be uncommon, but I saw this was
> done for several package documentations (e.g. PBS collections) and I
> kind of like this combination.

I now understand what you mean. The PBS documentation you refer to
seems a mere (manual) concatenation of a (non-LaTeX based) pdf
document and the reference manual pdf which is not generated from
a Sweave file. Such manipulations can be done using e.g. the pdfjam
toolbox by David Firth.

  http://go.warwick.ac.uk/pdfjam

Best,
Tobias

> On Wed, Apr 14, 2010 at 6:52 AM, Tobias Verbeke
> <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     Hi Sébastien,
>
>
>     Sébastien Bihorel wrote:
>
>         I am currently writing the documentation for my first package. I
>         have
>         created a short user manual using sweave/pdflatex which is
>         distinct from the
>         manual/summary-of-package-functions created by R CMD CHECK. I
>         was wondering
>         how could I seamlessly combine both documents.
>
>
>     It is common to have
>     - technical documentation in your .Rd files (in the man/ directory
>        of your package)
>     - functional documentation as a so-called vignette (Sweave file
>        documenting concrete use of your package) in the
>        inst/doc directory of your package.
>
>     http://cran.r-project.org/doc/manuals/R-exts.html#Writing-package-vignettes
>
>     Combining both documents into one file is not common.
>
>     I hope this helps,
>     Tobias
>
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Reply | Threaded
Open this post in threaded view
|

Re: R package documentation

Sébastien Bihorel-3
Thanks Tobias,

If there is no automated way to combine both documents, I will stack them
manually... that will likely cause some problems with page numbering tough.

Sebastien

On Wed, Apr 14, 2010 at 8:18 AM, Tobias Verbeke <
[hidden email]> wrote:

> Hi Sébastien,
>
> Sébastien Bihorel wrote:
>
>  The .R files that I have created for all my functions are somehow used to
>> generate a package manual pdf when I used R CMD CHECK. This is what I'd like
>> to add in my vignette. It might be uncommon, but I saw this was done for
>> several package documentations (e.g. PBS collections) and I kind of like
>> this combination.
>>
>
> I now understand what you mean. The PBS documentation you refer to
> seems a mere (manual) concatenation of a (non-LaTeX based) pdf
> document and the reference manual pdf which is not generated from
> a Sweave file. Such manipulations can be done using e.g. the pdfjam
> toolbox by David Firth.
>
>  http://go.warwick.ac.uk/pdfjam
>
> Best,
> Tobias
>
>
>  On Wed, Apr 14, 2010 at 6:52 AM, Tobias Verbeke <
>> [hidden email] <mailto:[hidden email]>>
>> wrote:
>>
>>    Hi Sébastien,
>>
>>
>>    Sébastien Bihorel wrote:
>>
>>        I am currently writing the documentation for my first package. I
>>        have
>>        created a short user manual using sweave/pdflatex which is
>>        distinct from the
>>        manual/summary-of-package-functions created by R CMD CHECK. I
>>        was wondering
>>        how could I seamlessly combine both documents.
>>
>>
>>    It is common to have
>>    - technical documentation in your .Rd files (in the man/ directory
>>       of your package)
>>    - functional documentation as a so-called vignette (Sweave file
>>       documenting concrete use of your package) in the
>>       inst/doc directory of your package.
>>
>>
>> http://cran.r-project.org/doc/manuals/R-exts.html#Writing-package-vignettes
>>
>>    Combining both documents into one file is not common.
>>
>>    I hope this helps,
>>    Tobias
>>
>>
>>
>
        [[alternative HTML version deleted]]


______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Reply | Threaded
Open this post in threaded view
|

Re: R package documentation

Sharpie
In reply to this post by Sébastien Bihorel-3
pomchip wrote
Dear R users,

I am currently writing the documentation for my first package. I have
created a short user manual using sweave/pdflatex which is distinct from the
manual/summary-of-package-functions created by R CMD CHECK. I was wondering
how could I seamlessly combine both documents.

Thanks for your help

Sebastien
The .Rd files are normally kept separate from the vignette- this is because Rd files have to be translated into several different formats such as html, man pages and pdf.  The vignette allows for a more free-form discussion as it does not have the rigid structure that allows .Rd files to be translated.

That being said, you could add the contents of .Rd files to something like an appendix in your vignette by converting the .Rd files to .tex and including them in your Sweave source.  Something like the following would convert each .Rd file and append it to a single .tex file (on UNIX/Linux systems):

  cd yourPackage/man
  ls *.Rd | xargs -I % R CMD Rdconv -t latex % >> manPages.tex

You could then move manPages.tex to yourPackage/inst/doc and include int in your Sweave source via \input{}.  You will need to ensure $R_HOME/share/texmf is on your tex search path as the LaTeX compiler will need Rd.sty to define some of the macros in the code produced by R CMD Rdconv.

Hope this helps!

-Charlie
Charlie Sharpsteen
Undergraduate-- Environmental Resources Engineering
Humboldt State University
Reply | Threaded
Open this post in threaded view
|

Re: R package documentation

David Scott-6
In reply to this post by Sébastien Bihorel-3
Sébastien Bihorel wrote:
> Thanks Tobias,
>
> If there is no automated way to combine both documents, I will stack them
> manually... that will likely cause some problems with page numbering tough.
>
> Sebastien
>

There was a thread a while back (this year) about someone who wanted to
incorporate his package manual in his thesis. A solution was offered to
this as I recall and it seems like the same problem to me.

What you need is the LaTeX that comes out of the package check. Just add
it to your vignette LaTeX and that should do the trick.

David

_________________________________________________________________
David Scott Department of Statistics
                The University of Auckland, PB 92019
                Auckland 1142,    NEW ZEALAND
Phone: +64 9 923 5055, or +64 9 373 7599 ext 85055
Email: [hidden email],  Fax: +64 9 373 7018

Director of Consulting, Department of Statistics

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Reply | Threaded
Open this post in threaded view
|

Re: R package documentation

Sébastien Bihorel-3
Thanks David,

After a bit of research, I believe that I've found the post you are
referring to:

http://tolstoy.newcastle.edu.au/R/e9/help/10/03/8779.html

I will look into the proposed solutions.

Sebastien

On Wed, Apr 14, 2010 at 6:01 PM, David Scott <[hidden email]> wrote:

> Sébastien Bihorel wrote:
>
>> Thanks Tobias,
>>
>> If there is no automated way to combine both documents, I will stack them
>> manually... that will likely cause some problems with page numbering
>> tough.
>>
>> Sebastien
>>
>>
> There was a thread a while back (this year) about someone who wanted to
> incorporate his package manual in his thesis. A solution was offered to this
> as I recall and it seems like the same problem to me.
>
> What you need is the LaTeX that comes out of the package check. Just add it
> to your vignette LaTeX and that should do the trick.
>
> David
>
> _________________________________________________________________
> David Scott     Department of Statistics
>                The University of Auckland, PB 92019
>                Auckland 1142,    NEW ZEALAND
> Phone: +64 9 923 5055, or +64 9 373 7599 ext 85055
> Email:  [hidden email],  Fax: +64 9 373 7018
>
> Director of Consulting, Department of Statistics
>
>
        [[alternative HTML version deleted]]


______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Reply | Threaded
Open this post in threaded view
|

Re: R package documentation

David Scott-6
Sébastien Bihorel wrote:

> Thanks David,
>
> After a bit of research, I believe that I've found the post you are
> referring to:
>
> http://tolstoy.newcastle.edu.au/R/e9/help/10/03/8779.html
>
> I will look into the proposed solutions.
>
> Sebastien
>
>

Yes, that is the thread I was referring to.

David

_________________________________________________________________
David Scott Department of Statistics
                The University of Auckland, PB 92019
                Auckland 1142,    NEW ZEALAND
Phone: +64 9 923 5055, or +64 9 373 7599 ext 85055
Email: [hidden email],  Fax: +64 9 373 7018

Director of Consulting, Department of Statistics

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.