On 9 February 2015 at 11:01, Marco Ciampa <ciam...@libero.it> wrote: > 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.
No, as a project we have not decided this, or if we did, I missed it so please point me to the decision. The CMake build system must be cross-platform and I'm sure has been specified in several other emails. As always, email is a poor communication tool! >> 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] Each chapter is a page... >> 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. I included them in a reference and if you have access to the web you have access to the CMake docs!? >> 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? No not yet, because as I said, I will start the work... I will let you know when I have a repo together... >> 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. I am not suggesting that they *cannot* see it, I'm just saying that to translate the documentation you don't necessarily *have* to go through the build process, you can just edit the po files, and send a patch/commit/pull request. Thank-you for all your work on the text format documentation! Best Regards, Brian. _______________________________________________ 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
