kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxxxx>]

On 9/1/2014 8:03 PM, Marco Ciampa wrote:
> 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,

Thank you for stepping up to help fix our documentation.  It's obvious
from you detailed description that you have an excellent understanding
of the issues.  Here are the steps I would like to see you take to move
forward:

1) Choose a format that meets the documentation requirements and
satisfies the platform availability requirements that I've already
commented on.  I'm comfortable with DocBook and mark down so I'll leave
the details up to you and the folks doing most of the documentation work.

2) Create you own branch of lp:~kicad-developers/kicad/doc, convert one
of the smaller user guides (cvpcb) to the new format (preferably in a
new folder), and update the CMake files to check if the required tools
are installed and the necessary make commands to build the html (at a
minimum) documentation.  Once you have this working, push your branch to
launchpad so other developers can test your changes.

3) Once other developers have had a chance to test your changes and we
have a consensus that this is the way to go, convert the remaining
documentation to the new format and commit the changes to
lp:~kicad-developers/kicad/doc.

4) When all the documentation is converted to the new format, remove the
legacy odt files from the repo.

5) Add the CMake code to build the translation po files and any
additional output formats we want to support.

There is a lot of work to be done to make this happen so let's support
Marco as best we can.

Cheers,

Wayne