Layout: Text Tables

Layout Tutorial 4: Text Tables

If you are writing a lot of rules material for blog posts or zines, especially if you are creating new classes with their own experience/hit dice progressions, you're going to do a lot of tables. They're simple to set up in the TED/Pandoc process I'm describing. However, if you want fancier features, you need to be aware of your target product's format.

Let's start with a simple d6-based table for what a character sees when peering through a keyhole, under a door, or through a crack.

Peering Through Cracks and Keyholes

d6 Roll	What You See
0 or less	Bugs heading straight towards your eye! If you are surprised, they reach you before you can look away.
1	An eye looking back! Lose element of surprise.
2-4	Nothing, just darkness.
5	Light of some kind.
6	Light and a moving shadow. You can't be surprised by room's occupant.

The Markdown format for this table looks like this:

---------------------------------------------------
d6 Roll     What You See
---------   ---------------------------------------
0 or        Bugs heading straight towards your eye!
less        If you are surprised, they reach you
            before you can look away.

1           An eye looking back! Lose element of
            surprise.

2-4         Nothing, just darkness.

5           Light of some kind.

6           Light and a moving shadow. You can't
            be surprised by room's occupant.
---------------------------------------------------

Table: Peering Through Cracks and Keyholes

Here are the things to note:

1. The table must begin and end with a line of dashes.
2. The headers are underlined with dashes as well. Spaces separate columns.
3. This is a multi-line table, which requires blank lines between rows. If you miss a blank line, the rows won't look the way you expect.
4. There is no blank line after the last row, just the dashed line that indicates the end of the table.
5. There is a blank line after the last dashed line, followed by the table caption, which begins with the word "Table" followed by a colon and the caption. You can leave the caption out.

One potential trap: don't surround the line of dashes with blank lines, like this:

A

--------

B

Pandoc will not interpret that as the beginning of a table. It will treat it as a horizontal rule (dividing line) instead.

The headers and the dashes underneath the headers tell Pandoc how to align the columns. If the dashed line under a header is aligned flush with the left end of the header and is longer than the header, the column will be flush left, as you see here. If the header is aligned flush right, the column will be flush right. If the dashed line is longer than the header on both ends, the column will be centered. If the line and the header are the same length, the default alignment will be used, which may or may not be the same as flush left.

The number of spaces between the columns isn't important, as long as there are spaces, but the width of the dashed header lines determines the width of the columns. You may find, when you test a table, that one column is too narrow. Increase the length of a dashed line to change the column width; add spaces between column entries in each row to make the columns line up again.

Building a Table

Lining up columns in a table may seem pretty tedious, but TED Notepad has a feature that will simplify this a great deal. Let's set up a "dummy table". Like this:

d6,double,triple,quadruple
---,-------,-------,----------
1,2,3,4
2,3,6,8
3,6,9,12
4,8,12,16
5,10,15,20
6,12,18,24

The columns are not lined up, except accidentally. We're just using commas to separate columns. Some of you may recognize this as Comma-Separated Values (CSV) format. If we were doing table entries that included long text, we'd just include a snippet of text, not the whole thing. We can add more text later. The dashed lines are one hyphen longer than the text in the headers.

Now, use the Columns & Numbers tool to line things up better: select
 Tools > Lines > Columns, Numbers.. from the menu. A dialog box will open. Our first concern is the output mask. We need to make it look like this:

  %1 %2 %3 %4

Each percent/number pair is a marker for one column of your final output. Anything between the column markers in the output mask, such as blank spaces, will show up between the columns in the actual, final text. In this case, we have four columns, so we have %1 through %4, separated with spaces.

Each of the markers has a tab below which defines how to select text to put in each column. To convert a simple comma-separated list like the one above into something resembling a table:

1. Select Columns from __ to __ on each tab.
2. Change the column numbers to 1 to 1 for column %1, 2 to 2 for the second column, and so on.
3. Set the delimiter for each column to a comma.

You can look at the preview box to make sure that the result looks something like this:

1    2    3    4
2    3    6    8
3    6    9    12
4    8    12    16
5    10    15    20
6    12    18    24

Clicking the Cut button changes your selected text to the column shown.

Afterwards, trim or insert a few spaces to make the columns line up pretty, either left-justified or right-justified. It's so much easier to let TED do about half the work for this than to line it all up from scratch. Add a line of dashes at the start and end of the table, and put blank lines between the rows.

d6	double	triple	quadruple
1	2	3	4
2	3	6	8
3	6	9	12
4	8	12	16
5	10	15	20
6	12	18	24

A Word About Structure, Format, Layout and Design

You're probably anxious to find out how to do fancy tables with every other row shaded, as you see in many RPG books. And you're probably wondering about other pretty format tricks. However, this is where we have to take a detour and talk about four concepts I've been tossing around without really distinguishing them from each other very much: structure, format, layout, and design.

The structure of a document is the most important part. We start with raw information, we separate the information into chunks by inserting section headers, we turn some information into bullet or numbered lists. It organizes information in a way that makes it easier to grasp and easier to refer back to.

The format of a document is the low-level decisions about appearance that can support the structure. Putting strong emphasis on a word, as I did in the first sentence of this paragraph, does not strictly speaking define the structure, but it helps to draw attention to the main concept of this paragraph. Similarly, indenting a block quote helps separate the quote from the rest of the document, drawing attention to it.

Both structure and format affect the appearance of the final output, but they are not concerned with the specifics of that appearance. The Markdown block indent marker doesn't define how much to indent the block, or whether all block quotes should be in a different font size or typeface. Strong emphasis does not necessarily mean "bold", even though that is usually the default.

I define layout and design in terms of the physical appearance of the page and the product as a whole. They are intertwined, but I see layout as the position of elements and white space and the flow of text around those elements, while design is the elements of appearance that relate to how the product is used (things like page headers or using a unique font for chapter titles.)

When you are working on a document and trying to keep it uniform across multiple output formats, you have to forgo thinking about many layout and design elements. You can't control layout or design using just Markdown, not only because there aren't any layout or design commands built into the Markdown standard, but also because layout and design depend on what the actual product is, and how it's displayed. Page layout for web pages is handled by your web browser. Page layout for an EPUB is handled by your ereader. Page layout for a PDF or printed document is handled by the software that makes the PDF, which in this case is the pdflatex renderer in MiKTeX. These things don't work the same, so if you make layout and design decisions for one, it's not going to look the same in the others.

One example is the placement of tables on a page. When you use Pandoc to turn your plain text table into an HTML table for either your blog or an ebook, the table shows up right where it is relative to the whole text.

Blah blah blah see this table. 

[TABLE] 

Here's how to use the table.

The table appears between the two lines of text.

However, when you turn the same source text into a PDF via LaTeX, LaTeX decides the best place to put the table. This is called a float, and it's something that happens with images as well, unless you tell LaTeX otherwise. For tables, this doesn't matter; LaTeX will probably make a better decision than you will, unless you have years of layout experience. The only thing you need to be aware of is to avoid referring to the table by position, as in "See the table below" or "see this table:". What you want to do is reference it by name: "See the Experience Table."

Images can be a little easier. There's a simple trick to make sure they don't float. There's a simple way to guarantee they get a caption, so that you can refer to the figure by name. I'll get to that in the next part of the tutorial. However, there are other things about positioning images and tables that are going to require different methods for different forms of output.

Shaded Rows

One example is the shaded table rows we were talking about earlier. It's now pretty much standard practice to shade every other row of a table, or to shade them in groups of three. I'm not going to talk about how to do that in a PDF yet, because we're going to have to learn about a lot of other things first. It's possible to do it in HTML output, like a web page, but this requires using an HTML-specific method: style sheets, or CSS.

I'm not going to go into CSS too much, and certainly not now. It's best to ease into this. However, I will point out this important fact: Markdown doesn't mind if you insert raw HTML into your document. For some versions of Markdown other than Pandoc, this was the only way to get get a table.

Fortunately, we don't have to deal with that. However, we can insert a style sheet in the middle of our document, using a <style> ... >/style> block. And the good thing is: this style block won't show up in other formats that don't use CSS.

If you do a table in Pandoc and output to a web page or blog post, then look at the source, you'll see the rows of the table marked either  <tr class="odd">  and  <tr class="even"> . The class attribute tells the web browser to use the defined style for that class. In this case, no style has been defined, so it just puts out a bland table. However, if you know CSS, or look up tips on the web, you can insert a style block that defines what to do for the "odd" and "even" classes. Here's a sample style block:

<style>
.odd {
      background-color: whitesmoke;
     }
.even {
      background-color: white;
      }
</style>

Put this at the start of your document, for now, and it will give you a shaded table. This is not the best place to put the style block, but we'll talk about that later.

EDIT: Some of my examples got treated as actual CSS commands. Should be fixed now.