ubuntu-developer-manual team mailing list archive

[Kevin Godby <godbyk@xxxxxxxxx>]

Hello.

Here's a quick run-down of how we handled it with the Ubuntu Manual project.

Everyone used the \screenshotTODO{A nice, detailed description of the
screenshot.} command.  In addition to inserting the MISSING SCREENSHOT
notices (which are there primarily to give us a rough idea of how long
the book may run after screenshots have been inserted), a
screenshots.log file is generated that lists the chapter number, page
number, and description of the screenshots required.  This
screenshots.log file is passed on to the Quickshot folks who use it to
produce a configuration/project file for Quickshot.

The screenshots were stored in a screenshots/LANGCODE subdirectory in
the same branch as the .tex files, though we've been discussing
splitting them up into their own branches.  I think this is probably a
good idea as it saves time for new authors and editors downloading the
.tex branch.  (No one really wants to have to download a ton of
screenshots in a language they don't speak.)

After we've collected the US English screenshots (which go in the
screenshots/en/ directory), we switched the \screenshotTODO{} commands
to use the \screenshot command.  The syntax of this command is:

  \screenshot{filename}{label}{caption}

An example (with a rather poor caption):

  \screenshot{08-display-properties-confirm.png}{ss:08-display-properties-confirm}{You
can revert back to your old settings if you need to.}

Behind the scenes, the \screenshot command does the following:

1. Checks to see if screenshots/LANGCODE/filename exists.  If it does,
it scales the image using the universal scaling factor (more on this
in a moment), and inserts it, the caption, and the label (used for
cross-referencing) as a floating figure.

2. If screenshots/LANGCODE/filename does not exist, it inserts the
MISSING SCREENSHOT box like you've seen in the current PDF.  This is
because we want to know if a screenshot hasn't been taken yet and we
don't want to accidentally overlook it because a non-translated
screenshot was there.  In the final release version, it would be easy
to tweak the code to fall back on the English screenshot instead, but
I wouldn't suggest doing this unless you really need to get the
translated version published and don't particularly care about the
screenshots.

Now, about the universal scaling factor mentioned above.  All of the
screenshots should be taken at the same resolution.  The widest
screenshot needs to be scaled to fit the text block of the page.  We
specify the widest screenshot using the
\setmaxscreenshot{path/and/filename} command.  This command notes the
width of the image and calculate the scaling factor to be used with
all the screenshots.

The label is used for cross-referencing.  You could say, for instance,
"Figure~\ref{ss:08-display-properties-confirm} shows the Display
Properties confirmation dialog." and the
\ref{ss:08-display-properties-confirm} would be replaced with the
appropriate figure number.

If you want to write a script that checks out the appropriate branch
of screenshots and symlinks the directory (or checks out the branch in
place or whatever is best), then I think that's a good idea.

I wouldn't bother copying screenshots from the English directory to
the translated directory as LaTeX can look in both places for us
behind the scenes if need be.

I would also suggest contacting the Quickshot developers
(https://launchpad.net/~quickshotdevs) to see if/how Quickshot can be
configured to work with your proposed workflow.

--Kevin