ubuntu-manual team mailing list archive

[Kevin Godby <godbyk@xxxxxxxxx>]

Hello, all.

I took some of the screenshots that ubuntujenkins gave me (at 1024 x
768) and added them to the manual with the new \screenshot command.
You can take a look at the result:

  http://kevin.godby.org/private/ubuntu-manual/ubuntu-manual.pdf

(See pages 24, 70, 76, 80, 88, and 94.)

I've got a few things to tidy up still, but it gives you the basic
idea of how they'll look.

Here's a bit about how to use the new \screenshot command.

  \screenshot{screenshot-file.png}{ss:screenshot-label}{This is the
caption text for the screenshot.}

The first argument is the name of the screenshot graphic file (in PNG format).

The second argument is the label.  The label should be prefixed with
"ss:" (for screenshot).  This is used in cross-referencing.  For
instance, "See screenshot \ref{ss:screenshot-label} for an example
screenshot." would produce: "See screenshot 2.3 for an example
screenshot." if it's the third screenshot in the second chapter. If we
end up cross-referencing screenshots a lot, I can make a
\screenshotlink command similar to the \chaplink command.

Finally, the third argument is the text that goes in the caption.  The
caption should not just describe the screenshot itself, but tell the
user something about what they can do with the application depicted.
For instance, "The F-Spot main window." is a rather boring caption. A
slightly better caption would be: "F-Spot let's you store, tag, and
edit your photos."  The screenshots will be eye-catching, so the
captions should invite the reader to learn more about the application
show.

For those who like to know how things work, here are some of the
behind-the-scenes details on the \screenshot command.

All of the screenshots are stored in the screenshots/LANG/ directory
(where LANG is the language code for your translation).  LaTeX doesn't
really care about the resolution, but all the screenshots should be
taken at the same resolution so that they're scaled equally.  The
screenshots in the example PDF linked above were taken at 1024 x 768.
The files can be named anything, but should not contain spaces or
funky characters.

To make sure that all of the screenshots are scaled equally, instead
of being stretched to fit the text width, we need to know what the
widest screenshot is.  We use the \setmaxscreenshot command to point
to the filename of the widest screenshot (which would be 1024 pixels
wide, in this instance).  The \setmaxscreenshot command takes that
screenshot and figures out what scaling factor must be used to get it
to fit onto the page (allowing the image to take up the main text
block width and the sidenote area width).  This scaling factor is
stored and applied to all of the screenshots throughout the manual.

When the \screenshot command is called, LaTeX looks at the width of
the screenshot and scales it using the scaling factor.  If the scaled
width is less than the main text block width, then we'll put the
screenshot in the text block area and put its caption alongside it in
the sidenote area.  If the scaled width is greater than the text block
width, then we'll let the screenshot use the full text block width
plus the sidenote area width and put the caption below the screenshot.

--Kevin