← Back to team overview

kicad-developers team mailing list archive

Re: V6 documentation


On 1/19/22 02:16 PM, Jon Evans wrote:

On Wed, Jan 19, 2022 at 2:12 PM Steven A. Falco <stevenfalco@xxxxxxxxx <mailto:stevenfalco@xxxxxxxxx>> wrote:

    Not to put words in your mouth, but it sounds like the code will be changed so that when someone clicks on the Help menu, they will get the on-line version, if possible.
    And only if the on-line version cannot be accessed, the code would then automatically fall back to the off-line (local) version.  Do I have the proposal correct?  If so, I like it.

Yes, something like that.  But, instead it could be to use the offline version if present, and fall back to the online version if absent.  Then it would be up to the packager to decide whether or not to include the offline docs (I'd propose to drop them from the Windows and Mac packages that we provide).

    It might also be good to have a warning somewhere, perhaps in the off-line version itself, that it is not necessarily current, along with a suggestion to go retrieve the on-line version manually.

Yes, I think this is important, just have to figure out how to add it to the generated documentation but not the website.

    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 am not trying to break any distro's packaging requirements for the sake of making people's lives hard, I am just trying to make it so the average KiCad user who has access to the online docs finds them first.

Maybe one option would be to not install the documentation package by default when the user selects the main kicad package.  That way, a user who just installs kicad will get the online docs redirect, and one who cares about offline docs can manually install the extra package?

That is how things are packaged right now, both for Fedora nightlies and for Fedora downstream (official) packages.  We build three packages:

1) main program + all libraries except 3d (because it is huge)

2) docs

3) 3d library

So nobody has to install the docs.  As long as the off-line docs indicate that there may be more current on-line docs, that should be fine.