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 <[email protected]> wrote: > 2015-05-18 1:55 GMT+02:00 Blair Bonnett <[email protected]>: > > On 18 May 2015 at 10:44, Melroy van den Berg <[email protected] > 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
_______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : [email protected] Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
