Style Guide for On The Line

View the underlying source code to understand how this page was composed at: https://github.com/OnTheLine/otl-bookdown/blob/main/9.3.3-style-guide.Rmd.

The goal of this style guide is to compose one version of the text, primarily in easy-to-read R-flavored Markdown format, which Bookdown generates into multiple book products (HTML for open-access web edition, MS Word for editing, PDF for print edition, ePUB for electronic publication, full-length Markdown for conversion, etc.).

Note: This style guide was created primarily for the HTML web edition, and the PDF and ePUB versions will require additional modifications prior to final publication of the print and eBook editions.

In general, each subchapter is a separate R-flavored Markdown (.Rmd) file. Each paragraph begins on a separate line.

Use brackets and parentheses for an embedded link, and remember to add a footnote (as shown further below) for readers of the printed version that does not display embedded links.

For lists, always insert a blank line before the items, unless they appear directly after hashtag header.

  • unordered
  • list
  1. ordered
  2. list

Dashes:

  • Use a hyphen (1 dash) for hyphenated words, such as two-thirds or dog-friendly hotel.
  • Use an en-dash (2 dashes) for ranges, such as the May–September magazine issue.
  • Use an em-dash (3 dashes) to insert an additional thought—like this—in a sentence.

Insert TODO to note items to finish or review with co-author or editor.

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

Note that the HTML edition has customized style.css code for block quotes. See relevant code on GitHub.

Also note that the HTML edition has customized style.css code to improve visual contrast and make it more accessible for visually-impaired readers, based on the Wave Accessibility Evaluation Tool. See relevant code on GitHub.

Conditional Formatting

Conditional formatting offers the option to display text or images in some editions, but not other editions. Options:

Conditional formatting offers the option to display text or images in some Bookdown editions, but not others. Here are several ways to use conditional formatting:

  1. Insert a HTML code comment <!-- Comment --> in the .Rmd file to hide a few lines of text. This appears as commented-out text in the HTML and .md formats, is not displayed in the HTML browser, and does not appear in any way in the PDF or MS Word formats.

Demo:

  1. R package function is_[html/latex]_output allows conditional output for different book products, such as text that should appear in the HTML edition but not the PDF edition, or vice versa.

Demos:

This line appears in the HTML, Word, Markdown versions, and is commented-out in the PDF version.

  1. Option to customize the style.css code for the HTML book.

  2. Option to add headers, footers, preambles to the HTML or LaTeX versions.

  3. Option to build different versions of the HTML and LaTeX/PDF books using different chapters by listing them in order in the _bookdown.yml file.

Cross-references

In order to cross-reference in Bookdown, assign a unique name or R code-chunk label to each chapter, section, figure, and table. Unique names and labels should contain only alphanumeric characters (a-z, A-Z, 0-9) or dashes (-).

To cross-reference any chapter or section, and allow readers to jump there, use a HTML link with the unique name, such as index.html or style-guide.html. Demos:

Note: We use the HTML link method because it works best for the HTML web edition. We avoid using Bookdown unique ID links to cross-reference chapters or sections, as recommended in the Bookdown manual, for the HTML edition because it creates imprecise URLs with extraneous hashtags for sections/subchapters. However, if your primary goal is to create an ePUB, use the Bookdown unique ID links method, since HTML links will not work.

To cross-reference figures and tables, and display their auto-number and allow readers to jump there, write a call-out with a Bookdown reference to a code-chunk label, such as See Figure \@ref(fig:sample-image) or See Table \@ref(tab:left-table). Demos:

  • See Figure 9.4.
  • See Table 9.1.

Cross-reference interactivity varies by output:

  • In HTML, all cross-refs are clickable.
  • In PDF, all cross-refs are clickable (except chapter-level HTML links).
  • In Word, no cross-refs are clickable (unless this varies with reference.docx).
footer