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
