Skip to content

Typesetting

Anisa Hawes edited this page Aug 19, 2024 · 24 revisions

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

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.

New Wiki (in-progress)

Publishing Tasks

Phase 1 Submission

Phase 6 Sustainability Accessibility

Phase change templates

Communications

Social Media

Bulletin

Events

Call Packages

Administration and Documentation

Members

Internal records

Resource indexes

Lesson Production and Development

Language and Writing

Accessibility

Governance

ProgHist Ltd


Old Wiki

Training

The Ombudsperson Role

Technical Guidance

Editorial Guidance

Social Guidance

Finances

Human Resources

Project Management

Project Structure

Board of Trustees

Clone this wiki locally