kicad-developers team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxxx>]

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