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.