R devel - Oct 2004 - R-exts.texi: suggestion for small change to Vignette section (PR#7323)

I recently wrote a vignette, with the following at the top of the .Rnw
file:

%%\VignetteIndexEntry{How to use look up tables for h() functions}
%%\VignetteDepends{sjedmin, spatstat}

Using vExplorer() on this function, I got an error from this part of
getVigInfo():

    lines <- grep("^%[[:space:]]*\\\\Vignette", file)
    if (length(lines) == 0) 
        stop("File ", vig, " does not appear to be a vignette
file, ",
            "no vignette metadata available.")

The error occurs here because the grep expects only one % at the start
of the line, whereas I had %%.  (I often use two at the start of a
line as I'm used to the ESS/Emacs coding habits of putting ## at the
start of a line.)  Changing %% to % solved the problem okay.  

So, my minor suggestion to R-exts.texi, at line 1011:

@code{\VignetteIndexEntry} statement is best placed in La@TeX{} comment,

is that maybe it should say either:

"in a La@TeX{} comment"

or 

"in a La@TeX{} comment with a single %"

although admittedly that sounds a bit clunky!

Thanks, Stephen

>>>>> S J Eglen writes:
> I recently wrote a vignette, with the following at the top of the .Rnw
> file:
> %%\VignetteIndexEntry{How to use look up tables for h() functions}
> %%\VignetteDepends{sjedmin, spatstat}
> Using vExplorer() on this function, I got an error from this part of
> getVigInfo():
>     lines <- grep("^%[[:space:]]*\\\\Vignette", file)
>     if (length(lines) == 0) 
>         stop("File ", vig, " does not appear to be a
vignette file, ",
>             "no vignette metadata available.")
> The error occurs here because the grep expects only one % at the start
> of the line, whereas I had %%.  (I often use two at the start of a
> line as I'm used to the ESS/Emacs coding habits of putting ## at the
> start of a line.)  Changing %% to % solved the problem okay.  
> So, my minor suggestion to R-exts.texi, at line 1011:
> @code{\VignetteIndexEntry} statement is best placed in La@TeX{} comment,
> is that maybe it should say either:
> "in a La@TeX{} comment"
> or 
> "in a La@TeX{} comment with a single %"
> although admittedly that sounds a bit clunky!
Hmm, why not change the Sweave code to support multiple comment chars?

The code for index computations on vignettes is based on

vignetteMetaRE <- function(tag)
    paste("[[:space:]]*%+[[:space:]]*\\\\Vignette", tag,
          "\{([^}]*)\}", sep = "")

-k

Is this not a bug in `vExplorer' (unexplained, but I believe in a BioC 
package -- by no means all R users have any experience of BioC)?

Why change the docs to a limitation of some application not part of 
core R?  

I do wonder why you sent this to R-bugs and not to the maintainer of
vExplorer.  Or was this a very minor comment on English grammar padded by 
something not relevant?

On Fri, 29 Oct 2004 S.J.Eglen@damtp.cam.ac.uk wrote:
> I recently wrote a vignette, with the following at the top of the .Rnw
> file:
> 
> %%\VignetteIndexEntry{How to use look up tables for h() functions}
> %%\VignetteDepends{sjedmin, spatstat}
> 
> Using vExplorer() on this function, I got an error from this part of
> getVigInfo():
> 
>     lines <- grep("^%[[:space:]]*\\\\Vignette", file)
>     if (length(lines) == 0) 
>         stop("File ", vig, " does not appear to be a
vignette file, ",
>             "no vignette metadata available.")
> 
> The error occurs here because the grep expects only one % at the start
> of the line, whereas I had %%.  (I often use two at the start of a
> line as I'm used to the ESS/Emacs coding habits of putting ## at the
> start of a line.)  Changing %% to % solved the problem okay.  
> 
> So, my minor suggestion to R-exts.texi, at line 1011:
> 
> @code{\VignetteIndexEntry} statement is best placed in La@TeX{} comment,
> 
> is that maybe it should say either:
> 
> "in a La@TeX{} comment"
> 
> or 
> 
> "in a La@TeX{} comment with a single %"
> 
> although admittedly that sounds a bit clunky!
> 
> Thanks, Stephen
> 
> ______________________________________________
> R-devel@stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
> 
> 
-- 
Brian D. Ripley,                  ripley@stats.ox.ac.uk
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

>>>>> On Fri, 29 Oct 2004 12:47:46 +0200 (CEST),
>>>>> S J Eglen (SJE) wrote:
  > I recently wrote a vignette, with the following at the top of the .Rnw
  > file:

  > %%\VignetteIndexEntry{How to use look up tables for h() functions}
  > %%\VignetteDepends{sjedmin, spatstat}

  > Using vExplorer() on this function, I got an error from this part of
  > getVigInfo():

  >     lines <- grep("^%[[:space:]]*\\\\Vignette", file)
  >     if (length(lines) == 0) 
  >         stop("File ", vig, " does not appear to be a
vignette file, ",
  >             "no vignette metadata available.")

  > The error occurs here because the grep expects only one % at the start
  > of the line, whereas I had %%.  (I often use two at the start of a
  > line as I'm used to the ESS/Emacs coding habits of putting ## at the
  > start of a line.)  Changing %% to % solved the problem okay.  

  > So, my minor suggestion to R-exts.texi, at line 1011:

  > @code{\VignetteIndexEntry} statement is best placed in La@TeX{} comment,

  > is that maybe it should say either:

  > "in a La@TeX{} comment"

  > or 

  > "in a La@TeX{} comment with a single %"

  > although admittedly that sounds a bit clunky!


That's a bug in getVigInfo(), not a bug in the R documentation (I also
use %% for the same reason).

Jeff: the regexp should certainly be ^%+[[:space:]]*\\\\Vignette", but
there is now also code in package tools which can be used to extract
the info directly.

Best,
Fritz