Layout: Web/EPUB Graphics

The installments so far in the DIY layout tutorials for hobby press publishing:

• Part 1 --- Free programs and setting up an efficient workspace;
• Part 2 --- Basic blog posts, webpages, and draft EPUB/PDF;
• Part 3 --- Structuring documents, using links, using templates;
• Part 4 --- Creating tables;
• Part 5 --- Graphics for simple projects.

Here is Part 6.

Layout Tutorial 6: Graphics for Web and EPUB Projects

I made a distinction in Part 5 between simple projects and complex projects. A simple project is a single master/source document that will appear more or less the same, no matter what the final output is (web, ebook, PDF.) A complex project needs to distinguish between web layouts, ebook layouts, and PDF/print layouts. To do this, anything specific to one layout is separated from the shared content. This typically means more than one file. Sometimes, the content itself is broken up into several files, perhaps separated by chapter.

Project Folders

Up to this point, I've been dumping all my files into a \proj\blog\ folder. That's fine, for simple projects. But if I were going to create, say, a unique monster manual, with pics for some of the monsters, I would want to create a new folder, something like \proj\mon\ (Keep the name short...) My content file or files would be here.

Your file names, excluding the extension on the end, should be divided into two or three parts, like this:

01-mon01.txt
01-mon01-adv.txt
01-mon01-gm.txt
01-mon01-lo.txt
01-mon01-hi.txt
02-mon02.txt
etc.

The parts are chapter number, identifier, and an optional control key.

When you first start working on a project, your master document only uses the identifier, something like mon01.txt. For larger projects, you should split your master into chunks of related material. Use a three-to-five character identifier that matches the name of the project's folder, followed by a 2-digit number, starting with foo01 and increasing by 1 each time you start a new chunk. After you've finished a couple solid parts, you can add the two-digit chapter number in front, separated by a hyphen from the rest of the name. This indicates the actual order of the parts, starting with 01. They do not have to match the two-digit identifier; in fact, the reason for using both a part number and an identifier is so you can change the first two digits freely to change the order of the parts, or to make room for other material.

(I've skipped 00-mon00.txt and its companion files because they will be the last thing added to your project: the title page and the information it includes, plus other front matter.)

The control key after the second hyphen indicates optional material, such as:

adv

"advanced" material, so that you could produce basic and advanced versions of a single book.

gm

"GM-only" material, so that you can print one version of a house rules document for players and a different version for the GM.

pc

"Player" material, an alternative to the "GM-only" tag, used when you want GM-only material (the main text) to appear first.

The point of this naming scheme is to use wildcards to select which parts to include when producing a draft or final product, and to keep them in the proper order. I'll be expanding on this later.

More on Image Formats

As I said before, the web browser or ereader figures out how to display images for those output formats, while the LaTeX engine figures out how to insert a graphic into a PDF. Browsers and ereaders do not have to support all image formats; I believe some ereaders will only support JPEG, PNG, the GIF format that PNG is meant to replace, and SVG (scalable vector graphics.) They might also support BMP (bitmap.) Web browsers will usually support all of these, plus several others, but only if the web server sends a code (called the MIME type) telling the browser what the image format is. There's no guarantee that a web server will be properly configured to support PCX or TIFF, for example.

In contrast, PDFs produced by LaTeX can contain JPEG, PNG, encapsulated PostScript (EPS,) and scalable vector graphics in PDF format. I'm not going to deal with EPS in these tutorials, because I'm trying to keep things simple and it looks like using EPS requires a few steps that require more effort.

Low Res/Hi Res Versions of a Product

A second thing to consider is the image resolution. Web graphics are usually low resolution: 72 dots per inch (dpi.) It keeps both the image size and web page load times low. It's also passable for EPUBs and PDFs you plan to use for your personal game. However, if you want to distribute a semi-pro product, you will probably want a higher resolution, such as 300 dpi. What this means is you need a way to separate which images appear in a web page or draft/amateur product from those that appear in a higher-quality EPUB or PDF.

There is a fairly simple way to do this. Remember the way we indicate the references for links and images in our master document?

[Part 1]: /2013/04/layout-tutorial-getting-ready.html
[Part 2]: /2013/04/layout-tutorial-2.html
[Part 3]: /2013/04/layout-tutorial-3.html
[Part 4]: /2013/05/layout-text-tables.html
[Part 5]: /2013/05/sack-dangers.html

[image 1]: /proj/pix/image1.png
[image 2]: /proj/pix/image2.png
[image 3]: /proj/pix/image3.png
[image 4]: /proj/pix/image4.png

Here, I've separated the links and the images into separate blocks. We can put each block anywhere in our document that we'd like. We can put a block of links at the end of the document, or after the paragraph where the links appear. It will define all the links with those names in the document, wherever they may be.

If you put the block that defines image references at the end of your document, it's easy to locate and quickly redefine images without changing your main text. But it's even easier to split the image references into a separate text file. Pandoc can join the two parts for you and translate them into your final product. The command will look like this:

pandoc 01-stuff01.txt 01-stuff01-lo.txt -o stuff.html

Pandoc starts with 01-stuff01.txt and tack 01-stuff01-lo.txt on the end, then converts the combined document. 01-stuff01-lo.txt contains references like this:

[image 1]: /proj/pix/image1-lo.png
[image 2]: /proj/pix/image2-lo.png
[image 3]: /proj/pix/image3-lo.png
[image 4]: /proj/pix/image4-lo.png

An alternate file, 01-stuff01-hi.txt contains references like this:

[image 1]: /proj/pix/image1-hi.png
[image 2]: /proj/pix/image2-hi.png
[image 3]: /proj/pix/image3-hi.png
[image 4]: /proj/pix/image4-hi.png

Or, you can replace "lo" and "hi" in the image names with actual resolutions:

image1-72dpi.png or image1-300dpi.png.

Text Wrapped Around Graphics

Another reason to split your project into parts this way is to separate out images, tables, or other material with special layout needs. For example: so far, all our images have been inserted into the text without any tweaks to the layout. Either the image is completely separated from the text, or a small image is inserted like a character as part of the text. Compare that to the image at the beginning of this paragraph: the lantern is larger than one or two lines of text, but the text has been aligned with the top of the image, instead of the bottom, and the text is wrapped and flows along the side of the lantern.

The way you do this in a web page or EPUB isn't the same as the way you do it in a PDF or in print. The first requires raw HTML, the second requires raw LaTeX. Pandoc allows you to insert raw HTML or raw LaTeX into a Markdown document to get tighter control of the layout than Markdown allows; when making a PDF, HTML will be ignored, and when making a web page or EPUB, LaTeX will be ignored. I'm only going to talk about web pages and related output formats like EPUB this time; I'll deal with wrapped images in a PDF later.

You may remember in Part 4, I gave an example of creating shading for alternate rows of a table using a <style> block. You need the same trick to make text flow around an image. Here's your style block:

<style>
.floatleft
{
float: left;
margin: 0 10px 10px 0;
clear: left;
}

.floatright
{
float: right;
margin: 0 0 10px 10px;
clear: right;
}

.containingbox p { margin-top: 0;}
</style>

We could just insert that at the beginning of our document, but there's a better way to do this. You will be using this exact same style spec in any project that flows text around an image in a web page or ebook, so it's a prime candidate for something you can stick in the \proj\std\ folder. Save the style block to a file named something like wrap.txt. When you want to flow text around an image, first put DIV tags around one or two paragraphs of text you want to wrap, like this:

<div class="containingbox">
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aufidio,
praetorio, erudito homine, oculis capto, saepe audiebam, cum se
lucis magis quam utilitatis desiderio moveri diceret. Hoc est dicere:
Non reprehenderem asotos, si non essent asoti. Duo Reges: constructio
interrete. Is ita vivebat, ut nulla tam exquisita posset inveniri
voluptas, qua non abundaret. Quid ergo aliud intellegetur nisi uti
ne quae pars naturae neglegatur? Is ita vivebat, ut nulla tam
exquisita posset inveniri voluptas, qua non abundaret. Sin laboramus,
quis est, qui alienae modum statuat industriae? Ex quo intellegitur
officium medium quiddam esse, quod neque in bonis ponatur neque in
contrariis. Sed est forma eius disciplinae, sicut fere ceterarum,
triplex: una pars est naturae, disserendi altera, vivendi tertia.
</div>

The "containingbox" class makes sure that the top of the image starts at the top of the block of text. Next, add a line after the first DIV tag, but before the start of the text. This is the line where your actual image will go, same ![image] mark-up we've already used, but with DIV tags around the image:

<div class="containingbox">
<div class="floatleft">![lantern]</div>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aufidio,
praetorio, erudito homine, oculis capto, saepe audiebam, cum se
lucis magis quam utilitatis desiderio moveri diceret. Hoc est dicere:
Non reprehenderem asotos, si non essent asoti. Duo Reges: constructio
interrete. Is ita vivebat, ut nulla tam exquisita posset inveniri
voluptas, qua non abundaret. Quid ergo aliud intellegetur nisi uti
ne quae pars naturae neglegatur? Is ita vivebat, ut nulla tam
exquisita posset inveniri voluptas, qua non abundaret. Sin laboramus,
quis est, qui alienae modum statuat industriae? Ex quo intellegitur
officium medium quiddam esse, quod neque in bonis ponatur neque in
contrariis. Sed est forma eius disciplinae, sicut fere ceterarum,
triplex: una pars est naturae, disserendi altera, vivendi tertia.
</div>

The image is contained in its own DIV box, which the text flows around. The "floatleft" class moves the image to the left margin of the containing box, so that the text in the containing box will flow along the image's right-hand side. Use "floatright" instead when you want an image on the right margin, with text flowing along the image's left-hand side.

Fixing the Filter

To convert our document, we're going to need to change the filter we've been using in TED Notepad. If you select Tools > Text Filters > Manage List.. from the menu, you can select your filter that creates a full web page and then click Edit. Change the filter command to:

pandoc --standalone -B \proj\%1 -o \proj\%2.html %F

What this does:

• the --standalone option just makes this a full web page, instead of just an HTML fragment.
• the -B option tells Pandoc what to insert Before the main body of the text. This file is inserted verbatim (in other words, it's not in Markdown format, but in this case is full HTML.)
• the \proj\%1 is the name of the file to insert. When you run the filter, you will change the %1 to something like std\wrap.txt, which will insert \proj\std\wrap.txt in after the header, but before the text in the body of your web page.
• -o \proj\%2.html is your output file, in HTML format.
• %F is the currently open file. Note that TED Notepad will save changes to your file before running the filter.

This command line is more complex than what we were using before. It has the potential to get even more complex, since there are many other options we haven't even looked at. However, I'm not tricking you into learning complex command-line syntax; I have a plan to simplify this later.

I'll cover wrapping text around an image in a PDF in a later installment of the tutorial.