kicad-developers team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxx>]

On Wed, Sep 03, 2014 at 10:28:09AM -0400, Wayne Stambaugh wrote:
> 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.

I _have_ to be honest.

I actually do not know the inner workings of all this chain.

I am mainly a translator, not a programmer, but I am not completely
unaware of programming though.

I do not know at all Cmake and just basic commands (before using Kicad
never had any occasion to use) bazaar and merely I know what is
docbook-xml, just used it as a doc writer.

Anyway, so many years are now that I have taken the burden to maintain
the translation updated of some free software projects, that I think I
know now very well (as a translator) what have to be done.

So, even though I haven't build up this mechanism myself, I have used it
so much that I can imagine how it should be working underneath and maybe
(I hope) I should be able to build up one for kicad. This could be the
bigger effort I ever done to some free software project and I am eager
and, to be honest, a little afraid to do it at the same time.

So this is not "do it for me" but instead, "yes, I will do it by myself
... with a little help from my friends"

SO please, be patient with me because I am not young chronologically (I
am 48) but in this case I feel like a young newbie (do not laugh at me,
please) and I do not want to do it all by myself but I will be glad if
someone would like join me in this effort.

> 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.

I would really like to discuss about this, the text source format to
choose, with someone or just here in the list, if you do not mind I
clutter the list with such mundane discussions. I would really like to
have some other opinion because I am not really sure about it and I do
want to avoid big mistakes especially at this early stage.

In particular, I really like the semplicity and elegance of markdown but
I do not know if the tools previously mentioned (maybe po4a? or something
other?) are able or suitable to extract the text paragraphs and then
re-merge translated. With docbook-xml format I am sure that with xml2po or
publican I can do it. So for me, docbook-xml could be the first choice if
it does not jump out any way to manage the extraction and reintegration
of translated strings in markdown.

> 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.

Ok.

> 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.

Ok.

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

Ok.

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

Since IMHO this is the most important feature and reason for the change
of the whole doc project, I think it would be better if it was done (or
just checked) before point 3)

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

I really count on this.
Just it will not so quick, so do not hold your breath! ;-)

Many thanks for the opportunity and for the trust you place in me,
hope it is not misplaced.

-- 


Marco Ciampa

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

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