New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Switch Rcpp Vignette Engine away from highlight #604

Closed
coatless opened this Issue Dec 4, 2016 · 7 comments

Comments

Projects
None yet
3 participants
@coatless
Contributor

coatless commented Dec 4, 2016

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

This comment has been minimized.

Show comment
Hide comment
@coatless

coatless Dec 31, 2016

Contributor

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
---
Contributor

coatless commented Dec 31, 2016

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

This comment has been minimized.

Show comment
Hide comment
@coatless

coatless Jan 1, 2017

Contributor

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

Contributor

coatless commented Jan 1, 2017

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

This comment has been minimized.

Show comment
Hide comment
@eddelbuettel

eddelbuettel Jan 1, 2017

Member

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.

Member

eddelbuettel commented Jan 1, 2017

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

This comment has been minimized.

Show comment
Hide comment
@jjallaire

jjallaire Jan 1, 2017

Member
Member

jjallaire commented Jan 1, 2017

@eddelbuettel

This comment has been minimized.

Show comment
Hide comment
@eddelbuettel

eddelbuettel Jan 1, 2017

Member

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

  • nicer (less boring, computer modern) font without blowing up size, pdf is good for that
  • nice code highlighting with good defaults for R and C++ (many options based on hightlight now)
  • shaded code boxen (easy enough in latex, exists currently)
  • as a new feature maybe wrap into a different latex style template (ie koma-script and alike)

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.

Member

eddelbuettel commented Jan 1, 2017

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

  • nicer (less boring, computer modern) font without blowing up size, pdf is good for that
  • nice code highlighting with good defaults for R and C++ (many options based on hightlight now)
  • shaded code boxen (easy enough in latex, exists currently)
  • as a new feature maybe wrap into a different latex style template (ie koma-script and alike)

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

This comment has been minimized.

Show comment
Hide comment
@coatless

coatless Jan 6, 2017

Contributor

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.

Contributor

coatless commented Jan 6, 2017

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

This comment has been minimized.

Show comment
Hide comment
@eddelbuettel

eddelbuettel Mar 13, 2017

Member

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...

Member

eddelbuettel commented Mar 13, 2017

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...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment