On Sun, 2022-09-25 at 08:13 -0700, tony mancill wrote: > Hello Mathias, > > On Sat, Sep 24, 2022 at 02:51:57PM +0000, Mathias Gibbens wrote: > > I happened to build trustedqsl this morning, and linitian flagged > > that lots of documentation is being installed in an incorrect > > location (/usr/share/TrustedQSL/help/). Policy Section 12.3 states > > that "[a]dditional documentation included in the package should be > > installed under /usr/share/doc/package." > > This will require patching the upstream source. The help files are > used by the software at runtime and in this regard, I don't > necessarily consider them "additional documentation." The files are > part of the program. I'd disagree. Even if the program has a built-in help renderer, the underlying files do document how to use the program, its options and configuration, etc. You can open them up in a normal browser and they function properly, so there's nothing that specifically ties them to TrustedQSL as the only way to view them. I would hope any required patching would be a single line change of a path prefix. (Creating a symlink as mentioned below might avoid the need for any patch.) > > > Please update the packaging so documentation is installed in the > > proper location. > > Is there a usability concern or use case you are trying to address? > When you start TQSL, you should be able to access the documentation > via Help -> Display Documentation. Mostly it's just trying to ensure this package follows Debian's conventions and policies. If I as an end user am looking for documentation that's included in with the package, the first place I'll look is in /usr/share/doc/<package>; I wouldn't know to look in a non- standard directory. > > > Also, it's a bit weird to have the trustedqsl package installing > > files to /usr/share/TrustedQSL/ (note the difference in > > capitalization). > > I agree that the capitalization is not typical and perhaps a bit > unfortunate, but there are other precedents. I can't find anything > in policy that indicates that this is a problem. Looking at my > system, TrustedQSL is not the only example: I concur and like you didn't see anything specifically about capitalization requirements for that directory name -- just noting it's atypical. > > We can certainly update the package, but I am not sure what bug we > are trying to address. For the lintian warning, we can add an entry > to lintian-overrides. I'd not like that approach. Usually lintian flags legitimate issues and sweeping them under the rug via overrides seems less than ideal. > > In addition to that, perhaps adding a symlink from > /usr/share/doc/trustedqsl/help -> /usr/share/TrustedQSL/help/tqslapp > would help users find the documentation who would prefer to use > another mechanism to access it? It appears to render correctly via a > web browser pointed at: > file:///usr/share/TrustedQSL/help/tqslapp/index.htm I'd suggest doing the inverse -- install the help files to /usr/share/doc/TrustedQSL/help/, and then symlink that directory to /usr/share/TrustedQSL/help/tqslapp/. That would install the documentation in a Policy-compliant location and also remove the need to patch the upstream source to point it to a different documentation directory. Mathias
Attachment:
signature.asc
Description: This is a digitally signed message part