kicad-developers team mailing list archive

[Brian Sidebotham <brian.sidebotham@xxxxxxxxx>]

On 21 October 2014 22:58, Marco Ciampa <ciampix@xxxxxxxxx> wrote:
> Hello,
>
> talking about the project of switching the KiCad documentation to an
> easier to maintain and translate format, after some experiments, (I know,
> I am slow ... I am not a real programmer) I have produced something
> to check.
>
> This is in effect something like an RFC: I need your comments,
> suggestions, improvements (and patches are welcome).
>
> I started writing an email, this:
>
> https://github.com/ciampix/kicad-doc/blob/master/doc/kicad-doc-doc.adoc
>
> it got bigger and bigger and it is not finished, but I though that it
> could be useful to publish it before being closed because I do not want
> to write it all alone.
>
> Along with this text there are two dirs in src: asciidoc and rest.
> Basically these folders contain the cvpcb manual converted into asciidoc
> and rest and the small example scripts to create docs into html/pdf/epub.
>
> The complete cycle is:
>
> (odt->)asciidoc/rest
> ->translation extraction
> ->(translation)
> ->merge->nationalized pdf/html/epub
>
> The examples are in asciidoc and rest but the asciidoc toolchain is
> almost the same for markdown. I have reported some comments about
> txt2tags, textile and sisu but I do not have studied these tools enough
> to have a clear idea about.
>
> So I ask you to:
>
>  - have a say about the work
>  - try my examples
>  - express your preferences about:
>
>   a. the documentation text format
>   b. the data organization of the manuals, in particular:
>    - file name/extension conventions
>    - source files folders,
>    - image folders
>    - makefiles/cmake configuration (I do not know anything about cmake...)
>    - any other thing
>
> If you have any doubt or problem about anything please express yourself.
>
> I do not think we are in a hurry so I think that we can our time to
> decide and clear out any quandary.
>
> When we will have decided the source text format we will start converting
> all the manuals. Please bear in mind that *anything written in a foreign
> language that is not strictly adherent to the english reference manual
> will have to be removed*.
>
> So, if you think that something you have written in a localized manual is
> not present in the reference, try to translate it in English for the
> inclusion in the reference: doing this may save your translation and give
> a hand to the whole project.
>
> PS: ... and please forgive my terrible English.
>
> --
>
>
> Marco Ciampa

Excellent work Marco, firstly your English is not terrible, my Italian is!

Thank-you for doing a thorough job in looking at the various tools
available and it's great to have the view of a translator looking from
the ease of internationalising a document properly as that's not an
easy task.

I've managed to read most of your document and everything looks sound
to me, I agree with your conclusions, but then I use asciidoc every
day of the week, so it's easy for me to agree with! At least, asciidoc
is not very intrusive into the text of the document, it is
light-weight.

I was worried that po4a was not available on Windows, but it appears
it's pretty easy to get going on windows. I'm sure the rest of the
toolchain is easy to get running on Windows. See some information here
with regards to po4a on windows:
http://ehc.ac/p/ourorgan/svn/754/tree//trunk/HOWTO-build-help-on-Windows

I'm excited for us to move to a text based documentation format as
soon as possible.

I imagine our workflow after we've decided on the markup source format
needs to be:

(1) Convert odt to text-based markup
(2) Get a document writer (could be a current dev(s)) to go through
the manuals and tidy up grammar, out-of-date screenshots, layout
issues, etc.
(3) Make sure the documentation build process is documented (which
you've already done an excellent job starting, thanks!!)
(4) Create the po files ready for translation and that should lead to
translators being able to start translating the new manuals.

The fact that everything, including images drops back to the master
English version if there's not a specific language version is
absolutely excellent.

Before reading your article I was pro-Markdown as the solution we
should use, but I am very convinced by your extensive work around the
translation of the documentation and I understand the limitations of
Markdown, so asciidoc is a fine conclusion to me.

Thanks again for the update and hard work!!

Best Regards,

Brian.