Marco, Great work on the conversion analysis. I finally go around to testing this and I have to say that I prefer the asciidoc format better than the markdown and rst formats for plain text readability. I also could not convert the asciidoc format to pdf using your example. I always get an error about dblatex failing even though I have it installed on my Debian partition. None of the section headers or table of contents were converted so there would obviously be some hand work involved. That's not a big deal for the cvpcb documentation but for all of the documentation there is a lot of work to do. Windows support is iffy. Even though MSYS2 has an asciidoc package, the optional bits to create pdfs is missing so that is an issue.
I guess the next steps are: * Make the final decision on the format. * Pick a VCS and a host server. Obvious choices are bzr/launchpad and git/github. * Convert all of the documentation over to asciidoc. * Write CMake build configuration support to handle dependency checking, out building, translation file creation, and installation. * Create initial repo and let the document fixing begin. Any volunteers? Wayne On 10/21/2014 5:58 PM, Marco Ciampa 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. > _______________________________________________ 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