-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy path9.3.3-style-guide.Rmd
86 lines (52 loc) · 5.38 KB
/
9.3.3-style-guide.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
## Style Guide for *On The Line* {- #style-guide}
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](http://example.com), 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](https://github.com/OnTheLine/otl-bookdown/blob/main/css/style.css#L37).
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](http://wave.webaim.org/). See [relevant code on GitHub](https://github.com/OnTheLine/otl-bookdown/blob/main/css/style.css#L7).
### 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:
<!-- This comment is visible in the .MD source text, but not visible in the HTML browser, nor PDF or MSWord outputs. -->
2. 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:
`r if (knitr::is_html_output()) '<!--'`
This line appears in the PDF and Word versions, and is commented-out in the HTML and Markdown versions.
`r if (knitr::is_html_output()) '-->'`
`r if (knitr::is_latex_output()) '<!--'`
This line appears in the HTML, Word, Markdown versions, and is commented-out in the PDF version.
`r if (knitr::is_latex_output()) '-->'`
3. Option to customize the `style.css` code for the HTML book.
4. Option to add headers, footers, preambles to the HTML or LaTeX versions.
5. 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:
- See [Preface](index.html)
- See [Style Guide in Chapter x](style-guide.html).
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](https://bookdown.org/yihui/bookdown/cross-references.html), 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 \@ref(fig:sample-image).
- See Table \@ref(tab:left-table).
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).