-
-
Notifications
You must be signed in to change notification settings - Fork 91
/
20.3-style-guide.Rmd
126 lines (85 loc) · 9.21 KB
/
20.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
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
## Style Guide for *Hands-On Data Visualization* {- #style-guide}
View the underlying source code to understand how this page was composed at: https://github.com/HandsOnDataViz/book/blob/main/20.3-style-guide.Rmd
We built *Hands-On Data Visualization* based largely on the [O'Reilly Style Guide](https://oreillymedia.github.io/production-resources/styleguide/), and also to match our needs for composing in R-flavored Markdown (.Rmd) and generating multiple book products through Bookdown. While we drafted chapters, we wanted to produce an HTML edition for the web that would display our embedded iframes to online charts and maps. We also needed to produce a PDF or Word version that displayed only static images, for our developmental editor to markup and provide feedback. Finally, we needed to produce a full-length Markdown file (.md) of the entire book that would easily convert all of our text, captions, and pathnames to static images for O'Reilly's publishing platform. Some of the notes below are stylistic or technical reminders to ourselves to write consistently as we worked on 16 chapters and more than 400 images.
In general, each chapter is a separate R-flavored Markdown (.Rmd) file. Each paragraph begins on a separate line. O'Reilly style guide prefers *italics* rather than bold. Use single back tics to display a monospaced `code` word. Insert `TODO` to note items to finish or review with co-author or editor.
O'Reilly guidelines recommend making your writing as conversational as possible. Imagine you're speaking to someone one on one, not giving a formal lecture to a large group. Refer to the reader as "you" and to yourself as "I" for a single-author book, and refer to yourselves as "we" for a co-authored book. Use active voice, not passive voice.
More from O'Reilly about chapter structure: Each chapter should begin with a paragraph or two that summarizes what the chapter is about and why that information is important to the overall topic of your book. Subsequent sections should walk readers through the information you're presenting. Keep readers oriented by including signposts like "As you learned in Chapter 4" and "I'll discuss this topic in more detail later in this chapter."
More from O'Reilly about transitions: End section X by saying something like, "Now that you understand X, you're ready to dig into topic Y," and start section Y by explaining how it relates to topic X. Daisy-chaining helps readers understand how concepts are connected and why you're covering them in this order. Finally, at the end of each chapter, summarize what you discussed in that chapter, and mention what the following chapter is going to cover.
O'Reilly encourages the use of tips, notes, and warnings, and assigns each of them an animal icon in their books (lemur, crow, and scorpion, respectively). In this book manuscript, simply start each with a paragraph beginning with the keyword, followed by a colon, to simplify find-and-replace at a later date:
- Tip: A couple of sentences that convey a helpful bit of information, a quick way to do things better.
- Note: A couple of sentences of supplemental information. It describes something you want readers to keep in mind as they work, so you use a note to set it apart and make sure they see it.
- Warning: Similar to a note or tip, but specifically focused on a way to help readers avoid making a mistake or getting into trouble.
Also:
- Sidebar: Use this to note where the editor has requested a boxed sidebar. If longer than one paragraph, add "End Sidebar" to close it.
Sample embedded external link: [O'Reilly](https://www.oreilly.com/). This appears as a colored clickable link in HTML and Word editions, and a non-colored but clickable link in the PDF edition. According to O'Reilly Atlas documentation, the AsciiDoc version should automatically unfurl for the printed edition.
Sample embedded internal link to the book, using the short pathname, such as [download this sample CSV file](data/data.csv), to ensure that Bookdown copies the file from the `data` subfolder over to the `docs` subfolder.
Embed links directly in the sentence, such as [download this sample PDF](data/ct-dph-covid-2020-05-31.pdf). Avoid linking words such as "here" or "this web page." Also, avoid writing "Click on this..." in the main text, such as when downloading a sample file, since readers cannot click on the print edition. However, it is acceptable to write "click on" or "right-click on" in a tutorial on interacting with software.
When instructions refer to software menu items, use italics. Example: Select *File > Make a Copy* to save your own version to your Google Drive.
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 three back tics to insert a code block, limited to 81 character line length for Animal style book body in [O'Reilly style guide](https://oreillymedia.github.io/production-resources/styleguide/#line-length), like this:
```
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/leaflet.css" />
<script src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>
```
### Conditional Formatting {-}
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. In this way, we published all chapters/subchapters for the HTML version, but published only selected chapters for the PDF and full-length Markdown versions for O'Reilly, as shown below:
```
# comment-out below when building all chapters for HTML book, un-comment to skip chapters not listed below for PDF and full-length Markdown for ORM
# rmd_files: [
# "index.Rmd",
# "0.0-introduction.Rmd",
# "01-choose.Rmd",
# "02-spreadsheet.Rmd",
# "03-find.Rmd",
# "04-clean.Rmd",
# "05-comparisons.Rmd",
# "06-chart.Rmd",
# "07-map.Rmd",
# "08-table.Rmd",
# "09-embed.Rmd",
# "10-github.Rmd",
# "11-chartcode.Rmd",
# "12-leaflet.Rmd",
# "13-transform.Rmd",
# "14-detect.Rmd",
# "15-story.Rmd",
# "16-fix.Rmd",
# "21-references.Rmd"
# ]
```
### 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 (-).
Contrary to the [Bookdown manual](https://bookdown.org/yihui/bookdown/cross-references.html), *avoid* using Bookdown unique ID links to cross-reference chapters or sections, because these create imprecise URLs with extraneous hashtags for sections/subchapters.
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 [Introduction](index.html)
- See ["Style Guide" in Chapter x](style-guide.html).
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).
When writing cross-references in the text, the [O'Reilly Style Guide](https://oreillymedia.github.io/production-resources/styleguide/#considering_electronic_formats) prefers live cross references (e.g., "see Figure 2-1"), but if not feasible, use "preceding" or "following" because physical placement of elements may vary across print and digital formats. *Avoid* using "above" or "below."