2015-02-09 12:01 GMT+01:00 Marco Ciampa <ciam...@libero.it>: > On Mon, Feb 09, 2015 at 10:09:04AM +0000, Brian Sidebotham wrote: >> On 7 February 2015 at 00:09, Marco Ciampa <ciam...@libero.it> wrote: >> > On Sat, Feb 07, 2015 at 09:56:36AM +1100, Cirilo Bernardo wrote: >> >> What a nuisance that po4a does not recognize "include". Maybe we should >> >> submit a patch to po4a? >> > >> > That would be the best thing to do. >> > >> >> Otherwise my own preference would be to continue to use individual text >> >> files for chapters and to use other tools to glue them together before >> >> invoking asciidoc. >> > >> > I think that that would resolve the problem in the meantime that po4a devs >> > patch the program. >> > >> > That would be the simpler thing to do, but we could have to introduce the >> > convention of, for example, call the docs with include directive in it >> > docname-master.adoc to obtain a "fusion" of >> > docname_master.adoc+docname_chapter_01.adoc+docname_chapter_02.adoc... >> > into ->docname.adoc >> > >> > nevermind... I've already resolved with some makefile+scripting+sed magic >> > :-) pushing it in a few minutes... >> > >> > We just have to follow the convention of calling the chapters >> > >> > DOCNAME_chapter_NN.adoc >> > >> > etc. as we already do. >> > >> >> UNIX systems usually have several tools installed >> >> which can do the job of stringing the files together (even most shell >> >> environments have such built-in facilities). MinGW/MSys would also have >> >> such facilities. >> > >> > sed you mean? >> >> We definitely won't be using sed, > > Why not? Sed is nearly ubiquitous in the Unix environment... > >> so don't worry too much about the building of the docs. > > I find that building the docs is useful to check the results... > >> We don't need sed 'foo' or anything as we have >> CMake and it can do everything we need *cross platform*. > > We already settled for not caring too much for the doc building *cross > platform* since actually there is no (even using sphinx) tool able to > build docs *cross platform*. This is due to the fact that the majority of > the tools use docbook as an intemediate format, that use xml stylesheets > transformations, latex and other tricks to produce pdf and epub. > >> CMake can read files into variables and it can process configure >> files[1] which can produce any intermediate file we require for >> processing. > > ok but I am not using and I am not able to use cmake anyway. I will try > to port all the docs into this new format. When the port will be complete > cmake people can (if they will) step in. I do not mean to be rude, mind > me, just keep on discussing since I am not sure to see your point and > that is probably my fault anyway... > >> Personally I really dislike documentation that's chopped up into >> separate pages, > > not pages, chapters. So for this point we have find an agreement. > See below...[XX] > >> the old CMake documentation is much better than the >> new (presumably Sphinx generated) documentation for me. > > I do not have access to the CMake docs, I do not know and I cannot adjudicate. > >> One search of >> the page always results in me getting results, whereas it doesn't in >> the newly separated docs. > > Uhm that could be really a point to unite all the docs into one big file > but perhaps it can be circunvented using the trick to unite all the docs > into one big format before compiling... [XX] I am sure I am not the > onlyone that find handier to have the big docs separated into chapters > ... that could really kill two birds with one stone... > >> I'll start the CMake and will try and make use of Fat-Zer's starting >> point. We have to test for a lot of features though to make it easy >> for documentation builders. > > do you have a git report to follow your work? > >> I assume that translators will simply use something like poedit which >> they'll be used to on the po files, is that right? > > right > >> So really, unless they're keen to see the built output, >> the documentation build system shouldn't really trip them up anyway. > > well, seeing the output finished *before* committing the work is a really > *plus* that I am not willing to renounce without a very good reason. > >> Hopefully we'll get CI building >> of the docs and an automatic upload of at least one format to the web. > > That would be nice. Html output is the perfect format for the web, and it > could easily be cross platform since it does not need any of the all > other tools (docbook/latex/etc.) that complicate the toolchain.
Yes, I intend to make the CI do that. I am not sure where if the files should be hosted (chached) somewhere out of the Jenkins workspace. I was thinking pushing them to http://downloads.kicad-pcb.org/, but I will wait fixing that untill we have cmake for the docs. Thank you. > > Thank for sharing your thoughts > > -- > > > Marco Ciampa _______________________________________________ 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
