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

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 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 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` 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).

• 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.

• 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 ?.

• 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.

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

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.

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, etc.
• 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.

A list of reserved words in common programming languages include:

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.

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.

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.

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