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 | +--------------------+ _______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : kicad-developers@lists.launchpad.net Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
