docs: state default plugin set and reframe stock themes as rarely used alternatives
Change-Id: Id5a37a34b4351fe17fa5c4d32572db6da2d44f04
diff --git a/R/revealjs_presentation.R b/R/revealjs_presentation.R
index d28fcd8..fa31dca 100644
--- a/R/revealjs_presentation.R
+++ b/R/revealjs_presentation.R
@@ -11,16 +11,20 @@
#' <https://github.com/rstudio/revealjs>
#'
#' # About plugins
-#'
+#'
+#' The plugins `notes`, `search`, `menu` and `zoom` are activated by default;
+#' only `chalkboard` is opt-in. Setting `reveal_plugins` replaces the default
+#' set -- pass `NULL` to render without any plugins.
+#'
#' ## Built-in plugins with reveal.js
-#'
-#' ### Zoom
-#'
-#' When activated, ALT + Click can be used to zoom on a slide.
-#'
-#' ### Notes
-#'
-#' Show a [speaker view](https://revealjs.com/speaker-view/) in a separated
+#'
+#' ### Zoom
+#'
+#' Activated by default: ALT + Click can be used to zoom on a slide.
+#'
+#' ### Notes
+#'
+#' Activated by default: shows a [speaker view](https://revealjs.com/speaker-view/) in a separated
#' window. This speaker view contains a timer, current slide, next slide, and
#' speaker notes. It also duplicate the window to have presentation mode
#' synchronized with main presentation.
@@ -103,15 +107,16 @@
#' their sub-slides.
#'
#' ### Search
-#'
-#' When opt-in, it is possible to show a search box when pressing `CTRL + SHIFT +
-#' F`. It will seach in the whole presentation, and highlight matched words. The
+#'
+#' Activated by default: pressing `CTRL + SHIFT + F` shows a search box.
+#' It will search in the whole presentation, and highlight matched words. The
#' matches will also be highlighted in overview mode (pressing ESC to see all
#' slides in one scrollable view)
#'
-#' ## Menu
-#'
-#' A slideout menu plugin for Reveal.js to quickly jump to any slide by title.
+#' ## Menu
+#'
+#' Activated by default: a slideout menu plugin for Reveal.js to quickly jump
+#' to any slide by title.
#'
#' Version `r version <- readLines(revealjs_lib_path("plugin", "menu", "VERSION"))` is
#' currently used and documentation for configurations can be found at
@@ -127,9 +132,9 @@
#' * `themes: false`
#' * `transitions: false`
-#' ## Chalkboard
-#'
-#' A plugin adding a chalkboard and slide annotation
+#' ## Chalkboard
+#'
+#' An opt-in plugin adding a chalkboard and slide annotation
#'
#' Version `r version <- readLines(revealjs_lib_path("plugin", "chalkboard", "VERSION"))` is
#' currently used and documentation for configurations can be found at
@@ -164,7 +169,11 @@
#' produced, with level 1 headers building horizontally and level 2 headers
#' building vertically. It is not recommended that you use deeper nesting of
#' section levels with reveal.js.
-#' @param theme Visual theme (`r knitr::combine_words(setdiff(revealjs_themes(), "default"), before = '"', and = " or ")`)
+#' @param theme Visual theme. Defaults to the dedicated IDS corporate design
+#' theme ("ids"), which is the raison d'être of this package; the stock
+#' reveal.js themes are available as rarely used alternatives:
+#' `r knitr::combine_words(setdiff(revealjs_themes(), c("default", "ids")), before = '"', and = " or ")`
+#' ("dark" is an alias for "black").
#' @param transition Slide transition (
#' `r (trans <- knitr::combine_words(setdiff(revealjs_transitions(), "default"), before = '"', and = " or "))`
#' )
diff --git a/README.Rmd b/README.Rmd
index d5611cd..aa034de 100644
--- a/README.Rmd
+++ b/README.Rmd
@@ -238,7 +238,7 @@
There are several options that control the appearance of revealjs presentations:
-- `theme` specifies the theme to use for the presentation (available themes are `r knitr::combine_words(setdiff(revealjs.ids:::revealjs_themes(), "default"), before = '"', and = " or ")`
+- `theme` specifies the visual theme for the presentation. It defaults to the dedicated IDS corporate design theme (`"ids"`), which is the raison d'être of this package; the stock reveal.js themes are listed here only for completeness, as alternatives that will rarely be used in the IDS context: `r knitr::combine_words(setdiff(revealjs.ids:::revealjs_themes(), c("default", "ids")), before = '"', and = " or ")` (`"dark"` is an alias for `"black"`).
- `highlight` specifies the syntax highlighting style. Supported styles include `r knitr::combine_words(rmarkdown:::highlighters(), before = '"', and = " or ")`. Pass null to prevent syntax highlighting.
@@ -249,12 +249,11 @@
``` yaml
output:
revealjs.ids::revealjs_presentation:
- theme: sky
highlight: pygments
center: true
```
-[Revealjs documentation about themes](https://revealjs.com/themes/)
+Documentation of the rarely used stock themes: [reveal.js themes](https://revealjs.com/themes/)
## Slide Transitions
@@ -477,7 +476,9 @@
| [chalkboard](https://github.com/rajgoel/reveal.js-plugins/tree/master/chalkboard) | Include handwritten notes within a presentation. Press `c` to write on slides, Press `b` to open a whiteboard or chalkboard to write. |
| [menu](https://github.com/denehyg/reveal.js-menu) | Include a navigation menu within a presentation. Press `m` to open the menu. |
-Note that the use of plugins requires that the `self_contained` option be set to false. For example, this presentation includes both the "notes" and "search" plugins:
+The plugins `notes`, `search`, `menu`, and `zoom` are activated by default; only `chalkboard` is opt-in. Setting `reveal_plugins` yourself replaces the default set, so to add `chalkboard` while keeping the defaults, list them all explicitly. Set `reveal_plugins: null` to render without any plugins.
+
+Note that the use of plugins requires that the `self_contained` option be set to false. For example, this presentation uses only the "notes" and "search" plugins (dropping "menu" and "zoom" from the default set):
``` yaml
---
@@ -584,7 +585,6 @@
``` yaml
revealjs.ids::revealjs_presentation:
- theme: sky
transition: fade
highlight: pygments
```
diff --git a/README.md b/README.md
index 1d5025f..1fb3f4d 100644
--- a/README.md
+++ b/README.md
@@ -296,9 +296,13 @@
There are several options that control the appearance of revealjs
presentations:
-- `theme` specifies the theme to use for the presentation (available
- themes are “ids”, “simple”, “dark”, “black”, “sky”, “beige”, “serif”,
- “solarized”, “blood”, “moon”, “night”, “league”, or “white”
+- `theme` specifies the visual theme for the presentation. It defaults
+ to the dedicated IDS corporate design theme (“ids”), which is the
+ raison d’être of this package; the stock reveal.js themes are listed
+ here only for completeness, as alternatives that will rarely be used
+ in the IDS context: “simple”, “dark”, “black”, “sky”, “beige”,
+ “serif”, “solarized”, “blood”, “moon”, “night”, “league”, or “white”
+ (“dark” is an alias for “black”).
- `highlight` specifies the syntax highlighting style. Supported styles
include “default”, “tango”, “pygments”, “kate”, “monochrome”,
@@ -313,12 +317,12 @@
``` yaml
output:
revealjs.ids::revealjs_presentation:
- theme: sky
highlight: pygments
center: true
```
-[Revealjs documentation about themes](https://revealjs.com/themes/)
+Documentation of the rarely used stock themes: [reveal.js
+themes](https://revealjs.com/themes/)
## Slide Transitions
@@ -600,9 +604,15 @@
| [chalkboard](https://github.com/rajgoel/reveal.js-plugins/tree/master/chalkboard) | Include handwritten notes within a presentation. Press `c` to write on slides, Press `b` to open a whiteboard or chalkboard to write. |
| [menu](https://github.com/denehyg/reveal.js-menu) | Include a navigation menu within a presentation. Press `m` to open the menu. |
+The plugins `notes`, `search`, `menu`, and `zoom` are activated by
+default; only `chalkboard` is opt-in. Setting `reveal_plugins` yourself
+replaces the default set, so to add `chalkboard` while keeping the
+defaults, list them all explicitly. Set `reveal_plugins: null` to render
+without any plugins.
+
Note that the use of plugins requires that the `self_contained` option
-be set to false. For example, this presentation includes both the
-“notes” and “search” plugins:
+be set to false. For example, this presentation uses only the “notes”
+and “search” plugins (dropping “menu” and “zoom” from the default set):
``` yaml
---
@@ -731,7 +741,6 @@
``` yaml
revealjs.ids::revealjs_presentation:
- theme: sky
transition: fade
highlight: pygments
```
diff --git a/man/revealjs_presentation.Rd b/man/revealjs_presentation.Rd
index 0e93d1a..84033ba 100644
--- a/man/revealjs_presentation.Rd
+++ b/man/revealjs_presentation.Rd
@@ -69,7 +69,11 @@
or just the body of a LaTeX document (\code{FALSE}). Note the LaTeX
document is an intermediate file unless \code{keep_tex = TRUE}.}
-\item{theme}{Visual theme ("ids", "simple", "dark", "black", "sky", "beige", "serif", "solarized", "blood", "moon", "night", "league", or "white")}
+\item{theme}{Visual theme. Defaults to the dedicated IDS corporate design
+theme ("ids"), which is the raison d'être of this package; the stock
+reveal.js themes are available as rarely used alternatives:
+"simple", "dark", "black", "sky", "beige", "serif", "solarized", "blood", "moon", "night", "league", or "white"
+("dark" is an alias for "black").}
\item{transition}{Slide transition (
"convex", "fade", "slide", "concave", "zoom", or "none"
@@ -155,15 +159,18 @@
\url{https://github.com/rstudio/revealjs}
}
\section{About plugins}{
+The plugins \code{notes}, \code{search}, \code{menu} and \code{zoom} are activated by default;
+only \code{chalkboard} is opt-in. Setting \code{reveal_plugins} replaces the default
+set -- pass \code{NULL} to render without any plugins.
\subsection{Built-in plugins with reveal.js}{
\subsection{Zoom}{
-When activated, ALT + Click can be used to zoom on a slide.
+Activated by default: ALT + Click can be used to zoom on a slide.
}
\subsection{Notes}{
-Show a \href{https://revealjs.com/speaker-view/}{speaker view} in a separated
+Activated by default: shows a \href{https://revealjs.com/speaker-view/}{speaker view} in a separated
window. This speaker view contains a timer, current slide, next slide, and
speaker notes. It also duplicate the window to have presentation mode
synchronized with main presentation.
@@ -249,7 +256,8 @@
their sub-slides.
\subsection{Search}{
-When opt-in, it is possible to show a search box when pressing \code{CTRL + SHIFT + F}. It will seach in the whole presentation, and highlight matched words. The
+Activated by default: pressing \code{CTRL + SHIFT + F} shows a search box.
+It will search in the whole presentation, and highlight matched words. The
matches will also be highlighted in overview mode (pressing ESC to see all
slides in one scrollable view)
}
@@ -258,7 +266,8 @@
\subsection{Menu}{
-A slideout menu plugin for Reveal.js to quickly jump to any slide by title.
+Activated by default: a slideout menu plugin for Reveal.js to quickly jump
+to any slide by title.
Version is
currently used and documentation for configurations can be found at
@@ -279,7 +288,7 @@
\subsection{Chalkboard}{
-A plugin adding a chalkboard and slide annotation
+An opt-in plugin adding a chalkboard and slide annotation
Version is
currently used and documentation for configurations can be found at