[R-pkg-devel] handling documentation build tools

[Simon Urbanek]

Ross,

It's entirely up to you how you do this -- what you describe is something that has to happen before your run R CMD build, so it's not reflected in your package that you submit (and this has nothing to do with CRAN or R). There is nothing automatic as it requires you to do something in any case. It's entirely up to you which tools you use before you call R CMD build - it comes down to personal preferences. You have already described all that is needed: the most simple solution is to have either a Makefile or a script in your repository that does whatever you need (Makefile gives you the automatic update for free) and you put those in .Rbuildignore so they will not be part of the package source you submit as the output of R CMD build. Typically, it is customary to keep the sources (here you .lyx) in the distributed package, "tools" is one place you could do it safely, but it is not well-defined.

There is a slight variation on the above: you can (ab)use the "cleanup" script so that the process is actually run by R CMD build itself. E.g., the cleanup script could simply check if your Makefile is present (which would be only in the repo, but not in that tar ball) and simply run make in that case.

That said, as Dirk mentioned, since your output is documentation, the semantically correct way would be to treat it as a vignette, which is well-documented and specifically provides way for what you described and it is clear that it is documentation and not just some random script.

Cheers,
Simon


> On 22/05/2024, at 9:01 AM, Boylan, Ross via R-package-devel <r-package-devel using r-project.org> wrote:
> 
> I have some documentation that requires external tools to build.  I would like to build the automatically, with requiring either users or repositories to have the tools.  What's the best way to accomplish that.
> 
> Specifically one document is written using the LyX word processor, so the "source" is msep.lyx.  To convert that into something useful, a pdf, one must run lyx, which in turn requires latex.
> 
> I'm looking for recommendations about how to approach this.
> 
> A purely manual approach would be to place msep.lyx in .Rbuildignore and manually regenerate the pdf if I edit the file.
> 
> This has 2 drawbacks: first, it does not guarantee that the pdf is consistent with the current source; second, if I want to generate plain text or html versions of the document as well, the manual approach gets more tedious and error prone.
> 
> Currently I use pkgbuild::build's option to run bootstrap.R to run the lyx->pdf conversion automatically with each build.  The script is pretty specific to my build environment, and I think if I uploaded the package CRAN would end up trying to run bootstrap.R, which would fail.
> 
> Maybe the script should go in tools/? But then it won't run automatically.  Maybe the script in tools goes in .Rbuildignore and the bootstrap.R script simply checks if the tools/ script exists and runs it if present.
> 
> Suggestions?
> 
> I'm also unsure what directory msep.lyx should go in, though that's a secondary issue.  Currently it's in inst/doc, which led to problems with the build system sometimes wiping it out.  I've solved that problem.
> 
> Thanks.
> Ross
> 
> 	[[alternative HTML version deleted]]
> 
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>