Layout Tutorial: 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.

Here's Part 5.

Layout Tutorial 5: Including Graphics

What we've been discussing so far have been simple projects: a blog post or webpage, a house rules document, a quick draft ebook or PDF. We haven't been discussing the more complex projects: semi-pro products for submission to zines or self-publication. When we get to the topic of graphics, we're at the transition point from simple project to complex projects. There are a couple uses for graphics in simple projects, which we can cover in this installment.

Let's say you're going to give your players a printed handout about the starting area for a new campaign. You want to list important names they would know, notes on prices and availability, and provide a quick map of the immediate area. You might also throw it up on a web page, to tell others about your campaign. You have a map in digital format.

Image Formats

First: make sure that the map is in either PNG or JPEG format. Technically, Pandoc doesn't know crap about image formats and will happily try to include anything you tell it to include as an image. The problem is that the three final products we're talking about -- web page, EPUB, and PDF/print -- have different expectations. It's the web browser or ereader that figures out how to display the listed image. It's the LaTeX engine that figures out how to insert a graphic into a PDF. They do not all allow the same kinds of image files. This is part of the reason why graphics mark the transition from simple projects to complex projects: if you try to step outside some very narrow boundaries, your document will not include all the graphics in both the web/ebook version and the PDF/print version.

For simple documents, PNG and JPEG will work in all output formats. PNG is best for cartoons, line drawings, and simple shading and color; JPEG is best for photographs and finely-shaded illustrations with a wide range of colors. Unless you have a photorealistic relief or overhead map, you will probably be using PNG for your map.

If your map is not in PNG format, you can use a program like The GIMP or Photoshop to convert it. I know a lot of people still use MS Paintbrush, but I haven't used that in a long time; I think by default it works with PCX format, which will need to be converted, but it probably can covert to PNG. I'm willing to bet that Hexographer, another popular tool for the RPG crowd, can save images in PNG.
You may also need to scale your image to 72 dpi, which is good for web pages and bearable in PDF or print for something that isn't meant to be widely distributed.

Move or copy your map to \proj\map\, once it's converted.

Including Images

It turns out that including a PNG or JPEG image isn't very hard to set up in Markdown. Remember the format for links?

Here is a [link].

[link]: http://somepage.com/

The [link] in the main text is the word that is turned into a hyperlink. The second line show the URL that the link references.

The image format is pretty much the same:

The Local Campaign
==================

![map]

Pictured in the map are the East Region,
the West Region, and the Middle Region.

[map]: /proj/map/localmap.png

The reference part is exactly the same: a path pointing to the location of the image. It can be a location on the web, if you are using something from WikiCommons or something like that. For a blog or a web page, it has to be a reference to an absolute URL or a relative location. For EPUB or PDF, the image is included in the final product, so we can just link to the location of the file on the hard drive or other local storage. Even on a Windows machine, though, it has to be forward slashes, not back slashes.

The difference between a regular link and an image is the exclamation mark in front of the link where it is supposed to appear in the text. ![map], in this case, tells us that our map will appear below the title ("The Local Campaign") and above the text describing the map. The word "map" in the link will appear in web pages as the "ALT text" that appears if the browser doesn't support images.

You can expand this by adding a title attribute. On some web pages, if you hover the mouse cursor over an image, a small rectangle will pop up with a description of the image. This "flyover text" is stored in a TITLE="foo" attribute added to the HTML code for the image. The web comic xkcd famously uses very long titles to make an extra joke or two about the topic of each strip. In the above example, we can add a title or flyover to our image by including the text in quotes or parentheses after the location of the image, like this:

[map]: /proj/map/localmap.png "Pictured in the map are the East Region,
       the West Region, and the Middle Region."

(Actually, you can do this to ordinary links as well, as I have to the xkcd link.)

Images with Captions

I didn't include a display example for the above Markdown code because Blogger is a little different in the way it wants you to upload images. So let's change our example to use a map I've already uploaded to Blogger.

![Map of Goskold]

The starting location for this campaign is Goskold,
a town in the principality of Pexequick.

[Map of Goskold]:     https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiU8aw63jPtC_LSnEA-74qXwgLGm30qdgMElFU78OdHxME50P5sQdVVvTX5QeDxbuF62AiiHB51ClZFHFdCRPhIf0StiAwQH5S019518y3dg8Ozonbad1XWU-5_z1xHALRJtKlxpuSPK9et/s320/hex_LMH2cu.png

(That horrible long thing is a typical Blogger image URL.)

Here's the result:

Map of Goskold

The starting location for this campaign is Goskold, a town in the principality of Pexequick.

You will notice that "Map of Goskold" appears below the image as a caption. The PDF output will also have a caption (although not with this example; that web URL seems to produce an error message when sent to pdflatex.) The image will be centered horizontally, and the caption will read "Fig. 1: Map of Goskold". If you have more than one image, MiKTeX or whatever pdflatex installation you are using will adjust the figure numbers accordingly.

The caption is taken from the link text. Any image that is in a line by itself will have a caption (and will be treated as a figure in LaTeX.) If you don't want a caption, you need to add something after the image, in the same line, such as:

![Map of Goskold]\

(The backslash at the end of the line, you may remember, includes a line break.)

Inline Images

If you have a small image (no higher than 1/6th of an inch, for 12 point fonts,) you can use it as an inline image. For example, you can start a paragraph about weapons available in a town with an image of a horizontal dagger. You do that by simply including the the image link in the same line as the text:

![weapons in town] You can find the following weapons in the local marketplace...

[weapons in town]: /proj/icon/dagger.png "Weapons Available in Town"

The reason why I specify the 1/6th of an inch height for the image is because the text will not wrap around the image. It will start at the baseline of the image, lining up with the bottom, and will have a blank horizontal space to the right of the image from the image top to the top of the text. 12-point type is 1/6th of an inch tall (more or less,) so an image 1/6th of an inch high will not create an unsightly gap in your text. It will be an even better fit if the image is shorter. It must be shorter if you use a smaller font (11 point or 10 point.) You could use a slightly taller image if the text is larger, for example with a large header.

You will notice that the supposed location of my dagger image is in the \proj\icon\ folder. I suggested this (back in Part 1) for exactly this kind of thing: replacement icons for bullet points, or icons to mark special sections of text.

Why can't we make the text wrap around the image? That's something I'll address in Part 6.