Quotes and code on a page

Quoting other people

When you include someone else's words, HTML lets you mark them as a quotation and record where they came from. This is good manners, it is clearer for readers, and it helps search engines understand that the words are not yours.

blockquote for longer quotes

<blockquote cite="https://www.w3.org/WAI/">
  <p>The power of the Web is in its universality. Access by everyone regardless of disability is an essential aspect.</p>
</blockquote>
<p>— Tim Berners-Lee, inventor of the World Wide Web</p>

blockquote is for a quotation that stands on its own, usually a sentence or more. Browsers indent it by default. The cite attribute holds the URL of the source. It is not shown on screen, so if the source matters to readers, name it in visible text too, as the line after the quote does.

q for short quotes inside a sentence

<p>As my teacher used to say, <q>Read the error message before you panic</q>, and she was right.</p>

The browser adds quotation marks around q automatically, so do not type your own as well, or you will get two pairs.

cite for titles of works

The cite element (different from the attribute) marks the title of a creative work: a book, film, song, paper or website.

<p>My favourite programming book is <cite>The Pragmatic Programmer</cite>.</p>

Browsers usually show it in italics. Do not use it for a person's name; it is meant for the title of the work.

Showing code

You met code for short pieces of code inside a sentence. For a whole block, combine it with pre:

<p>Save this as <code>hello.py</code>:</p>
<pre><code>name = input("Your name: ")
if name:
    print("Hello,", name)
else:
    print("Hello, stranger")</code></pre>

• pre keeps every space and line break, so the indentation that Python depends on survives. It also uses a monospaced font, so columns line up.
• code inside it says "this is computer code", which matters for screen readers, translation tools and syntax highlighters.

Put the code directly after <pre><code> with no line break before it. A line break there becomes an empty first line, because pre keeps everything.

The angle-bracket problem

Here is the catch every tutorial writer meets: if you want to show HTML code on an HTML page, the browser tries to run it.

<pre><code><p>This becomes a real paragraph</p></code></pre>

The fix is to write the special characters as character entities:

<pre><code>&lt;p&gt;This shows as code, not as a paragraph.&lt;/p&gt;</code></pre>

Escaping by hand is tedious for long snippets. Most editors, Markdown tools and frameworks do it for you, which is one reason people write documentation in Markdown. If you work with encodings such as Base64 or hex, the Hash & Encode Toolkit shows how text is transformed.

Other code-related elements

• kbd for keys the user presses: Ctrl.
• samp for output a program prints: Error: file not found.
• var for a variable in maths or code: the value of x.

You will mostly use code and kbd; the others are nice when precision matters, such as in technical documentation.

Common mistakes

• Typing quotation marks around a q and getting them twice.
• Using blockquote just to indent text. Indentation is CSS's job; blockquote means "this is a quotation".
• Forgetting to escape < inside code, so part of the example vanishes or becomes real HTML.
• A blank first line in pre from a line break after the opening tag.

Exercise

Write a short paragraph quoting the line "Programs must be written for people to read, and only incidentally for machines to execute" inline with q, crediting its authors, Harold Abelson and Gerald Jay Sussman, and naming the book Structure and Interpretation of Computer Programs with cite. Below it, show this exact HTML snippet as code: <a href="/">Home</a>.

<p>Harold Abelson and Gerald Jay Sussman wrote, in <cite>Structure and Interpretation of Computer Programs</cite>, that <q>programs must be written for people to read, and only incidentally for machines to execute</q>.</p>

<pre><code>&lt;a href="/"&gt;Home&lt;/a&gt;</code></pre>