ubuntu-developer-manual team mailing list archive

[Kyle Nitzsche <kyle.nitzsche@xxxxxxxxxxxxx>]

Kevin,

Excellent description. Thank you. In particular, for elucidating the LaTeX 
commands and capabilities regarding what I had called the image 'URI' and how 
LaTeX itself can search multiple locations to obtain the localized images, and 
fall back to English (if desired).

In general now, I am thinking a hybrid approach may work well.

My lang_pdfs bash script (emailed earlier but not committed) does indeed create 
& update the locale branches for localized images for current LINGUAS.

As you noted you mentioned, splitting into branches saves a lot of unnecessary 
download time for authors.

However my latest email, which has the new Makefile target to create a temporary 
directory (images/) for each lingua may not be needed since it appears LaTeX can 
be told where to look on each language 'run', and to fall back to English.

So, do you agree so far?

Another important area: are authors responsible for delivering screenshots?

I propose that Authors create the all their screenshots (knowing they will be 
replaced by uniform ones made by Quickshot).
For several reasons:
 * get it done now, during content creation, even if imperfect
 * my gut tells me it can be difficult to describe a screen shot sufficiently 
for someone else to make it. When the author needs to convey a very particular 
point, they may work a dialog into a particular state, or a terminal, or 
whatever, and that state is necessary to convey the point, and may be difficult 
to reproduce.

But, the screenshot.log (for missing screenshots) sounds GREAT. So I am 
wondering whether we can combine both approaches:
 * Author adds their screenshot (to en-images branch)
 * Author adds \screenshot{filename}{label}{caption}, so their (draft) 
screenshot DOES appear
 * Author *also* adds \screenshotTODO command, so the "missing" shots log is 
created and quickshot people know what to do. And they can use the draft PDF to 
*see* the precise screenshot desired.
 * Modify \screenshotTODO function so that it DOES NOT display the "MISSING 
screenshot box'.

This way we get screenshots NOW in English, even if all else fails.
We get a listing of ones that have not been made properly for quickshot and 
localization.
No ugly "Missing" BOX.

Thoughts?

I am not sure how the work is tracked for obtaining all screenshots for all 
target languages in ubuntu manual. I register that you mentioned the project 
file. I presume quickshot has process to iterate that for every target lingua 
and track missing screenshots and ones that need to be updated (cause the 
English one was modified)?

Lastly, I prefer to fallback to English screenshot if the localized one is not 
present. I think that would be unfortunate but far preferable to "Missing" box 
because the user may still find it useful, even if they can't read the text (and 
it's less ugly).

Cheers,
Kyle

On 01/07/2011 03:30 PM, Kevin Godby wrote:
> 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