- improve help for automatic updates

R/rchallenge.r

@@ -1,3 +1,18 @@
+#' @section Installation:
+#' Install the R package from \href{https://cran.r-project.org/package=rchallenge}{CRAN} repositories
+#' 
+#' \code{install.packages("rchallenge")}
+#' 
+#' or install the latest development version from \href{https://github.com/adrtod/rchallenge}{GitHub}
+#' 
+#' \code{# install.packages("devtools")}
+#' 
+#' \code{devtools::install_github("adrtod/rchallenge")}
+#' 
+#' A recent version of \href{http://johnmacfarlane.net/pandoc/}{pandoc} (>= 1.12.3) is also required. 
+#' See the \href{https://github.com/rstudio/rmarkdown/blob/master/PANDOC.md}{pandoc installation instructions} 
+#' for details on installing pandoc for your platform.
+#' 
 #' @section Getting started:
 #' Install a new challenge in \code{Dropbox/mychallenge}:
 #' 
@@ -40,21 +55,7 @@
 #' 
 #'  \item Give the \href{https://www.dropbox.com/en/help/274}{public link} to your \code{Dropbox/Public/challenge.html} file to the participants.
 #'  
-#'  \item Automate the updates of the webpage.
-#' }
-#' 
-#' For the step 4, on \strong{Unix} systems, you can setup the following 
-#' line to your \href{https://en.wikipedia.org/wiki/Cron}{crontab} using \code{crontab -e} (mind the quotes):
-#' 
-#' \code{0 * * * * Rscript -e 'rchallenge::publish("~/Dropbox/mychallenge/challenge.rmd")'}
-#' 
-#' This will publish a html webpage in your \code{Dropbox/Public} folder every hour.
-#' 
-#' On \strong{Windows} systems, you can use the \href{http://windows.microsoft.com/en-us/windows/schedule-task}{Task Scheduler} to create a new task with a \emph{Start a program} action with the settings (mind the quotes):
-#'   
-#' \itemize{ 
-#'  \item \emph{Program/script}: \code{Rscript.exe}
-#'  \item \emph{options}: \code{-e rchallenge::publish('~/Dropbox/mychallenge/challenge.rmd')}
+#'  \item Refresh the webpage by repeating step 2 on a regular basis. See below for automating this step.
 #' }
 #' 
 #' From now on, a fully autonomous challenge system is set up requiring no further 
@@ -71,6 +72,33 @@
 #'  \item \code{\link{plot_activity}}: Plots a chart of activity per team.
 #' }
 #' 
+#' @section Automating the updates on \strong{Unix/OSX}:
+#' 
+#' For the step 4, you can setup the following line to your \href{https://en.wikipedia.org/wiki/Cron}{crontab} 
+#' using \code{crontab -e} (mind the quotes):
+#' 
+#' \code{0 * * * * Rscript -e 'rchallenge::publish("~/Dropbox/mychallenge/challenge.rmd")'}
+#' 
+#' This will publish a html webpage in your \code{Dropbox/Public} folder every hour.
+#' 
+#' You might have to add the path to Rscript and pandoc at the beginning of your crontab:
+#'  
+#' \code{PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin}
+#'
+#' Depending on your system or pandoc version you might also have to explicitly add the encoding option to the command:
+#' 
+#' \code{0 * * * * Rscript -e 'rchallenge::publish("~/Dropbox/mychallenge/challenge.rmd", encoding = "utf8")'}
+#' 
+#' @section Automating the updates on \strong{Windows}:
+#' 
+#' You can use the \href{http://windows.microsoft.com/en-us/windows/schedule-task}{Task Scheduler} 
+#' to create a new task with a \emph{Start a program} action with the settings (mind the quotes):
+#'   
+#' \itemize{ 
+#'  \item \emph{Program/script}: \code{Rscript.exe}
+#'  \item \emph{options}: \code{-e rchallenge::publish('~/Dropbox/mychallenge/challenge.rmd')}
+#' }
+#' 
 #' @section Examples:
 #' \itemize{ 
 #'  \item \href{https://dl.dropboxusercontent.com/u/25867212/challenge_mimse2014.html}{My own challenge} (in french) given to Master students at the University of Bordeaux.

README.md

@@ -16,7 +16,7 @@ Further documentation is available in the [Reference manual](https://adrtod.gith
 
 Please report bugs, troubles or discussions on the [Issues](https://github.com/adrtod/rchallenge/issues) tracker. Any contribution to improve the package is welcome.
 
-### Installation
+## Installation
 Install the R package from [CRAN](https://cran.r-project.org/package=rchallenge) repositories
 ```
 install.packages("rchallenge")
@@ -27,7 +27,9 @@ or install the latest development version from [GitHub](https://github.com/adrto
 devtools::install_github("adrtod/rchallenge")
 ```
 
-### Getting started
+A recent version of [pandoc](http://johnmacfarlane.net/pandoc/) (>= 1.12.3) is also required. See the [pandoc installation instructions](https://github.com/rstudio/rmarkdown/blob/master/PANDOC.md) for details on installing pandoc for your platform.
+
+## Getting started
 Install a new challenge in `Dropbox/mychallenge`:
 <pre>
 setwd("~/Dropbox/mychallenge")
@@ -58,8 +60,7 @@ You can easily customize the challenge in two ways:
 - *During the creation of the challenge*: by using the options of the [`new_challenge`](https://adrtod.github.io/rchallenge/new_challenge.html) function.
 - *After the creation of the challenge*: by manually replacing the data files in the `data` subdirectory and the baseline predictions in `submissions/baseline` and by customizing the template `challenge.rmd` as needed.
 
-
-### Next steps
+## Next steps
 To complete the installation:
 
 1. Create and [share](https://www.dropbox.com/en/help/19) subdirectories in `submissions` for each team:
@@ -77,20 +78,8 @@ To complete the installation:
 
 3. Give the [public link](https://www.dropbox.com/en/help/274) to your `Dropbox/Public/challenge.html` file to the participants.
 
-4. Automate the updates of the webpage.
-
-For the step 4, on **Unix** systems, you can setup the following 
-line to your [crontab](https://en.wikipedia.org/wiki/Cron) using `crontab -e` (mind the quotes):
-```
-0 * * * * Rscript -e 'rchallenge::publish("~/Dropbox/mychallenge/challenge.rmd")'
-```
-This will publish a html webpage in your `Dropbox/Public` folder every hour.
-
-On **Windows** systems, you can use the [Task Scheduler](http://windows.microsoft.com/en-us/windows/schedule-task) to create a new task with a *Start a program* action with the settings (mind the quotes):
+4. Refresh the webpage by repeating step 2 on a regular basis. See below for automating this step.
 
-- *Program/script*: `Rscript.exe`
-- *options*: `-e rchallenge::publish('~/Dropbox/mychallenge/challenge.rmd')`
-
 From now on, a fully autonomous challenge system is set up requiring no further 
 administration. With each update, the program automatically performs the following
 tasks using the functions available in our package:
@@ -105,14 +94,41 @@ Name | Description
 [`plot_history`](https://adrtod.github.io/rchallenge/plot_history.html) | Plots a chart of score evolution per team.
 [`plot_activity`](https://adrtod.github.io/rchallenge/plot_activity.html) | Plots a chart of activity per team.
 
-### Examples
+## Automating the updates
+
+### Unix/OSX
+
+You can setup the following line to your [crontab](https://en.wikipedia.org/wiki/Cron) using `crontab -e` (mind the quotes):
+```
+0 * * * * Rscript -e 'rchallenge::publish("~/Dropbox/mychallenge/challenge.rmd")'
+```
+This will publish a html webpage in your `Dropbox/Public` folder every hour.
+
+You might have to add the path to Rscript and pandoc at the beginning of your crontab:
+```
+PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
+```
+
+Depending on your system or pandoc version you might also have to explicitly add the encoding option to the command:
+```
+0 * * * * Rscript -e 'rchallenge::publish("~/Dropbox/mychallenge/challenge.rmd", encoding = "utf8")'
+```
+
+### Windows
+
+You can use the [Task Scheduler](http://windows.microsoft.com/en-us/windows/schedule-task) to create a new task with a *Start a program* action with the settings (mind the quotes):
+
+- *Program/script*: `Rscript.exe`
+- *options*: `-e rchallenge::publish('~/Dropbox/mychallenge/challenge.rmd')`
+
+## Examples
 - [My own challenge](https://dl.dropboxusercontent.com/u/25867212/challenge_mimse2014.html) (in french) given to Master students at the University of Bordeaux.
 
 - [A classification and variable selection problem](https://dl.dropboxusercontent.com/u/50849929/challenge_fr.html) (in french) given by Robin Genuer (Bordeaux).
 
 Please [contact me](https://sites.google.com/site/adrientodeschini/) to add yours.
 
-### Copyright
+## Copyright
 Copyright (C) 2014-2015 [Adrien Todeschini](https://sites.google.com/site/adrientodeschini/).
 
 Contributions from [Robin Genuer](http://robin.genuer.fr/).
@@ -122,7 +138,7 @@ for data science challenges.
 
 The **rchallenge** package is licensed under the GPLv2 (https://www.gnu.org/licenses/gpl-2.0.html).
 
-### To do list
+## To do list
 - [ ] common leaderboard for several metrics
 - [ ] do not take baseline into account in ranking
 - [ ] examples, tests, vignettes

inst/web/index.html

@@ -69,7 +69,7 @@ <h1>rchallenge</h1>
 
 <p>Please report bugs, troubles or discussions on the <a href="https://github.com/adrtod/rchallenge/issues">Issues</a> tracker. Any contribution to improve the package is welcome.</p>
 
-<h3>Installation</h3>
+<h2>Installation</h2>
 
 <p>Install the R package from <a href="https://cran.r-project.org/package=rchallenge">CRAN</a> repositories</p>
 
@@ -82,7 +82,9 @@ <h3>Installation</h3>
 devtools::install_github(&quot;adrtod/rchallenge&quot;)
 </code></pre>
 
-<h3>Getting started</h3>
+<p>A recent version of <a href="http://johnmacfarlane.net/pandoc/">pandoc</a> (&gt;= 1.12.3) is also required. See the <a href="https://github.com/rstudio/rmarkdown/blob/master/PANDOC.md">pandoc installation instructions</a> for details on installing pandoc for your platform.</p>
+
+<h2>Getting started</h2>
 
 <p>Install a new challenge in <code>Dropbox/mychallenge</code>:</p>
 
@@ -133,7 +135,7 @@ <h3>Getting started</h3>
 <li><em>After the creation of the challenge</em>: by manually replacing the data files in the <code>data</code> subdirectory and the baseline predictions in <code>submissions/baseline</code> and by customizing the template <code>challenge.rmd</code> as needed.</li>
 </ul>
 
-<h3>Next steps</h3>
+<h2>Next steps</h2>
 
 <p>To complete the installation:</p>
 
@@ -153,24 +155,9 @@ <h3>Next steps</h3>
 
 <p>Prior to this, make sure you <a href="https://www.dropbox.com/enable_public_folder">enabled your Public Dropbox folder</a>.</p></li>
 <li><p>Give the <a href="https://www.dropbox.com/en/help/274">public link</a> to your <code>Dropbox/Public/challenge.html</code> file to the participants.</p></li>
-<li><p>Automate the updates of the webpage.</p></li>
+<li><p>Refresh the webpage by repeating step 2 on a regular basis. See below for automating this step.</p></li>
 </ol>
 
-<p>For the step 4, on <strong>Unix</strong> systems, you can setup the following 
-line to your <a href="https://en.wikipedia.org/wiki/Cron">crontab</a> using <code>crontab -e</code> (mind the quotes):</p>
-
-<pre><code>0 * * * * Rscript -e &#39;rchallenge::publish(&quot;~/Dropbox/mychallenge/challenge.rmd&quot;)&#39;
-</code></pre>
-
-<p>This will publish a html webpage in your <code>Dropbox/Public</code> folder every hour.</p>
-
-<p>On <strong>Windows</strong> systems, you can use the <a href="http://windows.microsoft.com/en-us/windows/schedule-task">Task Scheduler</a> to create a new task with a <em>Start a program</em> action with the settings (mind the quotes):</p>
-
-<ul>
-<li><em>Program/script</em>: <code>Rscript.exe</code></li>
-<li><em>options</em>: <code>-e rchallenge::publish(&#39;~/Dropbox/mychallenge/challenge.rmd&#39;)</code></li>
-</ul>
-
 <p>From now on, a fully autonomous challenge system is set up requiring no further 
 administration. With each update, the program automatically performs the following
 tasks using the functions available in our package:</p>
@@ -211,7 +198,37 @@ <h3>Next steps</h3>
 </tr>
 </tbody></table>
 
-<h3>Examples</h3>
+<h2>Automating the updates</h2>
+
+<h3>Unix/OSX</h3>
+
+<p>You can setup the following line to your <a href="https://en.wikipedia.org/wiki/Cron">crontab</a> using <code>crontab -e</code> (mind the quotes):</p>
+
+<pre><code>0 * * * * Rscript -e &#39;rchallenge::publish(&quot;~/Dropbox/mychallenge/challenge.rmd&quot;)&#39;
+</code></pre>
+
+<p>This will publish a html webpage in your <code>Dropbox/Public</code> folder every hour.</p>
+
+<p>You might have to add the path to Rscript and pandoc at the beginning of your crontab:</p>
+
+<pre><code>PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
+</code></pre>
+
+<p>Depending on your system or pandoc version you might also have to explicitly add the encoding option to the command:</p>
+
+<pre><code>0 * * * * Rscript -e &#39;rchallenge::publish(&quot;~/Dropbox/mychallenge/challenge.rmd&quot;, encoding = &quot;utf8&quot;)&#39;
+</code></pre>
+
+<h3>Windows</h3>
+
+<p>You can use the <a href="http://windows.microsoft.com/en-us/windows/schedule-task">Task Scheduler</a> to create a new task with a <em>Start a program</em> action with the settings (mind the quotes):</p>
+
+<ul>
+<li><em>Program/script</em>: <code>Rscript.exe</code></li>
+<li><em>options</em>: <code>-e rchallenge::publish(&#39;~/Dropbox/mychallenge/challenge.rmd&#39;)</code></li>
+</ul>
+
+<h2>Examples</h2>
 
 <ul>
 <li><p><a href="https://dl.dropboxusercontent.com/u/25867212/challenge_mimse2014.html">My own challenge</a> (in french) given to Master students at the University of Bordeaux.</p></li>
@@ -220,7 +237,7 @@ <h3>Examples</h3>
 
 <p>Please <a href="https://sites.google.com/site/adrientodeschini/">contact me</a> to add yours.</p>
 
-<h3>Copyright</h3>
+<h2>Copyright</h2>
 
 <p>Copyright &copy; 2014-2015 <a href="https://sites.google.com/site/adrientodeschini/">Adrien Todeschini</a>.</p>
 
@@ -231,7 +248,7 @@ <h3>Copyright</h3>
 
 <p>The <strong>rchallenge</strong> package is licensed under the GPLv2 (<a href="https://www.gnu.org/licenses/gpl-2.0.html">https://www.gnu.org/licenses/gpl-2.0.html</a>).</p>
 
-<h3>To do list</h3>
+<h2>To do list</h2>
 
 <ul>
 <li>[ ] common leaderboard for several metrics</li>

inst/web/new_challenge.html

@@ -124,7 +124,7 @@ <h2 id="examples">Examples</h2>
 # english version
 new_challenge()
 </div>
-<div class='output'>New challenge installed in: &quot;/tmp/Rtmph9QfoG&quot;
+<div class='output'>New challenge installed in: &quot;/tmp/RtmpIRRxbR&quot;
 Next steps to complete the installation:
 1. Replace the data files in the &quot;data&quot; subdirectory.
 2. Replace the baseline predictions in &quot;submissions/baseline&quot;.
@@ -136,12 +136,12 @@ <h2 id="examples">Examples</h2>
 6. Give the Dropbox public link to &quot;Dropbox/Public/challenge.html&quot; to the participants.
 7. Automate the updates of the webpage.
    On Unix systems, you can setup the following line to your crontab using &quot;crontab -e&quot;:
-    0 * * * * Rscript -e &#39;rchallenge::publish(&quot;/tmp/Rtmph9QfoG/challenge.rmd&quot;)&#39;
+    0 * * * * Rscript -e &#39;rchallenge::publish(&quot;/tmp/RtmpIRRxbR/challenge.rmd&quot;)&#39;
 </div>
 <div class='input'># french version
 new_challenge(template = &quot;fr&quot;)
 </div>
-<div class='output'>New challenge installed in: &quot;/tmp/Rtmph9QfoG&quot;
+<div class='output'>New challenge installed in: &quot;/tmp/RtmpIRRxbR&quot;
 Next steps to complete the installation:
 1. Replace the data files in the &quot;data&quot; subdirectory.
 2. Replace the baseline predictions in &quot;submissions/baseline&quot;.
@@ -153,7 +153,7 @@ <h2 id="examples">Examples</h2>
 6. Give the Dropbox public link to &quot;Dropbox/Public/challenge.html&quot; to the participants.
 7. Automate the updates of the webpage.
    On Unix systems, you can setup the following line to your crontab using &quot;crontab -e&quot;:
-    0 * * * * Rscript -e &#39;rchallenge::publish(&quot;/tmp/Rtmph9QfoG/challenge.rmd&quot;)&#39;
+    0 * * * * Rscript -e &#39;rchallenge::publish(&quot;/tmp/RtmpIRRxbR/challenge.rmd&quot;)&#39;
 </div>
 <div class='input'>setwd(wd)
 unlink(path)

inst/web/new_team.html

@@ -89,7 +89,7 @@ <h2 id="examples">Examples</h2>
 wd &lt;- setwd(path)
 new_challenge()
 </div>
-<div class='output'>New challenge installed in: &quot;/tmp/Rtmph9QfoG&quot;
+<div class='output'>New challenge installed in: &quot;/tmp/RtmpIRRxbR&quot;
 Next steps to complete the installation:
 1. Replace the data files in the &quot;data&quot; subdirectory.
 2. Replace the baseline predictions in &quot;submissions/baseline&quot;.
@@ -101,7 +101,7 @@ <h2 id="examples">Examples</h2>
 6. Give the Dropbox public link to &quot;Dropbox/Public/challenge.html&quot; to the participants.
 7. Automate the updates of the webpage.
    On Unix systems, you can setup the following line to your crontab using &quot;crontab -e&quot;:
-    0 * * * * Rscript -e &#39;rchallenge::publish(&quot;/tmp/Rtmph9QfoG/challenge.rmd&quot;)&#39;
+    0 * * * * Rscript -e &#39;rchallenge::publish(&quot;/tmp/RtmpIRRxbR/challenge.rmd&quot;)&#39;
 </div>
 <div class='input'>new_team(&quot;team_foo&quot;, &quot;team_bar&quot;)
 </div>

inst/web/publish.html

@@ -92,7 +92,7 @@ <h2 id="examples">Examples</h2>
 wd &lt;- setwd(path)
 new_challenge()
 </div>
-<div class='output'>New challenge installed in: &quot;/tmp/Rtmph9QfoG&quot;
+<div class='output'>New challenge installed in: &quot;/tmp/RtmpIRRxbR&quot;
 Next steps to complete the installation:
 1. Replace the data files in the &quot;data&quot; subdirectory.
 2. Replace the baseline predictions in &quot;submissions/baseline&quot;.
@@ -104,7 +104,7 @@ <h2 id="examples">Examples</h2>
 6. Give the Dropbox public link to &quot;Dropbox/Public/challenge.html&quot; to the participants.
 7. Automate the updates of the webpage.
    On Unix systems, you can setup the following line to your crontab using &quot;crontab -e&quot;:
-    0 * * * * Rscript -e &#39;rchallenge::publish(&quot;/tmp/Rtmph9QfoG/challenge.rmd&quot;)&#39;
+    0 * * * * Rscript -e &#39;rchallenge::publish(&quot;/tmp/RtmpIRRxbR/challenge.rmd&quot;)&#39;
 </div>
 <div class='input'>outdir = tempdir()
 publish(output_dir = outdir, output_options = list(self_contained = FALSE))
@@ -265,11 +265,11 @@ <h2 id="examples">Examples</h2>
 </div>
 <strong class='message'>output file: challenge.knit.md
 </strong>
-<div class='output'>/usr/lib/rstudio/bin/pandoc/pandoc +RTS -K512m -RTS challenge.utf8.md --to html --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash-implicit_figures --output /tmp/Rtmph9QfoG/challenge.html --smart --email-obfuscation none --standalone --section-divs --table-of-contents --toc-depth 3 --template /home/adrien-alea/R/x86_64-pc-linux-gnu-library/3.2/rmarkdown/rmd/h/default.html --variable &#39;theme:spacelab&#39; --include-in-header /tmp/Rtmph9QfoG/rmarkdown-str655335450b16.html --mathjax --variable &#39;mathjax-url:https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML&#39; --highlight-style tango 
+<div class='output'>/usr/lib/rstudio/bin/pandoc/pandoc +RTS -K512m -RTS challenge.utf8.md --to html --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash-implicit_figures --output /tmp/RtmpIRRxbR/challenge.html --smart --email-obfuscation none --standalone --section-divs --table-of-contents --toc-depth 3 --template /home/adrien-alea/R/x86_64-pc-linux-gnu-library/3.2/rmarkdown/rmd/h/default.html --variable &#39;theme:spacelab&#39; --include-in-header /tmp/RtmpIRRxbR/rmarkdown-str2306274a199.html --mathjax --variable &#39;mathjax-url:https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML&#39; --highlight-style tango 
 </div>
 <strong class='message'>
 Output created: challenge.html</strong>
-<div class='output'>Next step: give the Dropbox public link to &quot;/tmp/Rtmph9QfoG/challenge.html&quot; to the participants.
+<div class='output'>Next step: give the Dropbox public link to &quot;/tmp/RtmpIRRxbR/challenge.html&quot; to the participants.
 </div>
 <div class='input'>unlink(outdir)
 setwd(wd)