... now with 35% more arrogance!

Thursday, April 18, 2013

Layout Tutorial: Master of Content

Layout Tutorial 2: Master of Content

Part 1 of the Layout Tutorial focused on what to install and where. Part 2 introduces a basic workflow and format techniques for simple RPG projects like general blog posts or things like house rules, magic items, or spells.

The Plain Text Process

Using TED Notepad or some other plain text editor is good because it promotes the first two goals I listed in the last post: "Have one master, many slaves," and "Keep it separated". You only want to do your main work -- your content -- once, and only do minimal layout tweaks for each product you create from that content (blog post or web page, ebook, PDF or final print product.) That means your master document should be as product neutral as possible, to simplify production in different formats. And nothing is as product neutral as plain text. Nothing avoids distracting layout decisions like plain text, either.

The process I use involves doing your text in the Markdown format. Markdown is a way of indicating minimal format features like emphasized text, bullet or number lists, or section headings without making your text an unreadable piece of crap. It's based on the way people formatted text in the pre-HTML email days, or even the pre-computer typewriter days. You break text into paragraphs by skipping a line, and you emphasize text by putting *stars* or _underscores_ around it. **double stars** makes it strong emphasis. Emphasis usually shows up as italics and strong emphasis as bold in a web page or PDF, and triple stars in that case will be bold italics, but "emphasis" is a concept, not an appearance; how emphasis and strong emphasis are displayed can be changed at the output level.

A Typical House-Rule Post

Let's start with a simple example: posting a house rule to your blog. We'll use a compact version of the armor/encumbrance rule I mentioned recently. You would start preparing your content this way:

Base Move is based on armor worn. For Fighters and Clerics:

Light/No Armor = **Move 12**
any Metal Armor = **Move 6**
any armor + carrying maximum weight = **Move 3**

Any other class has the movement rate halved, minimum Move 3. Anyone with Move 3
is considered overburdened, always acts last each round, and must rest 2 turns out
of every 6 turns of activity, instead of just 1 turn.

The length of each line doesn't necessarily have to match what I typed; as long as there's no white space between lines or at the start of a line, the Pandoc Markdown conversion will join lines together in a paragraph. The stars around the Move scores were a design choice; I want the Move scores to stand out (strong emphasis.) I could have put the emphasis around the armor type instead.

We probably don't want the armor/move lines to be joined together, so in TED Notepad, we can select all three lines and use Tools > Lines > Quote to put * (a star and a space) at the beginning of each line. That's how you format a bullet list. If you wanted to number the steps in a process instead, you would just put 1. in front instead.

1. Type each step on a separate line.
2. Select all the lines.
3. Select `Tools > Lines > Quote` and put `1. ` in front
   of each line.

I changed the numbers in the above example, but I could have used "1. " for every line. Pandoc doesn't care what the other numbers are. It only cares what the first number is; it will start the list with that number and go in sequence. Notice also that I continued step 3 on the next line. I actually didn't need to put spaces at the beginning of the continued line, as long as it's all one paragraph. I only did that to make it look nice in the text file. Like I said: Markdown is based on the way you would format things on a typewriter.

(Also, not important, but: the backticks I used in Step 3 are one way of marking verbatim text; in other words, text that isn't interpreted as Markdown format. It's probably not something you would need, but it's good to know that there are many other things in Markdown I'm not even going to cover. It's all in the Pandoc docs, though.)

Save any text you are working on in the appropriate location, such as \proj\blog\house-move.txt or ~/proj/blog/house-move.txt on Mac/Unix, before converting it in Pandoc.

If you are typing the entire post in your notes.txt file using TED Notepad, you can select just the part you want and use File > Exclude..to save (and cut) part of your notes to a separate file.

Creating "Slaves" for a Master Document

You need to use a command line or terminal, or some kind of script or batch file or workflow, to make Pandoc convert your Markdown text to HTML or some other document. Pandoc is pretty smart about guessing file format based on the extension, and it assumes .txt files are Markdown unless told otherwise, so the command is pretty simple: pandoc filename.txt -o docname.html The -o stands for "output", so that command creates an HTML version of filename.txt and names it docname.html. We can actually set up TED Notepad to do this for us, without needing to open a terminal or command line.
  1. Select Tools > Text Filters > Manage List..
  2. The dialog should be open on the Filters tab. Click New.
  3. The Name should be something like "make HTML". The Command is pandoc %F -o \proj\%1.html. The Description can be blank for now.
Once you save this filter, try it out. Make sure you have the house-move.txt file open and select Tools > Text Filters > make HTML. You'll see that Execute contains pandoc %F -o \proj\.html and the cursor should be in the box labeled %1. Type blog\house-move and you'll see that Execute now contains pandoc %F -o \proj\blog\house-move.html. Click OK.

The %F is the full path to the current open file, so what Pandoc does is create an HTML version and save it in the \proj\blog\ folder. It shouldn't take long; you'll see a brief pop-up. What you need to do next is open it in your web browser. An easy way to do this is: open your browser and go to this location: file:///C:/proj/blog/. Change the C: to the appropriate drive, if necessary, or ~/ on Mac/Unix. This should open an index page of that folder, in most browsers. Bookmark that location (you'll use it a lot) and look through the list for house-move.html or whatever you named it. Click it to view; it should look something like:
Base Move is based on armor worn. For Fighters and Clerics:
  • Light/No Armor = Move 12
  • any Metal Armor = Move 6
  • any armor + carrying maximum weight = Move 3
Any other class has the movement rate halved, minimum Move 3. Anyone with Move 3 is considered overburdened, always acts last each round, and must rest 2 turns out of every 6 turns of activity, instead of just 1 turn.
You can copy and paste this into a Blogger edit box, for example. I will warn you that Blogger has a dumb tendency to remove the lines between paragraphs. If you are going to upload web opages to an actual website, you'll need another filter, because this file is actually an HTML fragment, without the proper header information. Call the new filter make web page. The correct command for that is: pandoc --standalone %F -o \proj\%1.html.

Let's set up a couple other quick output filters. Make one named make ebook with the command pandoc %F -o \proj\%1.epub. This will turn a single file into a simple EPUB format ebook that you can read on your ereader or tablet. We'll be coming back to ebooks later, but this is a handy thing to have right now.

Assuming you've installed MiKTeX, make another output filter named make PDF with the command pandoc %F -o \proj\%1.pdf. This filter will take a while the first time it is run, or at least it did for me, because MiKTeX will want to download additional components. Unless you installed the complete version of MiKTeX; I didn't, so I had that little delay. It's not that difficult, though, and will go much quicker the second time you use it. The output will be a PDF (with an invisible LaTeX step you won't see.)

Pandoc has lots of output possibilities, as well as many options to tweak, but these are going to be what we will focus on for now.

Part 3 will look at structuring documents, making things show up in an index, and using templates or standard "boilerplate" to simplify the job and create a unified look.


  1. This is fantastically useful, if for no other reason that I now know about pandoc.

    One thing that I would like to do is be able to tag different sections of a document so that I can hide or show different sections by output. Thus, a campaign document could have paragraphs labeled for players mixed in with ref information, or a single document could contain both "basic" and "advanced" rules for a game (if that makes sense).

  2. I skimmed the pandoc user guide, and didn't see anything about tagging sections. This should probably be handled with a preprocessor or template language anyways, so I decided to just use cpp.

    1. I assume you mean to control which sections are included? As you suggest, a preprocessor will give you more control, but there is another way to handle it. Actually, a couple other ways, but they're all based around the suggestion I made in part 1: for big projects (as opposed to blog posts or short articles for a zine,) make a separate directory for each project, and break up your master document into several documents. Not different versions, but more like different chapters and subchapters.

      I wasn't specifically planning to talk about that, although I was going to talk about something related (using different images for web page, ebook, and PDF.) That sounds like a good additional tutorial to do.

    2. In this case, I really want control almost sentence by sentence, so that I can mark examples, design notes, and so forth. I think the text is too mixed up to be able to be handled using multiple files.

      I first tried cpp, but it didn't play well with the leading hash marks required by the markdown headers. The ruby erb template language worked though.

    3. I haven't tested these yet, but I see a couple possible ways of doing this sentence-by-sentence. They depend on the fact that Pandoc's Markdown allows raw HTML and raw TeX/LaTeX, which are ignored when the write format doesn't allow that kind of markup.

      So, one way to do it is to just insert HTML comments in front of each section, like <!-- GM Only --> and write a simple filter in Perl or something that pipes text line by line to Pandoc until it sees that line, then starts discarding lines until it sees a <!-- Player --> line.

      Another way specifically for PDF or LaTeX output would be to use \begin{gmonly} and \end{gmonly} to mark your sections, then create a custom template that defines defines the gmonly environment as the equivalent of a comment. Using 'pandoc --template gmonly.latex -o mydoc.pdf *.txt' will create a PDF that doesn't include the stuff marked "GM only".

      I'll have more explicit instructions when I get around to testing that kind of stuff. I test everything before I include it in the tutorials.

  3. So I've been playing with pandoc, and there are a few things I would love to be able to do that I haven't been able to figure out.

    1. Digest size
    2. Easily change fonts (even just between broad categories, like sans serif)
    3. Change margins

    I suspect the answers have to do with mucking about directly with (La)TeX stuff, but it would be fantastic if it can be done in other ways.

    1. I'm going to talk about all those things later on, after I've played with them myself to find the simplest and most efficient way to do them. But basically, these are all done in either CSS or LaTeX.

      You can specify the margins for LaTeX using a simple switch in Pandoc:
      pandoc -V geometry:margin=1in
      (Or: geometry:"top=2cm, bottom=1.5cm, left=1cm, right=1cm" if you need more margin control.)

      You can, as I said, insert raw HTML or LaTeX into a Markdown document, so you can work mostly in Markdown and only tweak fonts and things as needed. I've already tested pasting a <STYLE> block into a document and adding <DIV>s around images or paragraphs; these show up in HTML output, but are trimmed from other output. Similarly, you could add the LaTeX command to switch to sans serif (I think it's \sffamily and \rmfamily switches to roman.) They won't show up in other output formats.

      There's also a -H or --include-in-header switch that lets you insert a (verbatim) text file into the header, so that you could have a standard style block for HTML or specific margin and font definitions for LaTeX. Or, you could define templates like rpgbooklet.latex and use --template to tell Pandoc to format your PDF a specific way. I think there's actually a booklet document type in LaTeX that sets up default margins and stuff for digest-size booklets.

    2. Thanks, all that is useful. The \sffamily works, though it doesn't affect the generated table of contents (presumably I need to put it somewhere in the template to also affect the TOC).

      I tried messing with --template=default.latex to try to get a digest size output, but it's been too long since I've messed with LaTeX and I couldn't get it to work before my patience gave out. \usepackage with a5paper seems promising still, but I'll probably just wait until you get to that part of your tutorial naturally.