On 2/9/2015 6:01 AM, Marco Ciampa 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...
Anything that can be done with CMake should be done with CMake. We've run into issues in the past with unix commands in MSYS being different than their unix versions and causing issues. CMake gives us the least amount of grief when performing cross platform tasks. > >> 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. While not necessary, I would prefer that we can build the documentation on all platforms including windows. I realize at this point, windows is not quite there yet (not sure about OSX) and for distribution we can build on Linux. Firing up a VM or dual booting just to build the documentation is less than optimal. I would like to be able to build the documentation in MSYS2 when they get latex packaged. > >> 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. > > Thank for sharing your thoughts > > -- > > > Marco Ciampa > > I know a joke about UDP, but you might not get it. > > +------------------------+ > | GNU/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 > _______________________________________________ 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
