Chapter 2 Basic Markup

2.1 File Name

You should write your contribution in a file that has a ".tex" extension, for example, what-i-did-last-summer.tex. The name of the file should contain only letters, numbers, hyphens (-) and underscores (_).

The person who is editing the anthology may suggest a file name that you should use. For example, the editor may wish you to use your own name as the file name (john-smith.tex).

2.2 Markup Commands for a Short Story

You should write your contribution as a plain text file with embedded commands that specify how to markup, (that is, format) the text. Figure 2.1 shows an example of a short story that might be included in an anthology. The markup commands are shown in a bold font. Figure 2.2 shows how the story might be formatted in the final anthology.

Figure 2.1: A short story: markup

\section*{What I Did Last Summer}\sectionAuthorInfo{John Smith}{England} Last year, I got a summer job working at a local factory. Unfortunately, with the recession, the manager wasn’t hiring anyone this year. Most of my friends had summer jobs, so I got \emph{very} bored hanging out by myself. To keep myself occupied, I decided to do some volunteer work at a local community centre. While there, I worked at a wide variety of tasks. I swept the floor. I made refreshments during coffee breaks. I proofread documents. I ordered new stationary supplies. Occasionally, I staffed the reception desk. I helped people with poor literacy skills to fill in forms. I repainted a corridor. And all that was during my \emph{first week} there! I volunteered at the centre five days a week, for most of the summer, taking just a two-week break to go on holidays. It was the most enjoyable job I’ve ever had.

Figure 2.2: A short story: formatted output

What I Did Last Summer

John Smith, England

Last year, I got a summer job working at a local factory. Unfortunately, with the recession, the manager wasn’t hiring anyone this year. Most of my friends had summer jobs, so I got very bored hanging out by myself.

To keep myself occupied, I decided to do some volunteer work at a local community centre. While there, I worked at a wide variety of tasks. I swept the floor. I made refreshments during coffee breaks. I proofread documents. I ordered new stationary supplies. Occasionally, I staffed the reception desk. I helped people with poor literacy skills to fill in forms. I repainted a corridor. And all that was during my first week there!

I volunteered at the centre five days a week, for most of the summer, taking just a two-week break to go on holidays. It was the most enjoyable job I’ve ever had.

Although the example is very short, it illustrates most of the markup commands that a contributor needs to be familiar with.

The \section* command takes one parameter (enclosed in braces) that specifies the name of the short story.

The \sectionAuthorInfo command takes two parameters: the first specifies the name of the contributor, and the second specifies some background information, such as the contributor’s location, age or occupation.

Finally, the \emph command is used to emphasise a word or phrase, and one or more blank lines are used to separate paragraphs.

By comparing Figures 2.1 and 2.2, you may also notice that (aside from blank lines), it does not matter where you put line breaks in an input file: the LaTeX typesetting system (upon which Canthology is based) will decide the optimal place for lines breaks in the output file.

2.3 Markup for a Chapter-length Contribution

In the previous section, I explained how to format your short story as a section (within a chapter). However, if the editor instructs you to submit your contribution as an entire chapter, then you should use the \chapter and \chapterAuthorInfo commands. For example:


\chapter{What I Did Last Summer}
\chapterAuthorInfo{John Smith}{England}

Last year, I got a summer job ...

If you want to divide your chapter into several sections, then you can use one of the following commands:


\section*{title}
\section{title}
\anonymoussection

You have already seen the \section* command: it formats the title text without a sectional number.

The \section command formats the title text with a sectional number. For example, when writing this chapter, I used the following command at the start of this section:


\section{Markup for a Chapter-length Contribution}

You can use the \anonymoussection command to start a new section but not assign a title for it. For example:


Then, in the rudest manner he could display, he turned
his back deliberately on Sandeman and walked out of
the room.

\anonymoussection

In the company of Adela he tried to forget the little
contretemps.

produces the following output:

Then, in the rudest manner he could display, he turned his back deliberately on Sandeman and walked out of the room.

* * * * *

In the company of Adela he tried to forget the little contretemps.

As you can see, the \anonymoussection command uses blank space and a row of * symbols to mark the end of one section and the start of another.

2.4 Markup Commands for Poetry

The example in Figure 2.3 illustrates the markup you should use for a poem, and Figure 2.4 shows the formatted output. (By the way, this example uses -- and --- to produce dashes of various lengths; such dashes will be discussed in Section 3.3.)

Figure 2.3: A poem: LaTeX markup

\poemtitle{Carpe Diem}
\poemAuthorInfo{William Shakespeare}{1564--1616}

\begin{verse}[16em]
O mistress mine, where are you roaming? \\*
O stay and hear! your true-love’s coming \\*
That can sing both high and low; \\
Trip no further, pretty sweeting, \\*
Journey’s end in lovers’ meeting--- \\*
Every wise man’s son doth know.

What is love? ’tis not hereafter; \\*
Present mirth hath present laughter; \\
What’s to come is still unsure: \\*
In delay there lies no plenty,--- \\*
Then come kiss me, Sweet and twenty, \\*
Youth’s a stuff will not endure.
\end{verse}

Figure 2.4: A poem: formatted output

Carpe Diem

William Shakespeare, 1564–1616

O mistress mine, where are you roaming?
O stay and hear! your true-love’s coming
That can sing both high and low;
Trip no further, pretty sweeting,
Journey’s end in lovers’ meeting—
Every wise man’s son doth know.

What is love? ’tis not hereafter;
Present mirth hath present laughter;
What’s to come is still unsure:
In delay there lies no plenty,—
Then come kiss me, Sweet and twenty,
Youth’s a stuff will not endure.

You use the \poemtitle command to specify the title of the poem, and \poemAuthorInfo to specify both the name of the contributor and some background information about that contributor, such as location, occupation or age.

The poem itself is typeset in the verse environment, that is, between the \begin{verse} and \end{verse} commands. Within a verse environment, you should do the following:

Leave a blank line between each stanza.
At the end of each line—except the last line of a stanza—use the \\* command. This forces a line break in the formatted output, while preventing a page break at that line.
If you feel it is acceptable to have a page break in mid-stanza, then you can use the \\ command instead of \\*. For example, Figure 2.3 uses \\ when a line ends with a semicolon. Note that using \\ does not force a page break at that point; it merely indicates that a page break is acceptable.

There is one last point to note about the typesetting of a poem. The \begin{verse} command can take an optional parameter, which, if used, is enclosed in square brackets. You can see an example of this in Figure 2.3: \begin{verse}[16em]. The optional parameter specifies a size, which can be specified in a variety of units, including point (pt), millimetre (mm), centimetre (cm), inch (in), ex (ex) or em (em).¹

If you do not specify the optional parameter to the verse environment, then the poem will be typeset slightly indented from the left-side margin. For example:

O mistress mine, where are you roaming?
O stay and hear! your true-love’s coming
That can sing both high and low;
…

If you do specify an optional size parameter, then the verse environment pretends that the length of each line in the poem is the specified size, and centres the poem on the page based on that pretended line length, as shown in Figure 2.4. As a contributor, you should not worry about specifying an accurate value for the optional parameter to the verse environment. (If you want, just omit the optional parameter and its square brackets.) If the editor of the anthology decides to centre poems, then she can use a trial-and-error approach with a document previewer to choose a suitable value for the optional parameter to the verse environment.

You might want your poem to be formatted in a very specific way, for example, perhaps every second line of the poem should be indented. Arguably, such formatting decisions should be made by the editor of an anthology, rather than by each individual contributor, so there can be consistency of formatting across all poems in the anthology. However, if you feel strongly that your poem should be formatted in a particular way, then you should contact the anthology’s editor to express your wishes.

2.5 Special Characters

The markup commands used in Canthology come from the LaTeX typesetting system, upon which Canthology is based. The following characters have special meanings to LaTeX:


# $ % ~ _ ^ \ & { }

If you need to embed any of those characters in your contribution, then you should use the appropriate command shown in the table below.

Command	Output
`\#`	#
`\$`	$
`\%`	%
`\_`	_
`\^{}`	^
`\&`	&
`\{`	}
`\}`	{
`\textbackslash{}`	\
`\textasciitilde{}`	~

For example:


I can see the \# symbol on my telephone keypad.

produces the following output:

I can see the # symbol on my telephone keypad.

As you can see from the table, most of the special symbols can be typeset by preceding them with \. The most notable exception to that rule is the \ character itself. If you want to use that character in a document, then use \textbackslash{} (the {} indicates that this command does not take a parameter). If you accidentally use \\ instead, then you will force a line break in the output. For example:


This is a \backslash{}, but this is a line\\break.

produces the following output:

This is a \, but this is a line
break.

The % character starts a comment that continues until the end of the line. Comments are not copied into the output document. For example, the following example accidentally uses % instead of \%:


Pareto found that 80% of the wealth in Italy was
owned by just 20% of the population.

so it produces the following incorrect output:

Pareto found that 80 owned by just 20

The fix is to replace % with \% in the input document:


Pareto found that 80\% of the wealth in Italy was
owned by just 20\% of the population.

so it produces the following correct output:

Pareto found that 80% of the wealth in Italy was owned by just 20% of the population.

1: A point is 1/72.27 inch. An ex is roughly the height of the letter “x” in the current font. An em is roughly the width of an “M” in the current font, which is often equal to the font size. For example, if the font size is 10pt, then 16em is equivalent to 160pt, but if you change the font size to be 12pt, then 16em will be equivalent to 192pt. People who design document layouts sometimes like to express sizes in ex or em units because this enables the sizes to be scaled automatically if the font size is changed.