Packaging opencpn: what about the docs?

[Sebastiaan Couwenberg]

On 9/17/18 9:42 AM, Alec Leamas wrote:
> Dear list,

Discussion should be on the debian-gis at l.d.o list. This list is for
commits and package related notifications.

> Still working w opencpn. There are two dependencies in the pipe: unarr
> and wxcurl. unarr seems ok (?),  wxcurl is as of now a draft (but
> available in the salasa repo). Will try to get the last dependency wxsvg
> rolling.
> 
> As for opencpn, the documentation is a problem. The package contains a
> html manual which triggers lintian diagnostics, the most significant is
> a E: source-is-missing and a companion
> insane-line-length-in-source-file. There are also some js-related
> warnings, probably not that hard to patch.

How can we reproduce this issue?

HTML documentation should be fine. Source for javascript files used in
the HTML can be added in the missing-sources directory.

> It all stems from the fact that the documentation is generated from a
> wiki site. This process is not really open to the regular open-source
> workflow since the site's sources are not available.
> 
> I have raised the issue at upstream [1]. The conclusion is that the wiki
> source will not be available in some public space. As I see it, it
> leaves me with some alternatives, none of which really attractive.
> 
>   - Accept the situation, package the docs and override the lintian
> warnings. Obviously, many packages does this [2]
> 
>   - Skip packaging the docs, and have users downloading them from
> opencpn website. Note that opencpn users possibly are sailing with slow
> or no internet connection...
> 
>   - Try to use the new docs published in epub format. This will probably
> not generate any lintian diagnostics, but the underlying problem is the
> same (but perhaps editing the epub format is easier?)
> 
> Thoughts?

Documentation should be plain text or similar common format (e.g. HTML).
EPUB is not a good choice for documentation in a package. It can be
provided in addition to plain text or HTML, but not by itself.

Please move this discussion to the debian-gis list, and include the
procedure how the opencpn package can be built to reproduce the lintian
issue. This most likely requires you to push your changes to the opencpn
repo on Salsa or provide a source package elsewhere.

Kind Regards,

Bas

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <http://alioth-lists.debian.net/pipermail/pkg-grass-devel/attachments/20180917/e2fea452/attachment.sig>