On 2/9/2015 6:43 AM, Nick Østergaard wrote: > 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.
HTML docs should be pushed to the "Documentation" page on kicad-pcb.org. PDFs will be required for KiCad binary packages. One thing to consider is versioning. As KiCad gains new features, the documentation will get updated accordingly. However, pushing the latest docs to kicad-pcb.org may confuse stable release users who do not yet have these features. It's not a major issue right now but it's something we should be thinking about. > >> >> 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 > _______________________________________________ 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
