Typographical Conventions

Michael Berg

Posted 2016-08-27. Last modified 2023-01-21.

The following typographical conventions are used on this site.

Block Quotes

Block quotes are indented and marked with a left border.

We hold these truths to be self-evident, that all men are created equal, that they are endowed by their Creator with certain unalienable Rights, that among these are Life, Liberty and the pursuit of Happiness.
– United States Declaration of Independence

Block quotes can also be nested, such as quoted content from an email thread.

What do you think?

I agree.

Inline Computer Code

Inline text that is related to computer code or configuration is typeset in a monospaced font with a light gray background. For example, the IPv4 address 198.51.100.92, the JavaScript function keyword, the HTML <script/> element, and the UNIX find command will all be typeset this way within regular text.

Textual File Content

Source code, scripts, document markup, and configuration files are examples of textual file content. Textual file content is typeset in a monospaced font, inside of a block with a light gray background and a gray border.

Here is a simple HTML file as an example.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8"/>
    <title>Hello World</title>
  </head>
  <body>
    <p>Hello World.</p>
  </body>
</html>

Interactive Terminals

Commands that users enter into an interactive terminal are typeset in a monospaced font, inside of a block with a light gray background and a gray border. The left border of the block is colored to provide additional context:

A red left border indicates that the commands should be executed as the root or Administrator user.
A green left border indicates that the commands should be executed as the relevant unprivileged user.
A gray left border indicates that the content is output from the preceding command.

For example, a system administrator might install software packages with the following apt-get command. In order to successfully execute these commands, the user must either have a root shell open or prefix the commands with sudo.

apt-get install tar gzip bzip2

A regular user looking for txt files in the current directory might execute the following find command.

find . -type f -name '*.txt'

The output of this find command might look like the following.

./file1.txt
./file2.txt
./subdir/file1.txt
./subdir/file2.txt

I find it useful to distinguish between the command to execute and the output of that command. This distinction helps prevent subsequent commands from getting lost in the output from previous commands and also makes it easier to break long output or interactive sessions into smaller chunks that are surrounded by descriptive text. For example, here is a short sequence of commands and their output.

id root

uid=0(root) gid=0(root) groups=0(root)

id nobody

uid=65534(nobody) gid=65534(nogroup) groups=65534(nogroup)

Putting It All Together

Here is a simple Bash script that interacts with the user. The script prompts the user for their name, reads the user’s response into the variable person_name, and then greets the user by the provided name. Save this script into the file hello-user.sh.

#!/bin/bash

echo -n "Please enter your name: "
read person_name
echo "Hello, ${person_name}."

A user can execute this script from a terminal with the following command.

sh hello-user.sh

The script’s output and user interaction will look like the following.

Please enter your name: John Doe
Hello, John Doe.