kicad-developers team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxx>]

On Mon, Sep 01, 2014 at 09:54:21PM +0100, Brian Sidebotham wrote:
[...]
> Latex I'm sure is definitely
> out - it's hard to see the content for the formatting, so it's not
> easy to work with.

Most of all, it is really hard to _automatically_ (I do not know of a
tool that is able to do it) extract chapters to create .po file to help 
maintain automated internationalization of the documentation.

> We want to create a situation where documentation
> writers can use text diffs to update their language's documentation.

_THIS_ is what I meant! Using one of these tools:

 * xml2po (to use with docbook-xml)
 * publican (better) - please - take a look at this wonderful tool
   https://fedorahosted.org/publican/
 * ... there must be other tools out there ... (markdown + po4a?)

> So something like restructured text may work well because it has some
> image formatting capabilities.
>
> Plain HTML can actually do the job too, although most people use a
> language that compiles to html to make the formatting even cleaner.
>
> Markdown has books written in it too.

Well markdown is wonderful and so is docbook-xml (although slightly
harder to write) and using tools like pandoc
(http://johnmacfarlane.net/pandoc/), for example, it is easy to create
automatically HTML, PDF, ODT, EPUB(!) or even DOC(X) (gosh!) files.

This is all good to write single language (english) doc.

For writing manageable internationalized docs we have create (or use a
specialized tool in) an automated chain like this:

1) write template doc (english) in (for example) docbook-xml 

(use the xml editor that you wish: emacs, gedit, eclipse, vi

2) use a tool to check structure validity of the template source file

(some editors like emacs and eclipse are able to check xml validity as
you type...)

command: make validate

3) automatically extract all chapters from the template xml source
file(s) creating a/some .pot file(s) for every language (typically the
list of languages are in the LINGUAS file)

command: make pot
command: make po-NN
 where NN is the language code

4) eventually update the existing .po file(s) with new strings, fuzzying
changed strings, and obsolete old strings. This is done through standard
gettext utility commands like msgmrg ...

command: make status-NN 

5) merge template file with .po files to create many nationalized xml
files, one for language

command: make xml-NN

6) create the output file as you like:

command: make html-NN
command: make pdf-NN
command: make odt-NN

 ----------

The advantages are:

1) In this way, doc authors and doc translators are completely
indipendent from each other. Doc authors can make changes in doc anytime
and those changes propagate automatically to all the languages.

2) A really nice side effect is that if a chapter is missing or obsolete,
doc default automatically to english, so the book is always complete,
even if not completely translated.

3) To translate, translators do not have to know docbook-xml sintax since
they work always with .po files using standard gettext tools like poedit

4) web translation platforms are possible / enabled (like launchpad web
translation support) through standard .po files

5) using HTML as standard output format it is possible (in the future) 
to enable even context sensitive help like is already done in the GIMP

PS: in the examples above, those are the actual commands used to build
the GIMP multilanguage documentation.

PPS: forgive my bad english.

-- 


Marco Ciampa

I know a joke about UDP, but you might not get it.

+--------------------+
| Linux User  #78271 |
| FSFE fellow   #364 |
+--------------------+