Thanks for the helpful replies.
Regarding the source: I see that in ..../grid/inst/doc there are no
pdfs and no index.html, so that confirms that index.html is generated
by the \VignetteIndexEntry method using Snw/Rnw when the grid package
is built. That is helpful for me but not the main point of my posting.
To zoom out: the goal of my posting was to suggest that the "Writing
package vignettes" (section 1.4) documentation could be improved with
a few small changes that might smooth the way for future new package
developers, and it is clear I misunderstood some aspects of what it
was trying to say because, well, it is not completely clear to
someone who is not already familiar with the details. I received an
off-list message confirming similar bumps from someone else when they
tried making a vignette for the first time.
Now I understand that the "pointers from packages" statements did not
refer to vignettes; I guess my confusion on that was that it appears
in the first paragraph of the "Writing package vignettes" section,
but I see the next paragraph should have set me straight. At the
least the point that the %\VignetteIndexEntry comment in section 1.4
is obtuse and does not provide the reader with sufficient information
of how to do this still seems valid. The successful creation of
index.html appeared from my explorations to go hand-in-hand with
successful recognition by R that the vignette exists, but I see that
it is for the HTML system only, and, again, I was left with some
guesswork after reading section 1.4.
The R manuals are amazing and I many others are indebted to those who
wrote them. I remember seeing a posting at some point about the
value of finding documentation bugs as well as code bugs, so when I
saw that section 1.4 falls short of explaining how to easily and
successfully set up a vignette (or include a pdf directly, which I
now see is not a vignette), I thought I would point it out (and
volunteer to help if I could, with help from one of the experts).
Undoubtedly the section makes perfect sense to someone who already
knows all the details, so it may be hard to see it from a newcomer's
view. I also recognize that the documentation can only be helpful to
a point and people need to spend their own time digging into things,
but I thought the totally unexplained %\VignetteIndexEntry was an
obvious case where very few additional words would be a huge help,
and perhaps a few of the other points that have arisen could also be
easily clarified.
Thanks again.
Perry
On Jan 15, 2009, at 10:34 AM, Gabor Grothendieck wrote:
I find this very confusing too.
I would also sometimes like to include pdf's that were not
generated from
Sweave and have them included in the package and listed in
library(help = mypackage) output as well as with clickable links
on the package's CRAN web page like vignettes are.
On Thu, Jan 15, 2009 at 1:27 PM, Simon Urbanek
<[email protected]> wrote:
On Jan 15, 2009, at 12:24 , Perry de Valpine wrote:
I am looking at the 2.8.1 source code in R-2.8.1/src/library/grid/
inst/doc, where there is an index.html (I am not at daily syncing
level and hope that is not an issue in this case). In this case the
Snw files contain the %\VignetteIndexEntry and associated commands,
so the index.html could have been generated by the package build (I
see the pdfs, so I assume they were generated from the Snws by
building the package. Should be I able to access a pre-build package
source? That is not what is in R-2.8.1.tar.gz but may be what you
have?).
To clarify: if I attempt to include a vignette by putting a pdf
directly in inst/doc, then R CMD BUILD does copy the pdf to the
built
package but generates an index.html that says there are no
vignettes,
so R is blind to the vignette.
That statement is wrong in the first place. R doesn't care about
index.html
when looking for package vignettes - it's generated for the HTML
help system
only (from vignettes, really). Please read "1.4 Writing package
vignettes"
in R-exts manual. Vignettes are only documents created with
Sweave. Although
you can add arbitrary documents to your package, those are not
considered
vignettes. If you have custom documents in inst/doc, you have to
supply your
own index.html (unless the default "look in ." makes you happy),
because R
creates an index file only for vignettes.
To address your original post: "Pointers from package help indices
to the
installed documents are automatically created" has nothing to do with
vignettes (note that it's talking about documents, not vignettes).
However,
AFAICT it's no longer true (at least 00Index.dcf seems to be
ignored), so
that may need some clarification.
Cheers,
Simon
After seeing a correctly built
index.html, I made a leap to think that if I include/modify the
index.html to treat the pdf as a vignette, that might make R see it.
However, I did not test this, and instead moved on to the Rnw method
with %\VignetteIndexEntry. For the direct pdf method, I don't know
if R CMD BUILD is intended to generate an index.html that recognizes
any pdfs present (i.e. the documentation is fine), or alternatively
if the documentation should state more completely how to include a
pdf directly as a vignette. The latter was the premise of my
earlier
post. Please let me know if that is confused or still not specific
enough. Thanks.
Perry
On Jan 15, 2009, at 7:10 AM, Gabor Grothendieck wrote:
On Wed, Jan 14, 2009 at 2:53 PM, Perry de Valpine
<[email protected]> wrote:
Dear R-devel,
I am putting together a package vignette for the first time (R
2.8.1,
OS X) and had some bumps from section 1.4 ("Writing package
vignettes") of the "Writing R Extensions" document. Here are
suggestions to clean up a few small documentation bugs (I
think) and
omissions. This is assuming that R is performing as intended
and the
only gaps are in the documentation, not vice-versa.
The statement "Pointers from package help indices to the installed
documents are automatically created" made me think I could put
a pdf
in inst/doc and it would automatically be treated as a
vignette. When
I did R CMD BUILD and R CMD INSTALL, an index.html was created in
inst/doc (and my pdf was copied there) but it stated there are no
vignettes for this package, and R indeed could not find the
vignette.
How about stating that index.html is needed and sticking in an
example?
I eventually figured it out by looking at the grid package source.
Could you please clarify this comment. I could not find an
index.html file
in the grid package source (R revision 47606 synced today):
C:\\R\src\library\grid>dir/s index.html
File Not Found
[[alternative HTML version deleted]]
______________________________________________
[email protected] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
[email protected] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
