search

RcppCore / Rcpp

Seamless R and C++ Integration
https://www.rcpp.org
GNU General Public License v2.0
731 stars 210 forks source link

Switch Rcpp Vignette Engine away from highlight #604

Closed coatless closed 7 years ago

coatless commented 7 years ago

Rcpp vignettes presently uses the highlight package that mandates a non-standard approach to rendering the documentation.

Switching away from this engine to either knitr or rmarkdown requires...

Knitr

In each vignette, the following must be changed:

%\VignetteEngine{highlight::highlight}

To 

%\VignetteEngine{knitr::knitr}

In the DESCRIPTION file replace:

VignetteBuilder: highlight

with 

VignetteBuilder: knitr

And add 

Suggests: knitr

Switch each code chunk to use knitr options:

<<>>=
@

RMarkdown

In each vignette, YML matter must be added:

---
title: "Vignette Title"
author: "Vignette Author"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

The rmarkdown::html_vignette can be customized using RMarkdown Templates (I've had success with uiucthemes). So, the current Rcpp vignette style could be ported to an embedded style function call.

In addition, code segments must be switched over to using the GFM code ticked fence design.

However, this involves more work potentially porting over LaTeX syntax to use native RMarkdown to take full advantage of the format.

Related to #506 and should be associated with #602

coatless commented 7 years ago

Probably going to go down the RMarkdown route.

The main issue is the custom syntax in a few files (e.g. \sugar) would only really be viable in LaTeX unless there is a way to custom define syntax for multiple renders that I've overlooked...

Outside of that, using parameterized reports the date and version information can easily be placed within the document. 

---
title: "Rcpp syntactic sugar"
author: 'Dirk Eddelbuettel and Romain François'
date: '`r paste("Rcpp version", params$prettyVersion, "as of", params$prettyDate)`'
output:
  rcpp_vignette
params:
  prettyDate: !r format(Sys.Date(), "%B %e, %Y")
  prettyVersion: !r packageDescription("Rcpp")$Version
bibliography: Rcpp.bib
---
coatless commented 7 years ago

Still have a way to go with matching the templates. But, here is an initial rendering using the Sugar vignette:

New: Rcpp-sugar.pdf

vs.

Old: Rcpp-sugar.pdf

eddelbuettel commented 7 years ago

Sorry but I am really no fan of the font.

I happen like the old vignettes.

I am with you in principle as these days I do write new content in markdown (even if that becomes latex and pdf, nice current example with a paper draft) but I am not that in practice I have a lot of energy for convergence exercises. We'll see.

Happy 2017.

jjallaire commented 7 years ago

We could always create a brand new R Markdown template which uses the old vigette's LaTeX as it's starting point.

On Sun, Jan 1, 2017 at 1:26 AM, Dirk Eddelbuettel notifications@github.com wrote:

Sorry but I am really no fan of the font.

I happen like the old vignettes.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/RcppCore/Rcpp/issues/604#issuecomment-269893566, or mute the thread https://github.com/notifications/unsubscribe-auth/AAGXx5I7tqrdaBPo8mPf0tnjlNRlz1qwks5rN0cdgaJpZM4LDfQu .

eddelbuettel commented 7 years ago

And we could start list with a set of features we want.

ie if someone insists on doing all this work (hi, @coatless) the outcome should be something professional and markedly better than what we have right now. Think "10x argument" to induce switching to something new. Don't take ten too literally. My main point is to take a switch worthwhile it has to offer something.

And in aggregate I still think this makes it a lower-priority item.

coatless commented 7 years ago

I agree that the switch is a lower priority item, however, it is an item that is important for the primary reason that it enables easier contributions to documentation (c.f. #433 rendering issues and required add-on script). Moreover, as the API docs (#602) come online, there is the new dependency of rmarkdown. So, why not make a push to employ rmarkdown in multiple areas?

With this being said, the objective behind showing progress was to indicate a valid path was found and the results weren't too disappointing. In the interim, new concrete targets were introduced that provide a guiding force for whether a switch should occur.

Touching on these points briefly, we have:

  1. Are you referring to the microtype and mathdesign font packages used in the vignettes? Alternatively, would you be interested in a Roboto variant?
  2. rmarkdown hands off the syntax highlight job to pandoc, which in turn uses highlighting-kate to parse the code. This is slightly problematic when it comes to specifying new color schemes as $highlighting-macros$ within the document must be overridden. However, this also allows for any color scheme outside of the 7 different schemes offered by pandoc (scroll to examples). Glancing quickly at the present code highlighting solution, highlight, it seems as either kwrite or emacs is the default theme whose values could be extracted and placed in the right token process.
  3. Regarding the "shaded code boxen", do you mean a border around a code box? E.g. The vignettes presently define a highlight box hlbox with a darker border.
  4. The documentclass needs to shift from article to scrartcl (doc class references).

Regarding the conversion process, the majority of the work once the template is concocted is to run:

# in shell
pandoc Rcpp-vignette.tex -o Rcpp-vignette.md

Clean up Rcpp-vignette.md, switch file extension to Rcpp-vignette.Rmd, double check render, go down to the Windsor have a pint and wait till it all blows over.

eddelbuettel commented 7 years ago

Conversion to md is not really a high-enough priority to keep this open.

But if I close this, as I have in the past with related ones, @coatless will just come back and open a new one so I'll trick him now and leave this open...