[Kicad-developers] on documentation format ...
Hi all. It seems that it is time to choose a format for good. I am insecure by nature so I am stuck on this quandary: asciidoc or rest? I was almost making up my mind when Alexander Golubev rightly asked me how to split big documents as the pcbnew and eeschema ref manuals into many, one for chapter, files. It turned out that while sphinx is perfectly capable of updating the po files that refers to the multiple splitted chapter files, po4a on which asciidoc relies for i18n, does not "understand" the asciidoc include file macro. This fact means that po4a is not able, by itself, to build a single big or multiple .po files (one for chapter) files from any asciidoc with include macro by itself (that means without the help of some makefile/script magic). And above all, this means that po4a is not able to update the included files with the correct strings from the correct .po file, again without any external (=scripts) help. So we have to: - get rid of the inclusion of multiple chapter files and collect all chapters into one single, one for manual, big file for asciidoc. Simple solution but not very nice. or - try to find a solution via makefile/scripts to obtain one po file per chapter (may be the best solution) for asciidoc, recreate/updated all chapter files using the po files like we are doing now with the single file documents we have now (if you have already a simple solution, please fork & commit! :-) or - get rid of asciidoc altogether and use sphinx that does not have this problem. Apart from being slightly simpler & less sophisticated format it is not a big change from asciidoc. We lose some formatting options on tables and we gain support from https://readthedocs.org/, very interesting platform. But if we may be concerned on rely on github for just the git repo (not a big problem IMHO) maybe this could not a very wise decision... I am investigating the second option. In the meantime please say what you think about the format to choose. Cheers -- 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
Re: [Kicad-developers] on documentation format ...
On Sat, Feb 7, 2015 at 2:27 AM, Marco Ciampa wrote: > Hi all. > > It seems that it is time to choose a format for good. > I am insecure by nature so I am stuck on this quandary: asciidoc or rest? > > I was almost making up my mind when Alexander Golubev rightly asked me > how to split big documents as the pcbnew and eeschema ref manuals into > many, one for chapter, files. > > It turned out that while sphinx is perfectly capable of updating the po > files that refers to the multiple splitted chapter files, po4a on which > asciidoc relies for i18n, does not "understand" the asciidoc include file > macro. This fact means that po4a is not able, by itself, to build a > single big or multiple .po files (one for chapter) files from any > asciidoc with include macro by itself (that means without the help of > some makefile/script magic). And above all, this means that po4a is not > able to update the included files with the correct strings from the > correct .po file, again without any external (=scripts) help. > > So we have to: > > - get rid of the inclusion of multiple chapter files and collect all > chapters into one single, one for manual, big file for asciidoc. > Simple solution but not very nice. > > or > > - try to find a solution via makefile/scripts to obtain one po file per > chapter (may be the best solution) for asciidoc, recreate/updated all > chapter files using the po files like we are doing now with the single > file documents we have now (if you have already a simple solution, > please fork & commit! :-) > > or > > - get rid of asciidoc altogether and use sphinx that does not have this > problem. Apart from being slightly simpler & less sophisticated format > it is not a big change from asciidoc. We lose some formatting options > on tables and we gain support from https://readthedocs.org/, very > interesting platform. But if we may be concerned on rely on github for > just the git repo (not a big problem IMHO) maybe this could not a very > wise decision... > > I am investigating the second option. In the meantime please say what you > think about the format to choose. > > > What a nuisance that po4a does not recognize "include". Maybe we should submit a patch to po4a? 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. 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. - Cirilo ___ 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
Re: [Kicad-developers] on documentation format ...
I think Marco mentioned on IRC that you could provide multiple files to po4a and solve it with the make scripts. Of course this should not hold anyone back at patching. Is this correct Marco? Den 06/02/2015 23.56 skrev "Cirilo Bernardo" : > On Sat, Feb 7, 2015 at 2:27 AM, Marco Ciampa wrote: > >> Hi all. >> >> It seems that it is time to choose a format for good. >> I am insecure by nature so I am stuck on this quandary: asciidoc or rest? >> >> I was almost making up my mind when Alexander Golubev rightly asked me >> how to split big documents as the pcbnew and eeschema ref manuals into >> many, one for chapter, files. >> >> It turned out that while sphinx is perfectly capable of updating the po >> files that refers to the multiple splitted chapter files, po4a on which >> asciidoc relies for i18n, does not "understand" the asciidoc include file >> macro. This fact means that po4a is not able, by itself, to build a >> single big or multiple .po files (one for chapter) files from any >> asciidoc with include macro by itself (that means without the help of >> some makefile/script magic). And above all, this means that po4a is not >> able to update the included files with the correct strings from the >> correct .po file, again without any external (=scripts) help. >> >> So we have to: >> >> - get rid of the inclusion of multiple chapter files and collect all >> chapters into one single, one for manual, big file for asciidoc. >> Simple solution but not very nice. >> >> or >> >> - try to find a solution via makefile/scripts to obtain one po file per >> chapter (may be the best solution) for asciidoc, recreate/updated all >> chapter files using the po files like we are doing now with the single >> file documents we have now (if you have already a simple solution, >> please fork & commit! :-) >> >> or >> >> - get rid of asciidoc altogether and use sphinx that does not have this >> problem. Apart from being slightly simpler & less sophisticated format >> it is not a big change from asciidoc. We lose some formatting options >> on tables and we gain support from https://readthedocs.org/, very >> interesting platform. But if we may be concerned on rely on github for >> just the git repo (not a big problem IMHO) maybe this could not a very >> wise decision... >> >> I am investigating the second option. In the meantime please say what you >> think about the format to choose. >> >> >> > What a nuisance that po4a does not recognize "include". Maybe we should > submit a patch to po4a? 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. 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. > > - Cirilo > > > ___ > 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
Re: [Kicad-developers] on documentation format ...
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? -- 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
Re: [Kicad-developers] on documentation format ...
On Sat, Feb 07, 2015 at 01:02:20AM +0100, Nick Østergaard wrote: > I think Marco mentioned on IRC that you could provide multiple files to > po4a and solve it with the make scripts. Of course this should not hold > anyone back at patching. > > Is this correct Marco? Yes! See the other mail ... ;-) -- 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
Re: [Kicad-developers] on documentation format ...
So asciidoc wins for now? Excellent! Adam Wolf On Feb 6, 2015 6:11 PM, "Marco Ciampa" wrote: > On Sat, Feb 07, 2015 at 01:02:20AM +0100, Nick Østergaard wrote: > > I think Marco mentioned on IRC that you could provide multiple files to > > po4a and solve it with the make scripts. Of course this should not hold > > anyone back at patching. > > > > Is this correct Marco? > > Yes! See the other mail ... ;-) > > -- > > > 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
Re: [Kicad-developers] on documentation format ...
On Sat, Feb 07, 2015 at 10:22:00AM +0400, Fat-Zer wrote: > 2015-02-07 3:11 GMT+03:00 Marco Ciampa : > > On Sat, Feb 07, 2015 at 01:02:20AM +0100, Nick Østergaard wrote: > >> I think Marco mentioned on IRC that you could provide multiple files to > >> po4a and solve it with the make scripts. Of course this should not hold > >> anyone back at patching. > >> > >> Is this correct Marco? > > > > Yes! See the other mail ... ;-) > > > About your Makefile, instead of sed'ing the files you may store them > in the different dir... > > As a propose, have you considered if it would be better to have > multiple po files, one for each *.adoc? As a criterion I want to make the Makefile behave in a way that will be consistent with the behaviour of a new, corrected version of po4a. Let me think about it, I am open to suggestions. If you think there could be a better way to handle it, please try to explain it in all the details so we can see if there are any flaws in it. Using a .po file for file would mean that we cannot maintain the current structure to have a .po file for language: it.po, fr.po, etc. That it means that they should be in a form like: locales/it/LC_MESSAGES/ Pcbnew.po Pcbnew_chapter_01.po Pcbnew_chapter_02.po Pcbnew_chapter_03.po ... that could be a great idea and consistent with other toolchains (see sphinx). Do you prefer this way? Do you think it would be better in this way? PS: hope you do not mind I bounce this email also into devs ml, I do not see any problem on making this discussion public... Thank you very much for sharing me your thougths. I am _not_ a programmer. If someone has some suggestion on how to improve this mechanism, please send suggestions! -- 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
Re: [Kicad-developers] on documentation format ...
On 7 February 2015 at 00:09, Marco Ciampa 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, so don't worry too much about the building of the docs. We don't need sed 'foo' or anything as we have CMake and it can do everything we need *cross platform*. CMake can read files into variables and it can process configure files[1] which can produce any intermediate file we require for processing. Personally I really dislike documentation that's chopped up into separate pages, the old CMake documentation is much better than the new (presumably Sphinx generated) documentation for me. One search of the page always results in me getting results, whereas it doesn't in the newly separated docs. 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. I assume that translators will simply use something like poedit which they'll be used to on the po files, is that right? So really, unless they're keen to see the built output, the documentation build system shouldn't really trip them up anyway. Hopefully we'll get CI building of the docs and an automatic upload of at least one format to the web. [1] http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:configure_file 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
Re: [Kicad-developers] on documentation format ...
On Mon, Feb 09, 2015 at 10:09:04AM +, Brian Sidebotham wrote: > On 7 February 2015 at 00:09, Marco Ciampa 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. 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
Re: [Kicad-developers] on documentation format ...
On 9 February 2015 at 11:01, Marco Ciampa wrote: > On Mon, Feb 09, 2015 at 10:09:04AM +, Brian Sidebotham wrote: >> On 7 February 2015 at 00:09, Marco Ciampa 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 documentati
Re: [Kicad-developers] on documentation format ...
2015-02-09 12:01 GMT+01:00 Marco Ciampa : > On Mon, Feb 09, 2015 at 10:09:04AM +, Brian Sidebotham wrote: >> On 7 February 2015 at 00:09, Marco Ciampa 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
Re: [Kicad-developers] on documentation format ...
On 2/9/2015 6:01 AM, Marco Ciampa wrote: > On Mon, Feb 09, 2015 at 10:09:04AM +, Brian Sidebotham wrote: >> On 7 February 2015 at 00:09, Marco Ciampa 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 wo
Re: [Kicad-developers] on documentation format ...
On 2/9/2015 6:43 AM, Nick Østergaard wrote: > 2015-02-09 12:01 GMT+01:00 Marco Ciampa : >> On Mon, Feb 09, 2015 at 10:09:04AM +, Brian Sidebotham wrote: >>> On 7 February 2015 at 00:09, Marco Ciampa 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"
Re: [Kicad-developers] on documentation format ...
On Mon, Feb 09, 2015 at 09:35:34AM -0500, Wayne Stambaugh wrote: > On 2/9/2015 6:43 AM, Nick Østergaard wrote: > > 2015-02-09 12:01 GMT+01:00 Marco Ciampa : > >> 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. Other software projects use the main version number to distiguish main feature version, so the documentation should follow those numbers. For example GIMP v2.4 had a GIMP manual v2.4, 2.6->2.6, 2.8->2.8 and so on... In this way, doc versioning is easier... -- 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
