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 ciam...@libero.it: 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
Re: [Kicad-developers] on documentation format ...
2015-02-09 12:01 GMT+01:00 Marco Ciampa ciam...@libero.it: On Mon, Feb 09, 2015 at 10:09:04AM +, 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
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 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. 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 ciam...@libero.it wrote: On Mon, Feb 09, 2015 at 10:09:04AM +, 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 :
Re: [Kicad-developers] on documentation format ...
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, 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 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 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
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 ciam...@libero.it: On Mon, Feb 09, 2015 at 10:09:04AM +, 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
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 ciam...@libero.it: 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 Sat, Feb 7, 2015 at 2:27 AM, Marco Ciampa ciam...@libero.it 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 ...
So asciidoc wins for now? Excellent! Adam Wolf On Feb 6, 2015 6:11 PM, Marco Ciampa ciam...@libero.it 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 ...
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 cirilo.berna...@gmail.com: On Sat, Feb 7, 2015 at 2:27 AM, Marco Ciampa ciam...@libero.it 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] New documentation format.
On 11/25/2014 8:59 PM, Fat-Zer wrote: 2014-11-25 18:17 GMT+03:00 Wayne Stambaugh stambau...@verizon.net mailto:stambau...@verizon.net: Are there any plans on reorganization of doc/translation repository from scratch? e.g. IMO it would be a good decision to drop the history of generated files like pdf's and *.mo and exclude them from being indexed. Yes, all of the binary files will be removed from the source tree and generated using makefiles created by CMake. It may take awhile to get all of the CMake stuff in place but that is the plan. I wanna help up with cmake scripting, I can prepare a template repository with ready to use cmake scripts and phony docs if it will be appreciated. It would be greatly appreciated. You should wait until we finalize the required documentation tools so you can use CMake to check for the availability of the tools. Otherwise, you may have to redo it. Brian Sidebotham also volunteered to help with the CMake scripts. Brian has a lot of experience with CMake (he wrote the kicad-winbuilder) so he would be a good resource. I'm hoping we can nail down the document format and tools in the next few weeks. Please coordinate your efforts with Marco since he will most likely be doing a lot of the document conversion from the current format. We have talked about using GitHub to host the documentation so that decision will also need to be made. In the future, please reply to the mailing list so other folks know your intentions so they can help out and/or prevent duplicate efforts. Thank you for volunteering to help out with this important part of the project. Cheers, Wayne ___ 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] New documentation format.
2014-11-26 15:13 GMT+01:00 Wayne Stambaugh stambau...@verizon.net: On 11/25/2014 8:59 PM, Fat-Zer wrote: 2014-11-25 18:17 GMT+03:00 Wayne Stambaugh stambau...@verizon.net mailto:stambau...@verizon.net: Are there any plans on reorganization of doc/translation repository from scratch? e.g. IMO it would be a good decision to drop the history of generated files like pdf's and *.mo and exclude them from being indexed. Yes, all of the binary files will be removed from the source tree and generated using makefiles created by CMake. It may take awhile to get all of the CMake stuff in place but that is the plan. I wanna help up with cmake scripting, I can prepare a template repository with ready to use cmake scripts and phony docs if it will be appreciated. It would be greatly appreciated. You should wait until we finalize the required documentation tools so you can use CMake to check for the availability of the tools. Otherwise, you may have to redo it. Brian Sidebotham also volunteered to help with the CMake scripts. Brian has a lot of experience with CMake (he wrote the kicad-winbuilder) so he would be a good resource. I'm hoping we can nail down the document format and tools in the next few weeks. Please coordinate your efforts with Marco since he will most likely be doing a lot of the document conversion from the current format. We have talked about using GitHub to host the documentation so that decision will also need to be made. For the moment the conversion/decision process is hosted on Marco's git repo on github, so if the cmake'ers can't wait, they could work from that already. I know that Marco has spent some time to write normal Makefiles, so I guess they could help a little on what commands actually is needed to generate the docs. I am sure he will be happy with any help or involvement he can get to work with cmake. But not to forget, since the format has not been decided yet, work will be lost if one decide to support all the formats available for testing. In the future, please reply to the mailing list so other folks know your intentions so they can help out and/or prevent duplicate efforts. Thank you for volunteering to help out with this important part of the project. Cheers, Wayne ___ 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] New documentation format.
Le 25/11/2014 08:41, Marco Ciampa a écrit : On Mon, Nov 24, 2014 at 07:19:02PM -0500, Wayne Stambaugh wrote: It's been a few weeks and I haven't heard anything so I'll assume everyone who is interested has looked at Marco's evaluation. The only folks I didn't hear from were the translators. I would be nice to know what their preferences are with regard to the new format. I would like to get this moving so the first order of business is to decide on a format. Thanks Wayne for raising this topic, if it was for me I'll be evaluating forever... Looking at the different formats, it seems to me that either asciidoc (easiest to read text format) or reStructuredText (full implementation) be the new format. Please note that actually it is somehow viceversa: asciidoc is easier to read _and_ more complete, almost comparable to docbook as copleteness, see table formatting for example (complete in asciidoc and absolutly absent in rest) Given the differences between markdown implementations (which there seems to be quite a few of), I would rather not depend on it since it seems to straddle the fence between asciidoc and rst. Well this is one of my fault. I never obtained to get a complete try of a markdown test. The thing is that I got stuck into choosing the md flavour and real life burden too slowed me down. I am dissadisfacted to the fact of not have being able to produce almost one single test conversion. If you can manage to wait for just another week I can try to create one for the purpouse to see at the results. I am resolved to use git-hub version just to see how a good english version appear live... The thing that made me not to discard md at all from the competition is that I've discovered that the documentation tool that we already use is oxygen and oxygen already creates md output, so using one format for all docs is not at all a bad idea... I've personally played around with asciidoc and rst and to be honest I didn't find rst all that bad Apart from table formatting and some other quirks like not being able to produce bold _and_ italics together... Table formatting (at least a simple but decent table formatting, allowing images in tables), bold _and_ italics and small image insertion (like a char in a string) are widely used in current Kicad doc. There features must be considered for the final choice. The leak of table formatting is a serious issue in markdown which has too poor formatting options. once I cleaned up the formatting of the documentation converted from the odt file some I'm currently leaning that way at the moment since it supports almost all of the elements of docbook. ok Lets see if we can come to a consensus over the new few weeks. Very well, it is time. Many thanks! -- Jean-Pierre CHARRAS ___ 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] New documentation format.
Le 25/11/2014 09:34, jp charras a écrit : The leak of table formatting is a serious issue in markdown which has __ Sorry: The lack of table ... too poor formatting options. -- Jean-Pierre CHARRAS ___ 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] New documentation format.
On 11/25/2014 2:41 AM, Marco Ciampa wrote: On Mon, Nov 24, 2014 at 07:19:02PM -0500, Wayne Stambaugh wrote: It's been a few weeks and I haven't heard anything so I'll assume everyone who is interested has looked at Marco's evaluation. The only folks I didn't hear from were the translators. I would be nice to know what their preferences are with regard to the new format. I would like to get this moving so the first order of business is to decide on a format. Thanks Wayne for raising this topic, if it was for me I'll be evaluating forever... Looking at the different formats, it seems to me that either asciidoc (easiest to read text format) or reStructuredText (full implementation) be the new format. Please note that actually it is somehow viceversa: asciidoc is easier to read _and_ more complete, almost comparable to docbook as copleteness, see table formatting for example (complete in asciidoc and absolutly absent in rest) I must have misread the feature set breakdown in Wikipedia. If this is the case and asciidoc's table formatting meet the requirements that JP mentioned, then the decision to use asciidoc is a no brainer. Given the differences between markdown implementations (which there seems to be quite a few of), I would rather not depend on it since it seems to straddle the fence between asciidoc and rst. Well this is one of my fault. I never obtained to get a complete try of a markdown test. The thing is that I got stuck into choosing the md flavour and real life burden too slowed me down. I am dissadisfacted to the fact of not have being able to produce almost one single test conversion. If you can manage to wait for just another week I can try to create one for the purpouse to see at the results. I am resolved to use git-hub version just to see how a good english version appear live... Sure, go ahead and see if you can get some better results with markdown. The more information we have the better. It makes me a bit nervous that there are so many different flavors of markdown. The thing that made me not to discard md at all from the competition is that I've discovered that the documentation tool that we already use is oxygen and oxygen already creates md output, so using one format for all docs is not at all a bad idea... I would be hesitant to use the markdown support provided by Doxygen. It seems to be a very limited subset of markdown. I know because I used it to add the Stable Release Policy and Road Map sections to the developers documentation and I wasn't very impressed. Doxygen is great for extracting source code documentation but I don't think it's the most useful tool for creating general purpose documentation. I've personally played around with asciidoc and rst and to be honest I didn't find rst all that bad Apart from table formatting and some other quirks like not being able to produce bold _and_ italics together... once I cleaned up the formatting of the documentation converted from the odt file some I'm currently leaning that way at the moment since it supports almost all of the elements of docbook. ok Lets see if we can come to a consensus over the new few weeks. Very well, it is time. Many thanks! ___ 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] New documentation format.
On Mon, Nov 24, 2014 at 07:19:02PM -0500, Wayne Stambaugh wrote: format. Looking at the different formats, it seems to me that either asciidoc (easiest to read text format) or reStructuredText (full implementation) be the new format. Given the differences between asciidoc is fine for me, if votes are tied :D -- Lorenzo Marcantonio Logos Srl ___ 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] New documentation format.
On Mon, Nov 24, 2014 at 07:19:02PM -0500, Wayne Stambaugh wrote: It's been a few weeks and I haven't heard anything so I'll assume everyone who is interested has looked at Marco's evaluation. The only folks I didn't hear from were the translators. I would be nice to know what their preferences are with regard to the new format. I would like to get this moving so the first order of business is to decide on a format. Thanks Wayne for raising this topic, if it was for me I'll be evaluating forever... Looking at the different formats, it seems to me that either asciidoc (easiest to read text format) or reStructuredText (full implementation) be the new format. Please note that actually it is somehow viceversa: asciidoc is easier to read _and_ more complete, almost comparable to docbook as copleteness, see table formatting for example (complete in asciidoc and absolutly absent in rest) Given the differences between markdown implementations (which there seems to be quite a few of), I would rather not depend on it since it seems to straddle the fence between asciidoc and rst. Well this is one of my fault. I never obtained to get a complete try of a markdown test. The thing is that I got stuck into choosing the md flavour and real life burden too slowed me down. I am dissadisfacted to the fact of not have being able to produce almost one single test conversion. If you can manage to wait for just another week I can try to create one for the purpouse to see at the results. I am resolved to use git-hub version just to see how a good english version appear live... The thing that made me not to discard md at all from the competition is that I've discovered that the documentation tool that we already use is oxygen and oxygen already creates md output, so using one format for all docs is not at all a bad idea... I've personally played around with asciidoc and rst and to be honest I didn't find rst all that bad Apart from table formatting and some other quirks like not being able to produce bold _and_ italics together... once I cleaned up the formatting of the documentation converted from the odt file some I'm currently leaning that way at the moment since it supports almost all of the elements of docbook. ok Lets see if we can come to a consensus over the new few weeks. Very well, it is time. Many thanks! -- Marco Ciampa I know a joke about UDP, but you might not get it. ++ | 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] new documentation format
On Tue, Oct 28, 2014 at 12:12:52AM +0100, Guilherme Brondani Torri wrote: On 10/26/14, 12:17 AM, Marco Ciampa wrote: On Sat, Oct 25, 2014 at 10:52:54AM -0400, Wayne Stambaugh wrote: Marco, Great work on the conversion analysis. I finally go around to testing this and I have to say that I prefer the asciidoc format better than the markdown and rst formats for plain text readability. Almost everyone does it but please consider that readability is not the most important factor. As I said many people use rest because of sphinx. Please consider that sphinx integrate a search javascript function into the html generated, although maybe not so important. Hi there! Just a few comment of a casual user... I am also looking for alternatives for the Qucs documentation. Our manuals are in mostly in LaTex which is amazing for what it does, but is a bit of a pain to translate. I understand... I found the approach taken by OpenMOC rather interesting [1]. They use Sphinx and Doxygen combined. The whole documentation is automatically (re)generated at every commit, directly from the GitHub repository. These examples are _very_ interesting indeed. We could definitely build something similar. There is also this demo, [2] which combines Sphinx, Github, Transifex and publish in the Read the Docs. Apparently anyone with access to the fork can edit directly on the GitHub web editor and the documentation is rebuild. I never used Transifex, but it seems to work very well if someone takes responsibility to sync the translation files from time to time. I have yet to look for similar thinks with AsciiDoc... Me neither but, all in all, is just html pages automatically generated and commited into a git repo. Nothing that we couldn't afford with some simple scripting... Best regards, Guilherme [1] https://mit-crpg.github.io/OpenMOC/devguide/documentation.html http://masaori-sphinx-internationalization-example-en.readthedocs.org/en/latest/# Anyway I will take a look at it to see if there are some interesting details that I haven't seen... Many thanks! -- Marco Ciampa I know a joke about UDP, but you might not get it. ++ | 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] new documentation format
On 10/25/2014 6:17 PM, Marco Ciampa wrote: On Sat, Oct 25, 2014 at 10:52:54AM -0400, Wayne Stambaugh wrote: Marco, Great work on the conversion analysis. I finally go around to testing this and I have to say that I prefer the asciidoc format better than the markdown and rst formats for plain text readability. Almost everyone does it but please consider that readability is not the most important factor. As I said many people use rest because of sphinx. Please consider that sphinx integrate a search javascript function into the html generated, although maybe not so important. My main issue with the rst formatting was the fact that odt2sphinx creating very long line which in some cases wrap more than once using a 100 character line width editor. This is a serious problem IMO. Looking at wrapped lines in a text editor makes my eyes bleed. I hope this is just the output formatting issue with odt2sphinx and not required by the rst format. Please don't underestimate the importance of plain text readability. If I have to struggle to figure out the file format, I will be less motivated to contribute to maintaining the documentation. My guess is that other potential contributers will feel the same way. That being said, rst would be tolerable if the formatting issues can be resolved. Are there features in rst that are not in asciidoc or markdown that are required to generate the kicad documentation? If so, then that tends to tip things in favor of rst. If not, then the less readable syntax would favor asciidoc. I also could not convert the asciidoc format to pdf using your example. I always get an error about dblatex failing even though I have it installed on my Debian partition. I use Ubuntu 14.04. Maybe Debian asciidoc or dblatex packages are bit older? 1. Please print the output error strings eventually augmenting verbosity. 2. try -L or --no-xmllint option, to disable xmllint check for sometimes xmmlint is too picky 3. try using asciidoctor to convert into xml first, exec a2x with -n or --dry-run to see the command line it execs to try to do it manually substituting ascidoc with asciidoctor TIA None of the section headers or table of contents were converted so there would obviously be some hand work involved. That's not a big deal for the cvpcb documentation but for all of the documentation there is a lot of work to do. Windows support is iffy. Even though MSYS2 has an asciidoc package, the optional bits to create pdfs is missing so that is an issue. I guess the next steps are: * Make the final decision on the format. ok * Pick a VCS and a host server. Obvious choices are bzr/launchpad and git/github. I am for git... * Convert all of the documentation over to asciidoc. I can do it... no problem. * Write CMake build configuration support to handle dependency checking, out building, translation file creation, and installation. I do not know cmake at all * Create initial repo and let the document fixing begin. ok Any volunteers? Count on me of course. ___ 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] new documentation format
On Wed, Oct 29, 2014 at 10:21:55AM -0400, Wayne Stambaugh wrote: My main issue with the rst formatting was the fact that odt2sphinx creating very long line which in some cases wrap more than once using a 100 character line width editor. This is a serious problem IMO. Looking at wrapped lines in a text editor makes my eyes bleed. I hope No virtual autowrapping like in vim? bad editor then :D Just joking. Maybe a pipe thru fmt would help? -- Lorenzo Marcantonio Logos Srl ___ 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] new documentation format
On 10/26/14, 12:17 AM, Marco Ciampa wrote: On Sat, Oct 25, 2014 at 10:52:54AM -0400, Wayne Stambaugh wrote: Marco, Great work on the conversion analysis. I finally go around to testing this and I have to say that I prefer the asciidoc format better than the markdown and rst formats for plain text readability. Almost everyone does it but please consider that readability is not the most important factor. As I said many people use rest because of sphinx. Please consider that sphinx integrate a search javascript function into the html generated, although maybe not so important. Hi there! Just a few comment of a casual user... I am also looking for alternatives for the Qucs documentation. Our manuals are in mostly in LaTex which is amazing for what it does, but is a bit of a pain to translate. I found the approach taken by OpenMOC rather interesting [1]. They use Sphinx and Doxygen combined. The whole documentation is automatically (re)generated at every commit, directly from the GitHub repository. There is also this demo, [2] which combines Sphinx, Github, Transifex and publish in the Read the Docs. Apparently anyone with access to the fork can edit directly on the GitHub web editor and the documentation is rebuild. I never used Transifex, but it seems to work very well if someone takes responsibility to sync the translation files from time to time. I have yet to look for similar thinks with AsciiDoc... Best regards, Guilherme [1] https://mit-crpg.github.io/OpenMOC/devguide/documentation.html http://masaori-sphinx-internationalization-example-en.readthedocs.org/en/latest/# ___ 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] new documentation format
Marco, Great work on the conversion analysis. I finally go around to testing this and I have to say that I prefer the asciidoc format better than the markdown and rst formats for plain text readability. I also could not convert the asciidoc format to pdf using your example. I always get an error about dblatex failing even though I have it installed on my Debian partition. None of the section headers or table of contents were converted so there would obviously be some hand work involved. That's not a big deal for the cvpcb documentation but for all of the documentation there is a lot of work to do. Windows support is iffy. Even though MSYS2 has an asciidoc package, the optional bits to create pdfs is missing so that is an issue. I guess the next steps are: * Make the final decision on the format. * Pick a VCS and a host server. Obvious choices are bzr/launchpad and git/github. * Convert all of the documentation over to asciidoc. * Write CMake build configuration support to handle dependency checking, out building, translation file creation, and installation. * Create initial repo and let the document fixing begin. Any volunteers? Wayne On 10/21/2014 5:58 PM, Marco Ciampa wrote: Hello, talking about the project of switching the KiCad documentation to an easier to maintain and translate format, after some experiments, (I know, I am slow ... I am not a real programmer) I have produced something to check. This is in effect something like an RFC: I need your comments, suggestions, improvements (and patches are welcome). I started writing an email, this: https://github.com/ciampix/kicad-doc/blob/master/doc/kicad-doc-doc.adoc it got bigger and bigger and it is not finished, but I though that it could be useful to publish it before being closed because I do not want to write it all alone. Along with this text there are two dirs in src: asciidoc and rest. Basically these folders contain the cvpcb manual converted into asciidoc and rest and the small example scripts to create docs into html/pdf/epub. The complete cycle is: (odt-)asciidoc/rest -translation extraction -(translation) -merge-nationalized pdf/html/epub The examples are in asciidoc and rest but the asciidoc toolchain is almost the same for markdown. I have reported some comments about txt2tags, textile and sisu but I do not have studied these tools enough to have a clear idea about. So I ask you to: - have a say about the work - try my examples - express your preferences about: a. the documentation text format b. the data organization of the manuals, in particular: - file name/extension conventions - source files folders, - image folders - makefiles/cmake configuration (I do not know anything about cmake...) - any other thing If you have any doubt or problem about anything please express yourself. I do not think we are in a hurry so I think that we can our time to decide and clear out any quandary. When we will have decided the source text format we will start converting all the manuals. Please bear in mind that *anything written in a foreign language that is not strictly adherent to the english reference manual will have to be removed*. So, if you think that something you have written in a localized manual is not present in the reference, try to translate it in English for the inclusion in the reference: doing this may save your translation and give a hand to the whole project. PS: ... and please forgive my terrible English. ___ 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] new documentation format
On 25 October 2014 15:52, Wayne Stambaugh stambau...@verizon.net wrote: Marco, Great work on the conversion analysis. I finally go around to testing this and I have to say that I prefer the asciidoc format better than the markdown and rst formats for plain text readability. I also could not convert the asciidoc format to pdf using your example. I always get an error about dblatex failing even though I have it installed on my Debian partition. None of the section headers or table of contents were converted so there would obviously be some hand work involved. That's not a big deal for the cvpcb documentation but for all of the documentation there is a lot of work to do. Windows support is iffy. Even though MSYS2 has an asciidoc package, the optional bits to create pdfs is missing so that is an issue. I guess the next steps are: * Make the final decision on the format. * Pick a VCS and a host server. Obvious choices are bzr/launchpad and git/github. * Convert all of the documentation over to asciidoc. * Write CMake build configuration support to handle dependency checking, out building, translation file creation, and installation. * Create initial repo and let the document fixing begin. Any volunteers? Wayne As I was pushing for us to make this move, and as I use asciidoc almost everyday for documenting projects at work, you can count on me to provide some horsepower. We should decide on our output format too. I was thinking we'd probably move to HTML output rather than PDF, but either is really okay with me. 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] new documentation format
On Sat, Oct 25, 2014 at 10:52:54AM -0400, Wayne Stambaugh wrote: Marco, Great work on the conversion analysis. I finally go around to testing this and I have to say that I prefer the asciidoc format better than the markdown and rst formats for plain text readability. Almost everyone does it but please consider that readability is not the most important factor. As I said many people use rest because of sphinx. Please consider that sphinx integrate a search javascript function into the html generated, although maybe not so important. I also could not convert the asciidoc format to pdf using your example. I always get an error about dblatex failing even though I have it installed on my Debian partition. I use Ubuntu 14.04. Maybe Debian asciidoc or dblatex packages are bit older? 1. Please print the output error strings eventually augmenting verbosity. 2. try -L or --no-xmllint option, to disable xmllint check for sometimes xmmlint is too picky 3. try using asciidoctor to convert into xml first, exec a2x with -n or --dry-run to see the command line it execs to try to do it manually substituting ascidoc with asciidoctor TIA None of the section headers or table of contents were converted so there would obviously be some hand work involved. That's not a big deal for the cvpcb documentation but for all of the documentation there is a lot of work to do. Windows support is iffy. Even though MSYS2 has an asciidoc package, the optional bits to create pdfs is missing so that is an issue. I guess the next steps are: * Make the final decision on the format. ok * Pick a VCS and a host server. Obvious choices are bzr/launchpad and git/github. I am for git... * Convert all of the documentation over to asciidoc. I can do it... no problem. * Write CMake build configuration support to handle dependency checking, out building, translation file creation, and installation. I do not know cmake at all * Create initial repo and let the document fixing begin. ok Any volunteers? Count on me of course. -- Marco Ciampa I know a joke about UDP, but you might not get it. ++ | 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] new documentation format
On 21 October 2014 22:58, Marco Ciampa ciam...@libero.it wrote: Hello, talking about the project of switching the KiCad documentation to an easier to maintain and translate format, after some experiments, (I know, I am slow ... I am not a real programmer) I have produced something to check. This is in effect something like an RFC: I need your comments, suggestions, improvements (and patches are welcome). I started writing an email, this: https://github.com/ciampix/kicad-doc/blob/master/doc/kicad-doc-doc.adoc it got bigger and bigger and it is not finished, but I though that it could be useful to publish it before being closed because I do not want to write it all alone. Along with this text there are two dirs in src: asciidoc and rest. Basically these folders contain the cvpcb manual converted into asciidoc and rest and the small example scripts to create docs into html/pdf/epub. The complete cycle is: (odt-)asciidoc/rest -translation extraction -(translation) -merge-nationalized pdf/html/epub The examples are in asciidoc and rest but the asciidoc toolchain is almost the same for markdown. I have reported some comments about txt2tags, textile and sisu but I do not have studied these tools enough to have a clear idea about. So I ask you to: - have a say about the work - try my examples - express your preferences about: a. the documentation text format b. the data organization of the manuals, in particular: - file name/extension conventions - source files folders, - image folders - makefiles/cmake configuration (I do not know anything about cmake...) - any other thing If you have any doubt or problem about anything please express yourself. I do not think we are in a hurry so I think that we can our time to decide and clear out any quandary. When we will have decided the source text format we will start converting all the manuals. Please bear in mind that *anything written in a foreign language that is not strictly adherent to the english reference manual will have to be removed*. So, if you think that something you have written in a localized manual is not present in the reference, try to translate it in English for the inclusion in the reference: doing this may save your translation and give a hand to the whole project. PS: ... and please forgive my terrible English. -- Marco Ciampa Excellent work Marco, firstly your English is not terrible, my Italian is! Thank-you for doing a thorough job in looking at the various tools available and it's great to have the view of a translator looking from the ease of internationalising a document properly as that's not an easy task. I've managed to read most of your document and everything looks sound to me, I agree with your conclusions, but then I use asciidoc every day of the week, so it's easy for me to agree with! At least, asciidoc is not very intrusive into the text of the document, it is light-weight. I was worried that po4a was not available on Windows, but it appears it's pretty easy to get going on windows. I'm sure the rest of the toolchain is easy to get running on Windows. See some information here with regards to po4a on windows: http://ehc.ac/p/ourorgan/svn/754/tree//trunk/HOWTO-build-help-on-Windows I'm excited for us to move to a text based documentation format as soon as possible. I imagine our workflow after we've decided on the markup source format needs to be: (1) Convert odt to text-based markup (2) Get a document writer (could be a current dev(s)) to go through the manuals and tidy up grammar, out-of-date screenshots, layout issues, etc. (3) Make sure the documentation build process is documented (which you've already done an excellent job starting, thanks!!) (4) Create the po files ready for translation and that should lead to translators being able to start translating the new manuals. The fact that everything, including images drops back to the master English version if there's not a specific language version is absolutely excellent. Before reading your article I was pro-Markdown as the solution we should use, but I am very convinced by your extensive work around the translation of the documentation and I understand the limitations of Markdown, so asciidoc is a fine conclusion to me. Thanks again for the update and hard work!! 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] new documentation format
To: kicad-developers From: Marco Ciampa Date: Tue, 21 Oct 2014 23:58:17 +0200 If you have any doubt or problem about anything please express yourself. I consider that the use of formats to create documentation using translations in the form of translation database (.po files) will, despite the many advantages, also some disadvantages for translators. While the use of such forms of translations for the UI is quite comfortable, the use of that form for translating a continuous text (which is result of the train of thoughts) can be very uncomfortable for translators. Why? The main difficulty will be limited visibility of the logic of the text and its layout (indentation, spacing). There will be situations where we will need to translate a fragment out of context. I as a translator prefer also see more of the text to be able to, among others, eliminate repetition of words and the use of synonyms. My native language is very flexible in this topic. Taking also the specificity of translated texts, unfortunately, it is in so many cases impossible to translate word for word. Sometimes you have to break down complex sentence into two (or even three) sentences that the reader can easily assimilate them. By translating KiCad user manual I had to just do that many times. Sometimes adding something from each other to avoid ambiguity. So. That’s my (maybe wrong) doubts. Regards Kerusey Karyu ___ 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] new documentation format
2014-10-22 17:57 GMT+02:00 Kerusey Karyu keruseyka...@o2.pl: To: kicad-developers From: Marco Ciampa Date: Tue, 21 Oct 2014 23:58:17 +0200 If you have any doubt or problem about anything please express yourself. I consider that the use of formats to create documentation using translations in the form of translation database (.po files) will, despite the many advantages, also some disadvantages for translators. While the use of such forms of translations for the UI is quite comfortable, the use of that form for translating a continuous text (which is result of the train of thoughts) can be very uncomfortable for translators. How is this different than translating normally (odf) and what is the alternative? ___ 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] new documentation format
On Wed, Oct 22, 2014 at 05:57:22PM +0200, Kerusey Karyu wrote: To: kicad-developers From: Marco Ciampa Date: Tue, 21 Oct 2014 23:58:17 +0200 If you have any doubt or problem about anything please express yourself. I consider that the use of formats to create documentation using translations in the form of translation database (.po files) will, despite the many advantages, also some disadvantages for translators. While the use of such forms of translations for the UI is quite comfortable, the use of that form for translating a continuous text (which is result of the train of thoughts) can be very uncomfortable for translators. Why? The main difficulty will be limited visibility of the logic of the text and its layout (indentation, spacing). There will be situations where we will need to translate a fragment out of context. I as a translator prefer also see more of the text to be able to, among others, eliminate repetition of words and the use of synonyms. My native language is very flexible in this topic. Taking also the specificity of translated texts, unfortunately, it is in so many cases impossible to translate word for word. Sometimes you have to break down complex sentence into two (or even three) sentences that the reader can easily assimilate them. By translating KiCad user manual I had to just do that many times. Sometimes adding something from each other to avoid ambiguity. So. That’s my (maybe wrong) doubts. Good point but I think that it is more a theoretical problem than a real one since such tools such as po4a, xml2po, etc. do not break paragraphs and in fact aggregate contiguous paragraphs. See for example the GIMP manual that is actually translated in these languages: Catalá, Dansk, Deutsch, English, Español, Ελληνικά (Greek) Français, Italiano, 日本語(Japanese), 한국어(Korean) Nederlands, Norwegian, Português, Pусский, Slovenščina Svenska, 中文 (Chinese). A manual of about 800 pages long. That kind of problem, for what I may know, never arised. I hope I have unraveled some doubt. -- Marco Ciampa I know a joke about UDP, but you might not get it. ++ | 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
