Layout Tutorial: Structures and Templates

Here's Part 3 of the DIY layout tutorials for hobby press publishing.

Layout Tutorial 3: Structures and Templates

Part 1 of the DIY layout and design tutorials covered free programs and setting up an efficient workspace; Part 2 covered using Markdown and Pandoc for blog posts and draft versions of EPUB and PDF. This time, I'm covering the structure of longer documents, links, and the use of templates and repeated blocks of text.

Layout for Spells

Let's talk about something RPG writers and designers are likely to do: spells and magic items. Or special equipment, for non-fantasy settings. Both are pretty much the same: a standard block of quick information, a paragraph or two of description. Doesn't matter which order these are in, but the name of the spell or item comes first and usually stands out. This might be a typical spell format for Swords & Wizardry:

Hunger
------
> **Spell Level**: Magic-User, 1st\
> **Range**: 240 feet\
> **Duration**: hour

Makes living creatures feel hungry, affecting
negotiations or morale and possibly distracting
creatures from other actions. Affects creatures
of up to 4+1 hit dice; use the Sleep spell for
numbers affected.

There's a couple new things in that bit of Markdown text. First, for the spell's "info block", each line begins with a right angle bracket (greater-than sign). In Markdown, this means "indent". It's great for creating block quotes, for example. By itself, though, each line in the block quote would be run together as a paragraph; the backslash on the end of two of the lines forces the line to break. That creates the following layout for the spell:

Hunger

Spell Level: Magic-User, 1st
Range: 240 feet
Duration: hour

Makes living creatures blah blah blah...

Templates and Standard Boilerplate

What you should do, once you've set up a sample of a particular thing (S&W spell, OSRIC spell, artifact, tech item) is make a quick copy-and-paste duplicate in whatever document you are working on, change the wording in the duplicate to something more generic, like this:

Spell Name
----------
> **Spell Level**: Class, Level\
> **Range**: feet, yards, touch\
> **Duration**: minute, turn, hour, day

blah blah blah...

... and then select the duplicate and use File > Exclude.. to cut out that section and save it to a separate file. Save this in\proj\template\. In this case, I saved it as sw-spell.txt.

The \proj\template\ folder, as I mentioned in Part 1, is for text that you insert into documents and then change to suit a specific need, exactly like this one. Rather than retype the repeated material again and again, possibly from memory if you haven't written a spell or item description for a while, you solve your layout problems once and save it for further use. Insert it using File > Include.. and navigating to the template folder to select the appropriate file.

The \proj\std\ ("standard") folder can also include pasteable Markdown-formatted snippets, but it is meant for stuff you might have to call from the command line, thus needing a path that's as short as possible. For example, Pandoc has its own templates and reference documents that you do not copy and paste into your master document, but instead use a command-line switch: pandoc --template=\proj\std\booklet \proj\blog\spell*.txt -o \proj\spellbooklet.pdf.

A lot of the files you would put in the std folder will not be in Markdown format; it will be CSS files for EPUBs, files to include in the headers of web pages, LaTeX macro definitions, or PDF formats. But what you might also want to put in std is any boilerplate text, stuff that doesn't really change from project to project. For example, most of the Open Game License is just a huge block of text, usually set up to be in small print. Only the last two paragraphs (copyright information for Open Game Content used and material excluded as Product Identity) ever change. Shorter examples would be a Creative Commons license notification, or contact info, or even a block of Lorem Ipsum text to paste into a test document when you're working on a layout.

Headers

But back to our spell example. The third new thing in that sample was the way the name was marked:

Hunger
------

That line of hyphens under the spell name marks it as a header. The superficial effect of marking text as a header is that headers usually are a different size, possibly a different font or even typeface. Level 1 headers are usually large print and used for chapter or article titles. Level 2 headers are a little smaller¹ They are best used for sections of a chapter or article. Level 3 headers are smaller still and can be used for subsections or for marking individual items you want to include in a PDF's bookmarks.

Level 1 headers can be marked with a row of equal signs, while Level 2 headers are marked with a row of dashes. In this case, I used a Level 2 header for the spell name, with the idea that after I've written several individual spells for blog posts, I could later bundle together the spells in an article or ebook. I would write an introduction explaining any background for the spells; the title of the article would be a Level 1 header, marked with equal signs. Each spell's name would then be a section of the article or ebook.

There's another way to mark headers, and that's by placing pound (#) signs and one space at the beginning of the line, like this:

## Hunger

The number of pound signs is the header's level (in this case, Level 2.) Since the underlining method looks nicer and is more distinctive when scrolling through long texts to find a section, I use that for my Level 1 and Level 2 headers exclusively. If I need a Level 3 header (or 4 or 5,) I have to use the pound signs for those. The advantage to using the pound signs is that header levels can be changed quickly. Also, in some cases (when setting up tables or horizontal rules, for example,) a line of hyphens might confuse Pandoc and produce the wrong layout.

Structure

Headers aren't just for appearance, however. They define the structure of your document, which is going to be important when designing larger projects. When you are composing text, you don't want to worry about how things are going to look, aside from a few superficial things like emphasizing text. You want to focus on what you are saying and how your ideas are organized. Level 1 headers represent a large chunk of ideas: an entire chapter, an entire article. This gets broken up into smaller chunks (sections.) For example, an article on "ten scary spells" would be broken up into ten sections, one for each spell, plus maybe a preface and a follow-up section.

Structuring a document can help in the planning phase. For example, let's say you are going to write an article about barbarian tribes in some setting. You only have vague ideas; you're making this all up from scratch. You start by listing general things you know you need to cover, one per line:

Introduction
Barbarians vs. Civilization
Barbarian Tribes
Role of Barbarians
Playing Barbarians

Then, under each line, add a line of hyphens and two blank lines. That turns each of those lines into Level 2 headers. Next, come up with some barbarian tribe names and insert them below the "Barbarian Tribes" header, one tribe per line; if you have a concept but no tribe name, use a place-holder name like "Short Stabbing-Sword People"² When you have enough, you can add three pound signs and a space in front of each tribe name. Now, you can fill in paragraphs of text in each section, in whatever order you wish. If you only have one phrase or sentence that pops into your mind, find a section it would fit in, then add it. You can add more or fix grammar later. Eventually, your barbarian article is finished and has a structure.

Structure in a document also matters for the table of contents and for PDF bookmarks. I'll have more to say about the table of contents when I get to EPUBs, but if you use the "make PDF" filter explained in Part 2 (or pandoc master.txt -o master.pdf from a command line,) Pandoc will create navigation bookmarks in your PDF for every Level 1, Level 2, and Level 3 header by default. That's also what will be included in the Table of Contents. The default "header depth" can be changed, if you you only want Level 1 and 2 headers, or if you want to include levels below Level 3.

Knowing this, you can leave the depth set to the default and use #### for text you want to set apart (as if it were a header,) but that you don't want to include in the Table of Contents. This may be important if you want a short ToC but have a ton of items, spells, or monsters you plan to include.

Linking

Headers also create spots that you can link to directly, which is how the Table of Contents in an EPUB works. You can also use it to include references, such as "See the Hunger spell". How? You need to set up a link to the header's identifier. Pandoc will automatically create identifiers for every header by default; the docs explain in detail how to figure out the identifiers, but the short answer is that they are plain lowercase letters, numbers, dots, hyphens and underscores, without formatting, starting with the first letter in the header, with white space turned into hyphens. So, the "Layout for Spells" section near the beginning of this document would have an identifier of "layout-for-spells", while the Hunger spell is "hunger".

To create the link, you need to insert a list of reference links directly into your master document. This can be anywhere, but it must be separated from the other paragraphs in your master document by blank lines. I usually put a block of link references after the paragraph the links appear in or at the end of the document. Start with the list of identifiers:

blah blah blah layout natter
natter natter Hunger spell blah
blah blah blah natter

: #layout-for-spells
: #hunger

Each identifier has a pound sign in front of it, but this has nothing to do with Markdown. It has to do with the way HTML anchors work. Pick the word or words in the paragraph you want to turn into a link, like "layout", and put square brackets around it: [layout]. Now, copy that word, including the brackets, and paste it in front of the first line in the link reference: [layout]: #layout-for-spells. Similarly, you would place brackets around "Hunger" and insert that in front of the second line, so now the text looks like:

blah blah blah [layout] natter
natter natter [Hunger] spell blah
blah blah blah natter

[layout]: #layout-for-spells
[Hunger]: #hunger

The link references block itself doesn't appear in your documents. It's just a way to list what a link in the actual text will link to.

This is the simplest way to handle links. There's actually other ways Pandoc and Markdown can handle links, but I like this way because the list of links stands out and it's easy to save a standard list of links as a template, for example.

To make external links (on the web,) you would use a full URL, like this link I used earlier:

[Lorem Ipsum]: http://loripsum.net

This is going to be important for inserting images, but that's going to have to wait for the next installment.

---

1. except for on Blogger, where they are a lot smaller, for some reason.(BACK)
2. That's Saxons, by the way...(BACK)