ubuntu-developer-manual team mailing list archive

[Kyle Nitzsche <kyle.nitzsche@xxxxxxxxxxxxx>]

During last night's bought of insomnia (extremely rare for me, but so be it ;), 
my mind crawled through the question of supporting  localized images for the 
ubuntu developer guide, which resulted in this proposal. We need a maximally 
simple solution that just works and produces excellent results. And I think we 
need it now because authors should be creating the initial screenshots, and they 
need to know how.

This proposal leverages Quickshot but diverges from the "TODO" work flow in the 
Ubuntu Manual Style guide. This proposal follows work I did implementing 
localization of images in PDFs for Doctemplate project and for the Ubuntu 
Desktop Course.

The simple description is: For each PDF build, auto-create an images/ dir that 
contains the layered images (English first, with the localized ones copied in to 
preempt)

The rest is an enumeration of this.

Goals:
 * PDFs automatically built with localized images where possible but fall back 
to non-localized (English) as necessary
 * Images taken in common theme and resolution (Quickshot magic)
 * Minimal impact on authors: they develop in English and take English 
screenshots (to be replaced via Quickshot)
 * Unlocalized image URIs in source LaTeX files. That is, source files don't 
need to know anything about localized image paths
 * Images stored in separate branches, one per lingua
 * As with translations, trunk/LINGUAS file controls current set of linguas 
(which allows extra, unused images branches and translations, and a build-time 
control switch)

Tools:
 * Quickshot to produce localized images
 * bzr: a branch for each lingua named: 
lp:~ubuntu-developer-manual/ubuntu-developer-manual/<lingua>-images
 * lang_pdfs script (which builds localized pdfs) to branch/pull image branches 
for valid linguas in LINGUAS file
 * Makefile to create localized images/ dir from images branches as needed (see 
below)

Working Layout:
Trunk directory is sibling to image branch directories:
root/
 - ubuntu-developer-manual/<chapter>/<tex-file-with-image-URIs>
 - images/ (Note, this is CREATED and DESTROYED automatically as needed. It is 
not pushed to LP. See below)
 - en-images/ (This is the master set of current images, in English)
 - pt-BR-images/ (This is the pt_BR images. It is created by Quickshot. It can 
be incomplete.)
 - de-images/ (Another sample localized image directory)

Image URI example: ../../../images/MyImage
 * That ^^^ shows that tex files point to one unlocalized directory that 
contains image files with unlocalized filenames
 * This keeps things maximally simple for authors

images/ Directory:
 * This is always the working images directory by and for a pdf build
 * It is not persistent (is not a branch)
 * Its contents are created at PDF build time as follows:
   - lang_pdfs script (localized builds only): updates <lingua>-images branches 
for each lingua in LINGUAS file
   - Makefile: cp en-images to images/ (This establishes en-images as the 
default images)
   - Makefile, for localized PDF builds, cp <lingua>-images/* images/ (This 
replaces en-images/ files with whatever localized images exist)
 * Thus, if a localized image is available, it is used, else fall back to en image
 * All image directories are flat. (They do not have chapter subdirs, which 
facilitates chapter reorganizations)

Author work flow:
 * Author needs two branches:
   - trunk
   - en-images
 * Author adds screenshot files for their content to en-images/
 * Author adds URI o text file as noted about
 * Author creates English pdf with 'make' command. (Makefile defaults to 
LANG=en, thus it creates images/ from en-images/ only.)

PDF Builder work flow:
 * Branches needed
   - trunk
   - (Note, lang_pdfs script will automatically branch or pull all localized 
images branches for linguas in LINGUAS file.)
 * Create all pdfs with ./lang_pdfs

Quickshot work flow: (OK, so I am waving my hands here, so lets think of it more 
as Quickshot Responsibilities)
 * use en-images as the base set of images
 * in en-images, replace author created images with Quickshot ones (* see 
discussion point below)
 * Create/update <lingua>-images/* based on images in en-images

Discussion:
 * Since authors put screenshots into en-images branch, they don't all have the 
normative dpi and theme (such as those provided by Quickshot do). So, should 
there be a dev-images branch for author images and en-images is created and 
managed solely by Quickshot, in the same way all other localized image branches 
are?
 * en-images is THE definitive set of current images. It should not contain 
extra images, authors should do this. A simple script can grep text files for 
image file names to identify images that are no longer used.

Implementation:
 * I think I could get this implemented pretty quickly (a day?).
 * Does this fit with Quickshot?
 * Are there reasons not to move on this directly?

Cheers,
Kyle