Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
186 lines (124 sloc) 16.6 KB
## *On The Line* Style Guide for Bookdown + RMarkdown {#style-guide}
NOTE: View this file and the code used to create the examples directly on the GitHub repo at <https://github.com/OnTheLine/otl-bookdown/blob/master/09.4-style-guide.Rmd>.
Also, this style guide was created primarily for the web edition <http://OnTheLine.trincoll.edu>, and may require additional modifications for the final PDF print edition.
#### General Goals {-}
For this book, the goal is to compose one version of the text that Bookdown will generate into multiple products: the Web/HTML edition, the PDF edition, and other formats such as ePub and MS Word if requested by the publisher. Only the Web edition will display interactive content and clickable links. But the text is designed so that readers of the printed PDF pages will see static images in place of interactive content. Also, readers of both the printed PDF pages and the Web edition will see footnotes with URLs, to supplement links that are clickable only in the Web edition. *(Since pages like this contain primarily technical details for authors, it does not include footnotes.)* Also, to ensure that the Web edition is accessible to visually-impaired readers, run tests and fix errors flagged by the [Wave Accessibility Evaluation Tool](http://wave.webaim.org/).
#### Markdown vs. R Markdown {-}
The text is based on the easy-to-read Markdown syntax, which is summarized in this [popular cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) and this [interactive tutorial](https://www.markdowntutorial.com).
But Bookdown uses its own flavor: [R Markdown by R Studio](https://rmarkdown.rstudio.com/).
#### Formatting {-}
Use brackets and parentheses for an [embedded link](http://example.com), and remember to add a footnote as shown below.
To display the URL of a non-embedded link, use only parentheses (http://example.com) or angle brackets <http://example.com>.
<!-- TODO is this second line necessary in Bookdown? -->
The book is designed for links to open in the same browser tab, since readers should use a right-click or two-finger click to open links in new tabs when desired. Only if absolutely necessary, use HTML tags to create <a href="http://example.com/">link that opens in a new page</a>.
Use HTML-style code comments to insert notes that are invisible to most readers, yet visible to authors (or anyone) viewing the public GitHub repo, such as TODO reminders:
```
<!-- TODO this comment appears in the source code, but not the book products -->
```
<!-- TODO confirm this em-dash syntax -->
For an em-dash, use three hyphens---like this---rather than two hyphens.
For a block quote, start each line with a caret **AND** add two spaces to insert a line break:
> I thoroughly disapprove of duels. If a man should challenge me, I would take him kindly and forgivingly by the hand and lead him to a quiet place and kill him.
> --- Mark Twain
> --- notable American author
#### Headers and Cross-reference links {-}
- Chapter titles are first-level headers with one hashtag: `# Chapter Title`
- Section titles are second-level headers with two hashtags: `## Section Title`
- Avoid third-level headers with three hashtags, as we have not yet found an easy way to control toc_depth in HTML edition.
- Subheaders are fourth-level headers with four hashtags: `#### Subheader in body text`
- Currently for Markdown tables, use fifth-level headers with five hashtags: `##### Table title`
Since the `index.Rmd` settings add numbers to chapters/sections, remember to block numbers from appearing in fourth- and fifth-level headers by adding curly brackets arounds a hyphen: `#### Subheader non-numbered {-}`
In Bookdown, a short chapter/section title `# Introduction` has a short default reference: `#introduction`. But a longer chapter/section title `# Defining City and Suburban Lines` has a longer default reference: `#defining-city-and-suburban-lines`.
In this book, we simplify each chapter/section title references by adding a short ID name in curly brackets, like this: `# Defining City and Suburban Lines {#defining}`.
Also, we match the short ID name `{#defining}` to the file name `02-defining.Rmd`. Although Bookdown does not require the file name and short ID to match, this method helps authors to organize all cross-references.
To embed a cross-reference to another chapter/section in the book, add an HTML link using brackets and parentheses. See code: `*by [Ilya Ilyankou and Jack Dougherty](authors-and-contributors.html)*` with demo: *by [Ilya Ilyankou and Jack Dougherty](authors-and-contributors.html)*. This method works best for the HTML edition.
#### Preface and Footers {-}
In this book, `index.Rmd` begins with a non-numbered first-level header `# Preface {-}`, followed by non-numbered second-level headers such as `## Authors and Contributors {-}` and `## Acknowledgements {-}`. All of this content is placed in the `index.Rmd` file because creating zero-numbered files (such as 0.1-about.Rmd) generated Bookdown errors.
Also, at the end of each section in the main text, a footer has been manually pasted that includes HTML links to sections in the Preface. The purpose of the footer is to ensure that each long web page contains author and copyright information, in case readers print out individual web pages from their browsers. Also, manually inserting a footer is not ideal, but we have not yet created a custom-script that performs the same function.
#### Footnotes {-}
A text-only footnote.^[This is a footnote, with no reference.]
To create a footnote with citations only, separate BibTeX citation keys with semi-colons: [@hirschMakingSecondGhetto1983; @jacksonCrabgrassFrontierSuburbanization1985; @tyackOneBestSystem1974]
Since footnotes also may include text and punctionation in Markdown syntax, always insert a caret symbol prior to the brackets to demarcate a footnote:^[On this theme, see @doughertyReviewConnecticutPublic2011. On a different theme, see @doughertySchoolChoiceSuburbia2009, pp. 33-35]
#### Static Images and Interactive iFrames {-}
In body of the book, avoid inserting images with simple Markdown syntax, because it does not support Bookdown figure auto-numbering and caption formatting. Instead, follow this R "code chunk" method, which supports figure auto-numbering and caption formatting for:
- static images, in both Web and PDF editions
- interactive maps and charts in Web edition, with static images in PDF edition
- scrolling PDF files in the Web edition, with static screenshots in the PDF edition
- videos in Web edition, with static images in PDF edition
**Overview**
- Define a text reference for captions, because this method accepts complex syntax, such as RMarkdown cites and links, as shown below. For details, see Bookdown sections on Figures <https://bookdown.org/yihui/bookdown/figures.html> and Markdown extensions <https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html>.
- Insert a BLANK LINE between the text reference and the R code chunk coming up.
- Insert an R code chunk <https://bookdown.org/yihui/bookdown/r-code.html>, with NO SPACES between ref:chunk-label, as shown below.
- To reduce the width (or height) of the output, add `out.width="30%"` to the code chunk, which works for Web edition and also PDF edition. If width is less than full, also insert `fig.align="center"`.
- To display interactive content in the Web edition and a static image in the PDF edition, create both elements and insert an if-else statement in the R code chunk to display these elements in different outputs, as shown below. (Thanks to Michael Dorman for this tip.)
- If the interactive content includes an iframe (for a map or chart), the default height will be 400 pixels. To adjust the iframe height (or width), insert a line of code in `custom-scripts.html` and add a code comment to the text to serve as a reminder, as shown below. Also, make sure that the `index.Rmd` file includes the custom script in the header, as described in the section above.
- Optional: In the body text, insert a dynamic reference to the figure in the same file, because PDF engine creates floating images that may be placed on the next page. Sample dynamic reference to a figure further below: ... as shown in Figure \@ref(fig:sample-interactive).
- Reminder: If the image appears a second time in the book, in a separate chapter, be sure to relabel the text ref: year-title2.
- Note: Bookdown does not auto-number figures in the `index.Rmd` file, which serves as a preface or introduction.
TODO for final PDF edition:
- About auto_pdf: "include_graphics() can be smart enough to use PDF graphics automatically when the output format is LaTeX and the PDF graphics files exist, e.g., an image path foo/bar.png can be automatically replaced with foo/bar.pdf if the latter exists. PDF images often have better qualities than raster images in LaTeX/PDF output. To make use of this feature, set the argument auto_pdf = TRUE, or set the global option options(knitr.graphics.auto_pdf = TRUE) to enable this feature globally in an R session." from https://bookdown.org/yihui/bookdown/figures.html
- Decide if 'out.width' and 'out.height' is preferable in all cases to `"fig_height=7"`
##### Static image in all editions, half-size output, no interactive version {-}
(ref:sample-static-image) Caption for sample static image, with Markdown formatting, links, citation.
```{r sample-static-image, echo=FALSE, fig.cap="(ref:sample-static-image)", out.width="50%"}
knitr::include_graphics("images/1937-holc-hartford-map-scan.jpg")
```
##### Interactive iframe in web edition (with adjusted height), static image in PDF edition {-}
(ref:sample-interactive) Caption for all versions here, with link to [full-screen interactive map with its own caption](https://ontheline.github.io/otl-redlining/index-caption.html), and link to sources and the code View [map historical sources, known issues, and the code](https://github.com/ontheline/otl-redlining/), developed by Ilya Ilyankou and Jack Dougherty, with footnote.^[@ilyankouMapRestrictiveCovenants2017]
<!-- set iframe 600px height 100% width in custom-scripts.html -->
```{r sample-interactive, echo=FALSE, fig.cap="(ref:sample-interactive)"}
if(knitr::is_html_output()) knitr::include_url("https://ontheline.github.io/otl-redlining/") else knitr::include_graphics("images/1937-otl-redlining.png")
```
##### Locally stored PDF scrolling in web edition, static screenshot in PDF edition {-}
(ref:pdf-sample-local) Here's a sample PDF that is locally stored in the GitHub repo, with option to add Markdown link and footnote.
```{r pdf-sample-local, echo=FALSE, fig.cap="(ref:pdf-sample-local)"}
if(knitr::is_html_output()) knitr::include_url("images/sample-3pp.pdf") else knitr::include_graphics("images/sample-pdf-screenshot.png")
```
##### Locally stored video clip, with custom script {-}
(ref:sample-clip) Here's a sample local video clip caption, with option to add Markdown link and footnote.
```{r sample-clip, echo=FALSE, fig.cap="(ref:sample-clip)"}
if(knitr::is_html_output()) knitr::include_url("images/BernsteinSimon2011clip.mp4") else knitr::include_graphics("images/2014-lumpkin-mae-willie-screenshot.png")
```
##### YouTube video iframe in web edition, static image in PDF edition {-}
(ref:youtube-sample-video) Here's a sample YouTube caption, with option to add Markdown links and footnote.
```{r youtube-sample-video, echo=FALSE, fig.cap="(ref:youtube-sample-video)"}
if(knitr::is_html_output()) knitr::include_url("https://www.youtube.com/embed/NuWg9Jrkrpw?start=64") else knitr::include_graphics("images/2013-cthistory-video-screenshot.png")
```
##### Vimeo video iframe in web edition, static image in PDF edition {-}
(ref:vimeo-sample-video) Here's a sample Vimeo caption, with option to add Markdown links and footnote.
```{r vimeo-sample-vimeo, echo=FALSE, fig.cap="(ref:vimeo-sample-video)"}
if(knitr::is_html_output()) knitr::include_url("https://player.vimeo.com/video/27299734") else knitr::include_graphics("images/2011-walsh-debra.jpg")
```
Since CTDA and Kaltura video feeds appear in the browser in autoplay mode, as of August 2019, do not embed these feeds in the book.
Instead, embed a short relevant video clips in YouTube or Vimeo, and insert link to "the full video on CTDA/Kaltura" in the caption and footnote.
An alternative method is to store the video locally and display with HTML5 video tags, with a custom-script to stop auto-play. But Bookdown does not recognize this so no figure auto-numbering and captions will be displayed, as illustrated below.
#### Trying HTML5 video tag solution {-}
Here's a solution using the [HTML5 video tag](https://www.w3schools.com/tags/tag_video.asp), which simply says NOT to insert "autoplay".
<video width="640" height="360" controls>
<source src="https://collections.ctdigitalarchive.org/islandora/object/120002:191/datastream/MP4" type="video/mp4">
</video>
The HMTL5 video tag solution stops autoplay, but it is NOT ideal for Bookdown-generated books because:
- Bookdown/knitr does not *appear* to support the HMTL 5 video tag in the same way as it supports knitr::include_url. I could submit a request to Bookdown to support HTML5 video tag, but it's not likely to happen soon....
- This means that I cannot use Bookdown built-in support for figures using the HMTL5 video tag, such as:
- the if-else statement in the R code-chunk that places the interactive iframe in HTML and the static floating image in the PDF, but the same caption for both
- figure auto-numbering, such as Figure 1.2, 1.3, etc.
#### Tables {-}
For now, use Markdown table formatting, with header above and caption (in italicized text) below. See <http://www.tablesgenerator.com/> with Markdown output. TODO: Decide on Bookdown-recommended kable package for tables, link to CSV in GitHub repo, and so on.
##### Sample table {-}
| **Header 1** | **Header 2** | **Header 3** |
|---------------------------|----------------------------|--------------------------|
| Security Grade | Second | Third |
| Location | Hartford | Hartford |
| Trend Next Decade | Stable | Stable |
*In the table above, insert a caption in italics, with optional links and footnote.*[@ilyankouMapFederalHOLC2017]
#### References for above {-}
- R Markdown book section on figures
- https://bookdown.org/yihui/rmarkdown/html-document.html#figure-options
- https://bookdown.org/yihui/rmarkdown/r-code.html#figures, which states:
- "PDF documents are generated through the LaTeX files generated from R Markdown. A highly surprising fact to LaTeX beginners is that figures float by default: even if you generate a plot in a code chunk on the first page, the whole figure environment may float to the next page. This is just how LaTeX works by default. It has a tendency to float figures to the top or bottom of pages. Although it can be annoying and distracting, we recommend that you refrain from playing the “Whac-A-Mole” game in the beginning of your writing, i.e., desparately trying to position figures “correctly” while they seem to be always dodging you. You may wish to fine-tune the positions once the content is complete using the fig.pos chunk option (e.g., fig.pos = 'h'). See https://www.sharelatex.com/learn/Positioning_images_and_tables for possible values of fig.pos and more general tips about this behavior in LaTeX. In short, this can be a difficult problem for PDF output."
- R Markdown reference https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf
- On R code chunks in RMarkdown https://bookdown.org/yihui/rmarkdown/r-code.html
- On R code chunk options in knitr package https://yihui.name/knitr/options/#code-chunk
- On positioning images in LaTeX https://www.overleaf.com/learn/latex/Positioning_images_and_tables
- Tips and tricks http://zevross.com/blog/2017/06/19/tips-and-tricks-for-working-with-images-and-figures-in-r-markdown-documents/#arguments-out.width-and-out.height-apply-to-both-existing-images-and-r-generated-figures
![creative commons by-nc-sa icon](images/cc-by-nc-sa-88x31.png) *[On The Line](http://ontheline.trincoll.edu) is an open-access, born-digital, book-in-progress by [Jack Dougherty and contributors](authors-and-contributors.html) at Trinity College, Hartford CT, USA. This work is copyrighted by the authors and freely distributed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/). Learn about our [open-access policy and code repository](copyright-with-open-access.html) and [how to read and cite](how-to-read-and-cite.html) our work. This book-in-progress was last updated on: `r Sys.Date()`*
You can’t perform that action at this time.