live-manual: Building translated manuals individually

[chals <chals@chalsattack.com>]

The question is:

Are live-manual makefiles flexible enough to build translated manuals
by language (one at a time)?

The answer is:

Absolutely yes! (With capital letters)

I usually work with several languages at the same time, that is why I
tend to favour the recommended translation workflow, but I can
perfectly understand that some translators may be reluctant to use the
"commit" target and regenerate all the manuals in one go. They
logically would prefer to only deal with their language. The one they
are working with.

Once upon a time, we were talking about this on the irc channel and
Daniel told us to use the "rebuild" target to achieve that goal. I do
not remember the exact details of that conversation but I do remember
that I tested it very thoroughly to see if the makefiles needed any
additional tweak to build one language at a time. I do not even know
whether the rebuild target was created with that aim in mind. But the
makefiles work fine without any modification. (This does not mean that
they cannot be improved. Any change for the better is always good.)

 I am writing this message because some newcomers may not be aware of
this. I'm using German "de" as an example. The procedure could be as
follows:

You translate manual/po/de/about_manual.ssi.po and you want to update
the German translation but "only" the German translation. Then you
type:

 $ make -C manual rebuild LANGUAGES=de

This command will do three things:

1.- Clean the git tree as necessary.

2.- Update the dates. This is a must, the dates show when live-manual
is published and it is published after any change is made.

3.- Build the language that you have specified. In this case it was LANGUAGES=de

Now there are several files ready to be staged and pushed. I make a
separate commit for the dates, so that other changes are easier to be
reviewed by others. And besides, the dates are a change on their own.

To add the dates:

 $ git add manual/*/live-manual.* manual/po/*/live-manual.*
 $ git commit -m "Updating the dates in live-manual files."

Then you can add the translation files you have created. In this case
they would be:

manual/po/de/about_manual.ssi.po
manual/de/about_manual.ssi

So:

 $ git add manual/po/de/about_manual.ssi.po manual/de/about_manual.ssi
 $ git commit -m "Updating German translation of about_manual."

And simply discard the changes to the po4a.cfg file. It is, after all,
a disposable configuration file. If anyone is interested in adopting
this workflow. It should be trivial to ignore the changes to that
file.

Now:

 $ git push

Why is this *not* the recommended procedure?

Because it skips the test target, which in turn performs a bulletproof
.po integrity check. However, this could be performed manually by
running the check target. i.e "make check".

I hope this information is useful. Have a lovely day :)



-- 
chals
www.chalsattack.com
chals@chalsattack.com