kicad-developers team mailing list archive

[Nick Østergaard <oe.nick@xxxxxxxxx>]

Apparently I did not forward this to the list while replying to Blair.

---------- Forwarded message ----------
From: Nick Østergaard <oe.nick@xxxxxxxxx>
Date: 2015-05-18 8:12 GMT+02:00
Subject: Re: [Kicad-developers] [PATCH] Add online documenation URL to the menu
To: Blair Bonnett <blair.bonnett@xxxxxxxxx>


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:
>>
>> I created a patch which opens the online documentation page in the
>> web-browser, only
>>  when the local help file could not be found.
>>
>> This way the user don't get the pop-up message: 'PDF could not be found'.
>> Instead they can read the latest successfully build documentation online
>> :).
>
> I've only glanced at the patch, but I like the concept.
>
>> 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.

> * 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.

> 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.

> 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?

> Regards,
> Blair
>
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp
>