Re: [Kicad-developers] V6 documentation
Hi Franck, This should be superceeded by: https://dev-docs.kicad.org/en/file-formats/ Nick On Wed, 19 Jan 2022 at 19:41, Franck Bourdonnec wrote: > > > About doc, this one seems good but bazaar, no revision, no datestamp ? > > Is it maintained ? > > > bazaar.launchpad.net/~stambaughw/kicad/doc-read-only/download/head:/1115%4016bec504-3128-0410-b3e8-8e38c2123bca:trunk%252Fkicad-doc%252Fdoc%252Fhelp%252Ffile_formats%252Ffile_formats.pdf/file_formats.pdf > > > ___ > 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] V6 documentation
It looks like this is a sensitive topic, and I now understand the packagers feel pressure and that they aren't appreciated enough. That wasn't my intention and I didn't want to hint or imply anything negative towards anyone. On the contrary, I know packaging isn't easy (I have looked at the packaging systems and given up) and appreciate the work. There seems to be more than one subjects going on, packaging is only one. The more fundamental is the need or lack of need for offline documentation, and if there is need, how is that solved. This also seems to be a sensitive topic. Personally I don't see why documentation should be packaged at all for distros if it can be downloaded anyway. I mentioned PCM, not because I would think it would be the best solution, but just for brainstorming (however, this topic seems to be too sensitive for brainstorming). It would just be a natural way to download KiCad documentation because other content is downloaded with it, too, and it would be readily available to the end users. An extra benefit would be that it would automatically go to a location known to KiCad, so if KiCad tries to find local documentation, it would be in the right place. Eeli Kaikkonen On Thu, Jan 20, 2022 at 5:59 PM Carsten Schoenert wrote: > > Hi, > > Am 19.01.22 um 23:18 schrieb Eeli Kaikkonen: > > > I don't understand why this discussion is so difficult to understand. > > sorry but I don't understand what problem you are trying to solve! > There is no problem within the Linux world and their distros to provide > packaged documentation, there is no need to develop another new way for > distributing documentation. > > > I agree with Jon and don't see any problem for distros. As far as I > > can see the point is that the documentation package version shouldn't > > be logically dependent on the KiCad packages or vice versa. You can > > have package kicad-v6.0-documentation version, say, 20222001 [date], > > can't you? You don't have to give it the version number 6.0.x. If a > > git tag is needed for technical reasons, let's have automatic tagging > > which adds a tag each day. > > To use the words from Marco... > > "Are you serious?" > > I'm getting a bit disappointed because I become the feeling that you are > somehow ignorant about the arguments of at least two main packagers of > KiCad within Linux. And I really think that you want to solve problems > on the wrong corner. > > THE MAIN PROBLEM ARE THE OUTDATED DOCUMENTS! > NOT THE WAY THEY ARE DISTRIBUTED. > > So it's better to think about how the documentation can be updated and > how a ongoing process can be introduced to make contributions easier > with a low barrier for one time contributors. > > And as Marco did explain, we need to fix the tools if there is something > missed at the end. Be friendly to the distributions, please do not try > to ignore them. They are part of the FOSS ecosystem KiCad is depending on. > Do not try to "solve" things were distributions already have a process > for and established rules for that. > > I stop now reading any new post on this topic. > > -- > Regards > Carsten > > ___ > 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] V6 documentation
> THE MAIN PROBLEM ARE THE OUTDATED DOCUMENTS! > NOT THE WAY THEY ARE DISTRIBUTED. One reason the documents are outdated is that they are hard to contribute to. They are hard to contribute to in part because they use a toolchain that only works well on Linux, and many of our users who might feel like contributing use Windows or Mac. Simplifying the toolchain would enable easy contribution from any platform. Also, as I mentioned before, the docs and the source code will generally never be in sync, and there is not much point in trying to make them be in sync. This would just needlessly delay releases. It is better to have a "rolling" 6.x documentation separate from the 6.0.x bugfix releases of code (but see below, I don't mind that some distributions "require" a matching 6.0.x release of the docs). Separately, gettext/po4a is not the best tool for managing translation of long-form documentation. Yes, we have a "working" system, but it doesn't work very well. Documentation should be translated in large chunks, for example by reading an entire paragraph or section and then translating it into the target language with an understanding of the full context. Doing it in small chunks as is done today will not result in great translations as the source (English) documents are updated and rewritten. I don't have a specific proposal for a different system yet (this problem is well-solved in the commercial world using commercial tooling, but I'm not sure the best path for open-source and free tooling), but I do maintain that we should be looking at improving this system. > Do not try to "solve" things were distributions already have a process > for and established rules for that. If the distributions "need" 6.0.1 tagged documentation because of their rules, that is fine. There is no reason to stop providing that. It is just obviously not the best way to provide the documentation to users who have Internet access, so I am talking about ideas to provide more updated documentation to users that can make use of it. -Jon On Thu, Jan 20, 2022 at 10:59 AM Carsten Schoenert wrote: > Hi, > > Am 19.01.22 um 23:18 schrieb Eeli Kaikkonen: > > > I don't understand why this discussion is so difficult to understand. > > sorry but I don't understand what problem you are trying to solve! > There is no problem within the Linux world and their distros to provide > packaged documentation, there is no need to develop another new way for > distributing documentation. > > > I agree with Jon and don't see any problem for distros. As far as I > > can see the point is that the documentation package version shouldn't > > be logically dependent on the KiCad packages or vice versa. You can > > have package kicad-v6.0-documentation version, say, 20222001 [date], > > can't you? You don't have to give it the version number 6.0.x. If a > > git tag is needed for technical reasons, let's have automatic tagging > > which adds a tag each day. > > To use the words from Marco... > > "Are you serious?" > > I'm getting a bit disappointed because I become the feeling that you are > somehow ignorant about the arguments of at least two main packagers of > KiCad within Linux. And I really think that you want to solve problems > on the wrong corner. > > THE MAIN PROBLEM ARE THE OUTDATED DOCUMENTS! > NOT THE WAY THEY ARE DISTRIBUTED. > > So it's better to think about how the documentation can be updated and > how a ongoing process can be introduced to make contributions easier > with a low barrier for one time contributors. > > And as Marco did explain, we need to fix the tools if there is something > missed at the end. Be friendly to the distributions, please do not try > to ignore them. They are part of the FOSS ecosystem KiCad is depending on. > Do not try to "solve" things were distributions already have a process > for and established rules for that. > > I stop now reading any new post on this topic. > > -- > Regards > Carsten > > ___ > 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] V6 documentation
Hi, Am 19.01.22 um 23:18 schrieb Eeli Kaikkonen: I don't understand why this discussion is so difficult to understand. sorry but I don't understand what problem you are trying to solve! There is no problem within the Linux world and their distros to provide packaged documentation, there is no need to develop another new way for distributing documentation. I agree with Jon and don't see any problem for distros. As far as I can see the point is that the documentation package version shouldn't be logically dependent on the KiCad packages or vice versa. You can have package kicad-v6.0-documentation version, say, 20222001 [date], can't you? You don't have to give it the version number 6.0.x. If a git tag is needed for technical reasons, let's have automatic tagging which adds a tag each day. To use the words from Marco... "Are you serious?" I'm getting a bit disappointed because I become the feeling that you are somehow ignorant about the arguments of at least two main packagers of KiCad within Linux. And I really think that you want to solve problems on the wrong corner. THE MAIN PROBLEM ARE THE OUTDATED DOCUMENTS! NOT THE WAY THEY ARE DISTRIBUTED. So it's better to think about how the documentation can be updated and how a ongoing process can be introduced to make contributions easier with a low barrier for one time contributors. And as Marco did explain, we need to fix the tools if there is something missed at the end. Be friendly to the distributions, please do not try to ignore them. They are part of the FOSS ecosystem KiCad is depending on. Do not try to "solve" things were distributions already have a process for and established rules for that. I stop now reading any new post on this topic. -- Regards Carsten ___ 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] V6 documentation
On Wed, Jan 19, 2022 at 06:37:46PM -0500, Steven A. Falco wrote: > On 1/19/22 05:18 PM, Eeli Kaikkonen wrote: > > On Wed, Jan 19, 2022 at 9:13 PM Steven A. Falco > > wrote: > > > > > It would still be helpful if the doc repo could be tagged at the same > > > point that everything else is tagged, because every single Fedora package > > > needs a correct version in its name. For example, it would be very > > > strange (perhaps "illegal") to package something called the 6.0.1 doc > > > that came from some random SHA in an untagged tree. > > > > I don't understand why this discussion is so difficult to understand. > > I agree with Jon and don't see any problem for distros. As far as I > > can see the point is that the documentation package version shouldn't > > be logically dependent on the KiCad packages or vice versa. You can > > have package kicad-v6.0-documentation version, say, 20222001 [date], > > can't you? You don't have to give it the version number 6.0.x. If a > > git tag is needed for technical reasons, let's have automatic tagging > > which adds a tag each day. > > > I don't think the discussion is difficult to understand. > But Fedora's process doesn't map into what you have just proposed. Not just Fedora's but nearly any other distro do not work in that way... -- Saluton, 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] V6 documentation
On Wed, Jan 19, 2022 at 02:09:08PM -0500, Jon Evans wrote: > I think the "typical" Linux user wants up-to-date documentation and has > Internet access. The kind who does not have Internet access, or cares a > lot about how the documentation is packaged, is not the "mass market" Linux > user. KiCad is not some software targeted at some narrow segment of Linux > users: probably most of our users are on Windows. Ok, following your reasoning let's drop support for MacOS and Linux and focus only on Windows since most of the users are there... see? There is something you are missing here... [...] > I believe part of the reason we have trouble getting people to help write > the documentation is because the build process is tricky (it is only easy > on Linux; I've spent some time trying to make it run on Windows and Mac but > given up as a waste of time). We have a lot of active and engaged users on > Windows and Mac who basically cannot contribute to the documentation > because they can't easily build and test it locally. Ok let's improve this instead! And since the strings are .po files. Why not use an online service to support translations like transifex, weblate, zanata, pootle, crowdin, etc. with an online CI integration support it should be much less difficult... > One thing we could do that would help this is to change the build process > so that the main build is only HTML, and PDF build is an optional extra > generated from the HTML (that can be enabled by a CI job for packaging). That would be a HUGE mistake. PDF made from HTML are just horrible and unusable. The same for epub (that I use and love). > Another thing would be to change the translation system from the existing > gettext/po system (which is not very well suited to long-form text) to a > manual translation system. Are you serious? That would even a bigger mistake! That would make the translation process completely unmanageable... just imagine to have to read and compare manually hundred of pages to see what changed in the original... impossible! -- Saluton, 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] V6 documentation
On Wed, Jan 19, 2022 at 11:38:02AM -0500, Jon Evans wrote: > Carsten, > > There is no reason to remove the ability to package docs offline, I just > don't think it should be a focus of the project. > The majority of users will be served better by keeping a "rolling release" > online at docs.kicad.org (with a download button, ideally). > > > It absolutely doesn't hurt to build completely offline usable > documentation. > > It does hurt the way we do it today, for the following reasons: > > 1) We currently support multiple formats, which makes the build system and > formatting changes complicated It is not. It depends on the tool you use. If (when) we switch to asciidoctor, creating pdfs is straightforward and, in the near future, also will be epubs. > 2) We currently tie the documentation version together with the application > version, and don't have good workflows for "rolling release" of > documentation for Linux distros that use separate packages. If there are rolling releases of source packages, similarly, then there will be rolling releases of docs. I do not see the problem here. > 3) The application itself doesn't handle the situation where offline docs > are missing very gracefully, or note to users that when offline docs are > present that they are probably outdated. That is a bug. You should report it as usual. > What I would propose to improve the situation is: > > 1) Drop all formats except HTML. HTML is perfectly fine as an offline > format, and this allows us to make improvements to the build workflow and > the layout/style of the docs without worrying about doing so in a way that > also works for PDF. If you really want a PDF, you can render it from HTML > pages anyway. Dropping something because you don't use it is a short-sighted decision... please don't. > 2) Change the application to gracefully redirect to the online docs if > offline docs are missing OK this I agree with. > 3) Make a better "offline docs" build that adds the warning about docs > being out-of-date. Have packagers use this if they want to generate docs > packages, and maybe make it easy for anyone to download these from the > website. That potentially can clash with the package distribution of the local system. Instead it could be useful to have one more option: local installed docs. This is an example: User customizable docs access. Please select what do you prefer (you can always change it later): - Local system docs - Local user docs - On-line docs local user docs CAN be updated directly from on-line zips, and the process can be automated. In this way it won't be interferences with the system packages... Imagine a warning at Kicad start: "It seems that there are newer (more updated) docs on the kicad site than the version you installed system-wide. Do you want to download and install them locally and set the help option preference to access the local docs instead of the (older) system installed? Yes/no" > 4) Stop tagging the kicad-docs repo with every KiCad code release. > Instead, continue the new practice we have started of maintaining major > release branches for the docs (V5, V6, etc) and have packagers start > packaging the tip of these branches. I.e. the Ubuntu package for > kicad-docs will update every time something is pushed to the V6 branch as > long as V6 is the stable release, and so on. We cannot interfere with distro packaging policies. Every distro have a general politics for packaging and won't change that only for the kicad package. Obviously others, more general, packaging systems can be better taylored to follow our needs like, for instance, flatpacks... -- Saluton, 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
