kicad-developers team mailing list archive

[Blair Bonnett <blair.bonnett@xxxxxxxxx>]

Sorry for the slow response, things have been rather busy here.

@Nick - I think we're saying the same thing; my initial message was a bit
unclear. My issue is not with the concept of the patch, but with the
off-topic suggestion of using the online docs as the default source.

On 18 May 2015 at 18:12, Nick Østergaard <oe.nick@xxxxxxxxx> wrote:
> 2015-05-18 1:55 GMT+02:00 Blair Bonnett <blair.bonnett@xxxxxxxxx>:
> > On 18 May 2015 at 10:44, Melroy van den Berg <webmaster1989@xxxxxxxxx
> wrote:
> >> Off-topic:
> >>>
> >>> It would be nice if online documentation becomes the default.
> >>> This way the users always read the latest version of the
documentation.
> >>>
> >
> > I would be opposed to this for two reasons:
> >
> > * It would be very hard to ensure the version of the online docs
matches the
> > installed version of KiCad. Maybe straightforward enough for release
> > versions, but with people running nightly builds etc this could get
tricky.
>
> That is an issue, but considering that a release will have the docs
> packaged, it should be available locally, and hence you get the
> correct docs. The getting from latest Jenkins on the internet is
> mostly usefull for people running nightlies and building bare bones.

Agreed. That is why the patch's concept is a good one. But throwing people
to the online docs when they have a local version isn't IMO.


> > * We'd have to check for network connectivity and try to fall back to
local
> > docs if the internet is not available (and yes, I have used KiCad
without an
> > internet connection before).
>
> Why do we need to check for network connectivity, the browser will do
> that and report to the user.  I mean, I would say it should search
> local docs first, then fallback to the online docs.

If we switch to using the online documentation as the default source (not
in the current patch, but Melroy's off-topic thought), then we'd have this
problem. Basically, if I was working offline, then asking for the docs
would fire up Chrome with the appropriate URL, but then Chrome would tell
me it couldn't connect to the page. However, KiCad wouldn't know this and
so couldn't fall back to the local docs. Again, not an issue with the
current patch but with the suggestion of online docs being the primary
source.


> > Any decent prebuilt package should either have the corresponding docs
> > included, or (e.g., for Linux package managers) have a separate
kicad-docs
> > package that is optional but recommended. I think it is reasonable to
assume
> > that people compiling it themselves are capable of building the docs
> > themselves, or falling back to the online version.
>
> People building themselves might not be interested in building the
> docs, when they are already directly avaliable online.

Exactly. That's why I like the idea of the patch (again, haven't looked at
the code in the patch yet). If somebody builds the code themselves, and
chooses to use the online docs, thats fine. But if we switch to the online
docs being the default, then somebody who does build the docs, or who does
install a kicad-docs package, then they'll be confused as to why the local
ones aren't being used.


> > Maybe we should consider embedding the version of KiCad the docs are
written
> > for into the HTML output (e.g., into any title page and at the top of
the
> > table of contents?) to make it easy for people to check.
>
> What do you mean here? I guess you want the triplet to be written, but
> what about the development docs?

Maybe the triplet for docs released with a stable version (see issue 63 [1]
on the docs repository and the message Brian posted to the list [2] about
version numbering for the docs), and the current bzr revision number at the
time of build for development docs (or the previous triplet plus the
revision number)? Its not an easy thing to get perfect. Basically, there
needs to be some indication to the user whether the docs were intended for
their version of KiCad, or if there may be some differences.

Blair

[1] https://github.com/ciampix/kicad-doc/issues/63
[2] https://lists.launchpad.net/kicad-developers/msg18385.html