Typesetting

Publishing Tasks: Phase 6 Sustainability + Accessibility

Typesetting (all lessons)

Ahead of publication, we review each lesson’s Markdown file, paying particularly close attention to layout and structure. This step aims to ensure that each new lesson is structurally and visually consistent with those we’ve published previously.

---

Contents of this page:

• Table of features
• Bold
• Italics
• Round Brackets
• Backticks
• Quotation Marks
• Non-breaking Spaces
• Headings
• Lists
• Citations
• Perma Links
• Commonly Used Reserved Words

---

Table of features

Feature	Typesetting	Example
Abbreviations	Round brackets following the Full Capitalised Form	Natural Language Processing (NLP)
Arguments	Backticks	You can define the colour and title arguments
Buttons	Italics	Click the Upload to session storage button
Citations	Article name in double quotation marks (or « guillemets » in French)	Tobler, W. R. (1970), “A computer movie simulating urban growth in the Detroit region”, Economic Geography, 46:234-240. // Taryn Dewar, « Analyser des données tabulaires avec R », traduction par Marie Flesch, Programming Historian en français 5 (2023), https://doi.org/10.46430/phfr0027. See more examples under Citations.
Code (inline)	Backticks – one on each side	You can type bundle show minima from the command line
Code (multiline blocks)	Backticks – three above and three below	See section on Backticks for an example
Coined terms or phrases	Single quotation marks (or « guillemets » in French)	There is no 'one size fits all' approach
Column heading	Bold	This represents the data in the column Year
Extracted term	Italics	Most languages are heavily dependent on function words like the, as, of, to, and from
File extensions	Backticks	We will export this file in a .pdf format
File or folder names	Backticks	Next, we analyze the DNP_ancient_authors.csv dataset
Functions	Backticks	Let us next apply the PCA() function
Headings	Sizes range from ## to ####	## Header 2 and #### Header 4
Icons	Bold	Click the Files icon on the left of the window
Keystroke	Italic	press Enter
Labelled category	Bold	TRUE
Lesson titles	Links	See Programming Historian’s excellent article on Computer Vision for the Humanities
Lists	Numbered or bulleted; sentence-capped; no punctuation	See section on Lists
Menu items	Bold	Click File > New Notebook in the menu
Punctuation (French)	Non-breaking space	  before :, ;, !, ?
Quotes	Single quotation marks (or « guillemets » in French)	The program has transcribed 'prote Inier' instead of 'wrote Izie' // Le programme a écrit « prote Inier » au lieu de « wrote Izie ».
Reserved Words	Backticks	import these modules at the start of your new notebook
Speech	Double quotation marks (or « guillemets » in French)	You could ask your corpus the following question: "How do people in nineteenth-century novels use the word bread when they aren't referring to food?"
Tab name	Bold	Go to the Basics tab
Technical words	Single quotation marks (or « guillemets » in French)	This will replace any missing numeric values as a 'non-number' // Nous allons réaliser des « affectations », c’est-à-dire attribuer une valeur à une variable.
Titles	Italics	Las bizarrías de Belisa is a comedy written by Lope de Vega (1562-1635) in 1634
Translations	Round brackets	Se anota el nodo de origen (source)
Variables	Backticks	This time, call the function using the fig variable
Window or page name	Bold	You can find this on the Keys and Endpoint page

Bold

Bold is formatted using **double asterisks**. It is used to help readers with their navigation around an interface or workspace. This includes:

• Menu items (e.g. in a dropdown)
• Tab or window names
• Column headings (e.g. in a spreadsheet)
• Labelled categories (e.g. in a dataset)

Italics

Italics are formatted using *single asterisks* or _single underscore_. They are used primarily to indicate:

• a keystroke or button which generates an action (e.g. Enter, Run)
• a term extracted from a dataset, usually to perform textual analysis
• book titles, plays, films, TV programmes, paintings, songs, albums

Round Brackets

Round Brackets are used to follow a word with its direct translation. They can be used both to give a translation from the original language, or the translated language.

• OR (TR)
• TR (OR)

They can also be used to introduce an abbreviation. The first time any abbreviation is introduced, it is first written in its Full Capitalised Form, followed by the abbreviation in brackets (FCF).

Backticks

`Backticks` are used to indicate any parts of the text which are code, to distinguish them clearly from the prose.

• Multi-line code blocks should be enclosed in three backticks:

# hello-world.py
print('hello world')

• Inline code can be enclosed in single backticks.

They are also used to indicate:

• Variables (e.g. num).
• Functions (e.g. createFile)
• Filenames, including their extension (e.g. typographical-guidelines.md).
• File extensions on their own (e.g. .pdf).
• Reserved Words which are part of a programming language (e.g. See our list of commonly used reserved words).

Quotation marks

• We always use 'single quotation marks', for quotes but also to highlight coined terms or technical words (ideally followed by an explanation). They are also used to delineate words, phrases or values that are to be typed.
• "Double quotation marks" are simply used for instances of quotes within quotes.
• French « guillemets » (chevrons) are used for any and all instances of quotation marks in French. «  and  » can be written using the HTML codes «  for a left-pointing guillemet and  » for a right-pointing guillemet.

Straight double quotation marks interfere with the liquid syntax. Use backslash \ followed by straight double quotation marks or single quotation marks, if needed in figure captions. Ideally, avoid altogether in the alt-text.

Non-breaking Spaces

• In French (only), certain punctuation signs need to be preceded by a space. It is important to use a 'non-breaking space' instead of the spacebar. This 'non-breaking space' groups the word and the punctuation sign as one single entity, and prevents them from being separated over a line break.
• The non-breaking space is written using the HTML code   before a colon :, semi-colon ;, exclamation mark ! and question mark ?.

Headings

• Largest heading size: ## Header 2
• Smallest heading size: #### Header 4

Headings should never contain inline code font or style formatting such as bold, italic, or code font.

Lists

Typically, we use numbered lists and bulleted lists. List items are sentence-capped. List items should be treated as separate items and should not be strung together with punctuation or conjunctions.

For example:

• Here is an item
• Here is another item
• Here is the final item

Or:

1. Here is an item
2. Here is another item
3. Here is the final item

Citations

We use the The Chicago Manual of Style, 17th Edition for all our citations.

• Book and journal titles are in italics, whereas article names are in double quotation marks (or « guillemets » in French).
• Where references to other Programming Historian lesson titles are made within the text (but not in a citation), these should formatted as links without quotation marks around the title (e.g. "see Programming Historian’s excellent article on Computer Vision for the Humanities).
• To cite software according to the recommendations of Software Heritage, please provide available elements of the following information: author, title, version, year of release, license, repository URL.

Examples:

• Article in a journal:
  Jack Hardy and Ute Römer, “Revealing disciplinary variation in student writing: A multi-dimensional analysis of the Michigan Corpus of Upper-level Student Papers (MICUSP),” Corpora 8, no. 2 (2013): 183–207. https://doi.org/10.3366/cor.2013.0040

• Book:
  Carol Berkenkotter and Thomas Huckin, Genre knowledge in disciplinary communication: Cognition/culture/power, (Lawrence Erlbaum Associates, Inc., 1995).

• Chapter in an edited book:
  Jennifer Isasi et al., “A Model for Multilingual and Multicultural Digital Scholarship Methods Publishing,” in Multilingual Digital Humanities, edited by Viola, L., & Spence, P., Routledge, 2023.

• Software:
  Barnier, Julien, Kent Russell, Mike Bostock, Susie Lu, Speros Kokenes, Evan Wang. Scatterd3 (version 1.0.1). GPL. 2021. https://cran.r-project.org/web/packages/scatterD3/index.html.

• PH lesson in a citation (not in-text):
  Jonathan Reades and Jennie Williams, "Clustering and Visualising Documents using Word Embeddings," Programming Historian 12 (2023), https://doi.org/10.46430/phen0111.

Perma Links

All the links used in a lesson must be archived through Perma.cc, EXCEPT for the following:

• Links to lessons or pages from Programming Historian's website, and to directories or files in Jekyll. Instead, we format these into 'relative links' which start with / usually followed by a language code (en, es, fr, pt) or assets.
• Links that ask the reader to perform a direct action in the lesson, such as downloading, installing.
• Links to dynamic content including videos, interactive diagrams/maps or social media
• Links that are already permanent, including DOIs and webpages archived by the Wayback Machine or other services.

For more details about how to create Perma Links, see the Archival Hyperlinks page of this Wiki.

Commonly Used Reserved Words

A list of reserved words in common programming languages include:

JavaScript:

abstract, arguments, await, Boolean, break, byte, case, catch, char, class, const, continue, debugger, default, delete, do, double, else, enum, eval, export, extends, false, final, finally, float, for, function, goto, if, implements, import, in, instanceof, int, interface, let, long, native, new, null, package, private, protected, public, return, short, static, super, switch, synchronized, this, throw, throws, transient, true, try, typeof, var, void, volatile, while, with, yield.

Python 2:

and, as, assert, break, class, continue, def, del, elif, else, except, exec, finally, for, from, global, if, import, in, is, lambda, not, or, pass, print, raise, return, try, while, with, yield.

Python 3:

and, as, assert, break, class, continue, def, del, elif, else, except, False, finally, for, from, global, if, import, in, is, lambda, nonlocal, None, not, or, pass, raise, return, True, try, while, with, yield.

R:

break, else, for, FALSE, function, if, in, Inf, NA, NA_character_, NA_complex_, NA_integer_, NA_real_, NaN, next, NULL, repeat, TRUE, while.