ubuntu-developer-manual team mailing list archive

[Kevin Godby <godbyk@xxxxxxxxx>]

Greetings.

On Fri, Jan 7, 2011 at 3:17 PM, Kyle Nitzsche
<kyle.nitzsche@xxxxxxxxxxxxx> wrote:
> 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?

Yes, I think so.  Before you dash off and create a slew of bzr
branches for screenshots, however, please check with the Quickshot
devs.  I know that at one point they were discussing storing the
uploaded screenshots in bzr branches.  I don't know if they're doing
that now or not, so you'll have to contact them and see.  If they are,
we can just pull those branches instead of maintaining copies all over
the place.

> 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.

I think this is fine.

> 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)

I'd recommend we store those screenshots in a draft-images folder
instead of en-images.  That way en-images can be the final set of
English images instead of a mix of draft and final.  (Final being
those generated by Quickshot.)

>  * Author adds \screenshot{filename}{label}{caption}, so their (draft)
> screenshot DOES appear

This is fine.  The filenames of the images should be the same
regardless of the language—that is, the filenames are *not*
translated.

>  * 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.

This is unnecessary as the \screenshot command can be modified to emit
the screenshots.log file itself.

>  * Modify \screenshotTODO function so that it DOES NOT display the "MISSING
> screenshot box'.

I disagree with this, but I think we may be talking about two separate
stages of the process.  I'll explain more below.

> 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)?

The images taken by Quickshot are uploaded to the Quickshot server.
The server has a web interface that shows you the progress (number of
screenshots taken) on a per language per project basis.  The old
Quickshot server interface can be seen here:
http://screenshots.ubuntu-manual.org/.  The new server has a better
interface, supports multiple projects, and other whiz-bang features.

> 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).

During the writing and editing process, I suggest that we leave the
ugly MISSING SCREENSHOTS boxes in.  These notices are not for the
reader of the manual, but for the authors, editors, translators, etc.
so they can see at glance that some screenshots still need to be
taken.  This has the desired effect that, to get rid of the ugliness,
someone will take a few minutes to take the required screenshots.  If
we use the draft screenshots instead, the editors, translators, etc.
may overlook the fact that the screenshots haven't been translated and
this increases the likelihood of having an incomplete translated
edition.

If we get the the point that the entire book has been translated and
no one can be bothered to collect the remaining missing screenshots,
then we can easily instruct LaTeX to use the English screenshots
instead and proceed with publishing the translated edition.  This
should be seen as a fallback position, however, and heavily
discouraged.  I believe that each translated edition should stand on
its own and be of the same high quality as the original English
edition.  We should do all we can to improve the quality of the
translated editions.

--Kevin