ubuntu-developer-manual team mailing list archive

[Kyle Nitzsche <kyle.nitzsche@xxxxxxxxxxxxx>]

Hi.

On 01/07/2011 05:26 PM, Kevin Godby wrote:
> 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.
I'll contact them (who are they? ;)
>   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's fine. LaTeX will need to look there, naturally. perhaps the 
(final/production) LaTeX search order should be:
 * localized branch (<linguas>-images)
 * en-images
 * draft-images

(I am agnostic on naming dir convention: lingua-images or images-lingua. I 
selected the former to ease terminal navigation, but that is, as you noted at 
the cost of a directory listing that is not so neat.)

> 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.
ack. this should be done perhaps has a first order of business since writing 
needs to happen now.
> >   * 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.
nice!
> > 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.
agreed
> 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