The PreTeXt Guide

This is the first of several grouping tags, using characters with left and right variants, and some of the most common markup in your writing. Presentation uses double quote marks that are smart quotes, meaning that they look different in their opening and closing variants. (See <blockquote> for extensive runs of quoted text that can stand alone, and which can carry an attribution.)

Perhaps less-often used than <q>, so a couple more characters to type. Presentation is paired single-quotes, opening and closing.

Left and right angle brackets to enclose a phrase. This is not for creating a set of generators in mathematics, use the appropriate mathematics tag and syntax for that. Note also that the characters used here are definitely distinct from the inequality symbols, < and >.

Double left and right square brackets to enclose a phrase. This is not for grouping expressions in mathematics, use the appropriate mathematics tag and syntax for that. These are used in the analysis of texts to note various restorations or deletions. Inquire if you feel there should be more semantic markup for this purpose.

Use this element to surround characters in a phrase that is to be emphasized. This will typically be rendered in italics, though this choice is left to the implementation of a particular conversion. See also, <alert>.

If you are new to using a markup language, this is a place to stop and think. As a PreTeXt author you are never able to say, “I want this text to appear in italics.” Rather, you specify that certain text has a certain purpose or meaning. Emphasis is a way of calling attention to a portion of a sentence or paragraph. A font change (to italic) is a common and effective device. But a particular format might have a better, or different, way to achieve this. Perhaps in an electronic format, the letters are animated and dance up and down. (Just kidding. But you may be reminded of frequent blinking text in the early days of web design, supported by a non-standard <blink> element.) Seriously, now would be a good time to review Section 1.1.

Use this to heavily emphasize something to a greater degree than just emphasis. Maybe think of it as SHOUTING. Bold italic font, or a bright color, or both, would be normal choices for presentation. Overuse of this tag will dilute its effectiveness.

Use this to identify a word or phrase that is being defined, in contrast to actually using a structured <definition>. Typical presentation is a bold font. Caution: the use of this tag is to communicate a defined term and converters may make use of this interpretation, given the importance of definitions in scholarly work. It would be considered tag abuse to use this tag to simply bold a word or phrase for some other reason, perhaps as an alternative to <em> or <alert>.

This tag is used to identify words or phrases from a language other than the main one used for the overall document. It is best practice to use a @xml:lang attribute to identify the language, since this will assist screen readers and hyphenation algorithms. We may also recognize the need for a different script (font). Usual presentation is italics for languages using a Latin script. This should not be used for entire paragraphs as a way of assisting with a translation of an entire document.

Note that when we use italics for emphasis and to point out foreign words or phrases, there is a loss of information in our output. In other words, we can no longer reliably (in an automated way) convert our output back to equivalent PreTeXt source from its visual representations. C’est la vie. See Section 1.1 again.

These provide the ability to typographically distinguish the title of another work, and are not a replacement for careful bibliographies and citations. Use <pubtitle> for longer, complete works, such as books, plays, or entire websites. Use <articletitle> for shorter, component works, such as a chapter of a book, a research article, or a single webpage.

Presentation for a longer work will be italics or an oblique (slanted) font, and for a shorter work, the title will simply be quoted.

An abbreviation is a condensed or shortened version of some word or phrase, such as Mr. for “Mister.” Converters should take care with periods (full stop) inside an <abbr> as distinguished from the end of a sentence (which may not always be clear given the absence of a tag delimiting sentences). An initialism is an abbreviation read as a sequence of letters, often the first letter of words in a phrase, such as HTML for “HyperText Markup Language.” An acronym is much like an initialism, but the letters are read as a pronounceable word (which sometimes actually enters the language as a word, such as “radar” which began as RAdio Detection And Ranging). An example is SCUBA which stands for “Self-Contained Underwater Breathing Apparatus.” Initialisms and acronyms may be presented in a small-capitals font or as regular capitals reduced in size.

These denote portions of a text that is being changed in some way, presumably as part of an editing process. Conceivably, they could be managed by some other tool acting on your source. Stale text is that which is slated for removal eventually, but is left in place so that it may be consulted. There is no support presently for actually deleting or incorporating text, though that would be a reasonable feature request.

Red and green, for leaving and entering, are natural choices for presentation. But in consideration of those readers who cannot always distinguish different colors, other devices, such as strikethrough or underlining, should also be employed.

These are PreTeXt tags for when we write about PreTeXt and need to discuss tags, empty tags, and attributes. Given how we design PreTeXt tags the content of these elements should only be the 26 lower-case letters and a dash/hyphen. These should render in ways that make the three types of language elements obvious without much further discussion. Just a bit self-serving, but not unjustified.

This element may surround a full scientific name, resulting in presentation in italics. There are subelements <genus> and <species> which may be used to delineate those components.

A @ncbi attribute on <taxon> accepts an identifier from the National Center for Biotechnology Information¹. Feature requests for ways to make this more useful are welcome.

A footnote can be inserted in a paragraph and a mark will be left behind. Where the content of the footnote goes depends on the capabilities of the output format. Because a footnote allows you to begin a new piece of text anywhere, it can be difficult to handle technically. For this reason it is banned from places like titles and its possible content is limited (for openers, no paragraphs).

A footnote is the farthest thing from structured writing that we can think of. It can go anywhere. Resist the temptation to use it, and your writing will improve. We frequently entertain the thought of making footnotes impossible in PreTeXt. See the <aside> element for a possible alternative.

Simple, inline expressions using mathematical notation may be used in paragraphs, and in titles and captions. The syntax is LaTeX. See Section 4.9 for full details.

Short bursts of raw, or verbatim, text can be wrapped in the <c> element. Strictly speaking, “code” is a misnomer, as the text may be anything you need to communicate exactly as one would type it at a keyboard or as input to a computer program. Anything longer than a handful of characters, or needing accurate line breaks should consider the <cd>, <pre>, <program> or <console> tags. Presentation is normally a monospaced sans serif font, perhaps of a slightly heavier weight, and designed for the job with features such as unambiguous zeros (versus the letter ‘oh’). See Section 4.4 for details.

Very similar to the <c> tag, this may be used to get a monospace presentation of an email address, possibly as an active link in some formats.