Documentation Update / Issue Tracker Cleaning

[coatless]

I'm aiming to update some documentation hopefully in time for the 0.12.6 push and subsequently when I'll be covering Rcpp in class.

Documentation Specific Issues

The issues that I am looking to resolve are:

• Rcpp-quickrefs issue #484 opened on May 29 Rcpp-quickrefs issue
• Long vector Rcpp function fails on Windows server, C function works #460 opened on Apr 12 Long vector Rcpp function fails on Windows server, C function works
• Strange behavior with CharacterVector and std::sort #419 opened on Jan 14 Strange behavior with CharacterVector and std::sort
• Document default arguments in Rcpp FAQ #418 opened on Jan 13 Document default arguments in Rcpp FAQ
• Add documentation for RCPP_EXPOSED_AS and similar macros in the vignette #416 opened on Jan 13 Add documentation for RCPP_EXPOSED_AS and similar macros in the vignette
• Coding Standards note ? #317 opened on Jun 30, 2015 Coding Standards note ?
• Problem with automatic RNG scoping #268 opened on Feb 26, 2015 Problem with automatic RNG scoping
• Convert uses of inline::cxxfunction to attributes.  #56 opened on Nov 15, 2013 Convert uses of inline::cxxfunction to attributes.

Outside of the above issues I will also try to do the following:

• 1. Rcpp Beginners Vignette / New Rcpp Introduction #524 Introduce an "Rcpp beginners" vignette to serve as an "Rcpp Introductory" vignette
• 2. Move the current "Rcpp Introduction" to "Rcpp JSS Paper" as the present title is a bit misleading per SO.
• 3. Switch Rcpp Vignette Engine away from highlight #604 Try to switch the present vignettes over to use knitr or rmarkdown if there is no objection. Principal motivation for this change is due to the present way being a bit adhoc and non-standard with respect to highlight.

Closing Issues

Lastly, depending on time, I'm going to try to bring the issue tracker up to date by finding the resolution to associated issues via PRs or git commits and asking that those issues are closed.

Items completed, but not closed

• Rcpp::algorithm proposal #426 opened on Jan 18 Rcpp::algorithm proposal
• Underlying CHARSXP in String class needs gc protection #321 opened on Jul 6, 2015 Underlying CHARSXP in String class needs gc protection
• Rcpp 0.11.5 test failures with new Rtools toolchain #277 opened on Mar 15, 2015 Rcpp 0.11.5 test failures with new Rtools toolchain
• Macros like 'major' still leak, or are protected too aggressively #272 opened on Mar 9, 2015 Macros like 'major' still leak, or are protected too aggressively
• Sugar var() only knows numeric #223 opened on Jan 2, 2015 Sugar var() only knows numeric
• ListOf<>::names() and ::attr() #183 opened on Sep 23, 2014 ListOf<>::names() and ::attr()
• bool not converted to LogicalVector as expected #177 opened on Sep 13, 2014 bool not converted to LogicalVector as expected
• Two constructors of Vector class not meaningful #170 opened on Aug 30, 2014 Two constructors of Vector class not meaningful
• Rcpp-extending: implementing Rcpp:wrap() for a templated type #165 opened on Aug 8, 2014 Rcpp-extending: implementing Rcpp:wrap() for a templated type
• .parseLinkingTo fails with versioned LinkingTo #145 opened on May 18, 2014 .parseLinkingTo fails with versioned LinkingTo
• Allow user to enable/disable bounds checking #137 opened on Apr 10, 2014 Allow user to enable/disable bounds checking
• ListOf<T> class #135 opened on Mar 18, 2014 ListOf class
• Attributes vignette and Imports/Depends distinction #130 opened on Mar 13, 2014 Attributes vignette and Imports/Depends distinction
• Matrix default ctor does not make a matrix #129 opened on Mar 13, 2014 Matrix default ctor does not make a matrix
• Bug in assigning SEXP to List #128 opened on Mar 11, 2014 Bug in assigning SEXP to List
• update OSX information in FAQ vignette #80 opened on Nov 30, 2013 update OSX information in FAQ vignette
• NEWS.Rd is stale #76 opened on Nov 29, 2013 NEWS.Rd is stale
• ChangeLog is stale #75 opened on Nov 29, 2013 ChangeLog is stale
• checking for interupts #69 opened on Nov 25, 2013 checking for interupts
• tests for automatically generated math functions #30 opened on Nov 6, 2013 tests for automatically generated math functions
• tests for dpq functions #29 opened on Nov 6, 2013 tests for dpq functions
• operator/ needs to handle the case of division by 0 #22 opened on Nov 6, 2013 operator/ needs to handle the case of division by 0
• logical indexing #16 opened on Nov 6, 2013 logical indexing
• Vignette about stats function #9 opened on Nov 6, 2013 Vignette about stats function
• Sugar ops unit tests #6 opened on Nov 6, 2013 Sugar ops unit tests

Items not completed

• Error messaging suggestion #308 opened on Jun 23, 2015 Error messaging suggestion
  • Support presently exists for GCC 4.6.2 <= in the code base and given the nature of R's RHEL component, it is inadvisable to trigger a warning within Rcpp. Best to let it play out on required code bases (e.g. RcppArmadillo).
• Rcpp::SquareMatrix class #229 opened on Jan 16, 2015 Rcpp::SquareMatrix class
  • No desire to support a square matrix class without accompanying algorithms
• More flexible attributes #37 opened on Nov 7, 2013 More flexible attributes
  • Project to abstract away attributes has been moved to a new location

Quick code fixes

• Autogeneration Warning for RcppExports.* #526 opened on Aug 1 Autogeneration Warning for RcppExports.
• Fix invalid C++ identifiers #387 opened on Oct 30, 2015 Fix invalid C++ identifiers
• Environment::(get,find)( Symbol ) #326 opened on Jul 17, 2015 Environment::(get,find)( Symbol )
• tests for random generators #28 opened on Nov 6, 2013 tests for random generators

Possible future code projects

• Two constructors of Vector class not meaningful #170 opened on Aug 30, 2014 Two constructors of Vector class not meaningful
  • Remark: The two constructors are still in place to save:CharacterVector x = std::string("hello"); could this feature be deprecated in favor of ::create()?
• Sugar ops unit tests #6 opened on Nov 6, 2013 Sugar ops unit tests
  • Remark: Possible feature: Matrix Multiplication (perhaps use the % operator for element-wise manipulation similar to armadillo?) and Matrix to Matrix Addition.

[jjallaire]

With respect to switching to knitr/rmarkdown, you should note that the development version of knitr now handles caching of Rcpp chunks correctly, see http://rmarkdown.rstudio.com/authoring_knitr_engines.html#rcpp

[eddelbuettel]

Regarding:

• point 2: I was about to do it but then relented -- we have a ton of advice out there saying 'start by vignette("Rcpp-introduction")' so I no longer think we want that.
• point 3: I am not sure I am in favour of a wholesale replacement of pdf by html. I like both very much and still think pdf vignette render much better and generally look better so I think there is room to keep pdf
• point 1: contributed documentation is always welcome, I'd be happy to help / get involved as we discussed.

[jjallaire]

Switching to rmarkdown could still preserve pdf output. If we wanted full
control of the LaTex (i.e. identical appearance to current vignettes) we
could even create an rcpp_vignette custom format)
On Sat, Jul 16, 2016 at 7:23 AM Dirk Eddelbuettel notifications@github.com
wrote:

Regarding:

point 2: I was about to do it but then relented -- we have a ton of
advice out there saying 'start by vignette("Rcpp-introduction")' so I
no longer think we want that.

point 3: I am not sure I am in favour of a wholesale replacement of
pdf by html. I like both very much and still think pdf vignette render much
better and generally look better so I think there is room to keep pdf

point 1: contributed documentation is always welcome, I'd be happy to
help / get involved as we discussed.

—
You are receiving this because you commented.

Reply to this email directly, view it on GitHub
#506 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAGXx6EtPIaenMEZQSAna6culFds2AWjks5qWL87gaJpZM4JN6-J
.

[eddelbuettel]

Quite true on .md to .pdf as a process which is in fact what I do often. But having written the book I can assert that dealing with nine vignettes and rewriting them is not a small task, and if anybody can muster that much energy then maybe we should focus the energy somewhere else? In principle this can be done -- and replacing use of highlight by pandoc would be nice. In practice I have some doubts. As for a custom vignette format which looks good in pdf and html, I'd be a taker. We don't have that now, do we? (I not to beat a dead horse but current bookdown output is far from stylish too...)

[coatless]

• On point 2: Wouldn't that make it better to proceed with the change once the beginners vignette is ready? I ask since that is where the flock of users are going to initially. The alternative is probably naming the beginners vignette more as a Quick Start
• On point 3: I agree that it is labour intensive. Perhaps, let's do a slight demo with one of the smaller vignettes?

[eddelbuettel]

• point 2: come to think about it, once we have a new vignette with an intro, we can have it provide the Rcpp-introduction target and rename the current one to Rcpp-jsspaper. That intro could even be a quick two-pager with a quick start example and a pointer for further references.
• point 3: Oh yes. We should just pick. Or start with the intro.

In other words, I think we can clearly have a nice new Rcpp-intro (in markdown, and possibly with output in pdf and html as @jjallaire volunteered 😸 a new style file) for 0.12.7 in two months.

[coatless]

@eddelbuettel Any chance I could squeeze the beginners vignette into the 0.12.6 release? More specifically, do you have a date in mind for 0.12.6 release? I ask because I will hopefully have the two pager done by tomorrow. I'm presently working on it in between cluster runs.

[eddelbuettel]

The date is basically ... tomorrow or Monday. So I am hesitant. That said, this would make for an excellent candidate for 0.12.6.1 where we can test the transition to a new Rcpp-introduction. And by being on a drat repo your students can install.packages() it as normal.

So in short I'd rather not ram it in.

[coatless]

@eddelbuettel Okay. Definitely agree as tomorrow/monday would be too quick of a turn around time. I was hoping for later in the week. I'll inoculate them to drat before Rcpp.

Would you prefer a flood of completes or should I move through the items one at a time?

[eddelbuettel]

Thanks -- I am thinking an issue per item may make sense. Maybe even just continue on the old items but keep another one (this one?) as a jumping board?

[ I recently needed a tick-off list to collect 'ok by me' replies for digest -- maybe something like that could help? We could just prefix your nice list above... ]