GNOME Bugzilla – Bug 726146
Handle missing documentation more gracefully
Last modified: 2018-06-29 23:28:11 UTC
After filing a Debian bug about the huge size of gnucash-docs https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=741175 - I was told that "Recommends is the right dependency level, because otherwise some menu items won't work." It seems bizarre that a default install pulls in a documentation set that is many times greater than the original package (the actual gnucash package is only 2.3MB), just because the app itself errors when the ondisk documentation is not present. Suggestion: when the user clicks a menu item that requires documentation, instead of presenting an error, gnucash could instead detect that the ondisk documentation is not present, and inform the user that they will be directed to the online documentation and that this will be done automatically in the future (so the user does not get this message every time they click the menu option). There would be a config option somewhere in preferences to use the online docs instead, so the user can change this back in the future if they wish.
No! Have them only online is definitely the wrong way. There are still region on this planet with no or very bad connectivity. The package has only ~ 53 MB. For 139 MB you were perhaps adding the symlinks up. The package is a recommendation, no dependency: You should have read the guide before starting real work. If it really matters, you could remove unused languages. In theory the maintainers could split it in 1. help and guide 2. per language, but are that 10¢ disk space worth their work?
> Have them only online is definitely the wrong way. I did not say the docs should be "only online". I said the user should have the option, and gnucash should behave sensibly if the user chooses not to install the docs. > There are still region on this planet with no or very bad connectivity. Yes, and that is why making the default install download a huge docs package that most users don't need is a bad idea. Many people don't have fast broadband, or are using mobile connections, so minimising the install size is important. FYI, I actually encountered this issue when attempting to install gnucash in a developing nation, and downloading such a huge amount of data would have taken me several days. > The package has only ~ 53 MB. For 139 MB you were perhaps adding the symlinks up. No. At the time I filed the bug it was 139MB - following my bug report, the Debian maintainer then managed to slim it down to 85MB, with an installed size of 96MB, see https://packages.debian.org/jessie/doc/gnucash-docs : Download gnucash-docs Architecture Package Size Installed Size Files all 85,508.0 kB 96,645.0 kB [list of files] > The package is a recommendation, no dependency: You should have read the guide before starting real work. 1. It is a hard dependency on Fedora and RedHat. The reason for this is that gnucash generates errors when the docs are not present, so it is considered a bug that the docs aren't installed. 2. It is important to have sensible defaults. Even 85MB of documentation, as default, is too much. Imagine if every program came with 85MB of documentation... 3. If the docs are not installed, then gnucash itself generates errors when it tries to access the docs (this was considered a bug by the Debian maintainer, which is why the requirement for the docs was added). That was the point of this bug report - other apps handle this much better - Handbrake, for example, follows the suggested behaviour of first checking for the docs on the local disk, and if not present, offers to open docs on the web site. > If it really matters, you could remove unused languages. This is not possible for a user, as all of the languages are bundled into a single package. > but are that 10¢ disk space worth their work? It is not about the cost of disk space, it's about cutting bloat from the default install. As you pointed out, there are "still regions on this planet with no or very bad connectivity.". Even in developed nations, the cost of data can be prohibitive (85MB on a typical payg mobile is about US$7 here). Are there any other apps that come with 85MB of documentation in the default install? Perhaps there are some, but it is the exception rather than the rule.
OK, I reopen it, but can not set the status to need info. From what I see at https://packages.debian.org/jessie/doc/gnucash-docs: "These documents are available in HTML, PDF and DocBook formats (the latter is intended to be viewed with the GNOME Help browser)." Sebastien, are you packaging all target formats in one package? By default the package should only build docbook (with the yelp dependency) - on Linux. The other format targets are primarly for view (HTML) them on or download (PDF, epub, mobi) them from http://gnucash.org/docs.phtml. If you think you should build them too, I would suggest to split them in separate packages like gnucash-docs-html, gnucash-docs-pdf ... Perhaps we should add that section to the readme file? I never heard from crashes by missing help files. If that is still the case and not caused by other components like yelp, file a separate bug against the GUI component, referencing this bug report and ideally with a stacktrace with debug symbols. [http://wiki.gnucash.org/wiki/Stacktrace] "other apps handle this much better - Handbrake, for example, follows the suggested behaviour of first checking for the docs on the local disk, and if not present, offers to open docs on the web site." If you like, file a separate enhancement request against component GUI.
Just for completeness, the original summary was: gnucash-docs should not be required on disk, gnucash should redirect to online docs when not present Setting need info.
> I never heard from crashes by missing help files. It's not a crash, just an error: "Document Not Found The URI ‘ghelp:gnucash-help’ does not point to a valid page." There is a link to "search for packages containing this document", clicking on the link brings up another error dialog "You do not have PackageKit. Package install links require PackageKit."
(In reply to comment #3) > Sebastien, are you packaging all target formats in one package? Yes. > By default the package should only build docbook (with the yelp dependency) - > on Linux. > The other format targets are primarly for view (HTML) them on or download (PDF, > epub, mobi) them from http://gnucash.org/docs.phtml. If you think you should > build them too, I would suggest to split them in separate packages like > gnucash-docs-html, gnucash-docs-pdf ... That could be a possibility, though I am not sure it's worth the extra effort. If someone has strong opinions about this, please file a bug against the package in the Debian bug tracking system.
Ok time for a summary: 1. The debian gnucash-docs package is huge because it not only ships the documentation in docbook format but also pdf, epub,.. 2. If no documentation is found, gnucash' error message is rather unhelpful, or actually yelp's error message is. 3. Because of this unhelpful error message several distributions consider the gnucash-docs package mandatory/recommended which in practice means both will always be installed together. 4. To break this dependency the request is to change gnucash such that it will offer online documentation if gnucash-docs is not installed. So... Point 1. is a debian decision, which we can't do much about. Personally I like Frank's proposal to split the docbook format from the other formats as that would indeed reduce the download size considerably. Other than that I'll leave this discussion to the Debian community. Point 2. gets to the core of the issue. GnuCash is totally unaware of whether or not its documentation has been installed. It just hands the request to yelp. If yelp can't find the requested documentation, it reports this generic error message. Unfortunately yelp does not report this problem to gnucash, so gnucash can't know whether or not the request to show the information was successful. Point 3. is at the discretion of the distributions. Point 4. could be a reasonable user experience improvement. That would require to first find a solution for the issue of yelp not reporting failures to gnucash. Or we should drop yelp altogether and find our own way to display the help. We already do on Windows (using Windows' native html help system) or OS X (I believe it refers to the online documentation). Anyway I have removed the status NEEDINFO. That info has been provided.
Oh and renaming the bug again to reflect the only remaining gnucash issue.
GnuCash bug tracking has moved to a new Bugzilla host. The new URL for this bug is https://bugs.gnucash.org/show_bug.cgi?id=726146. Please continue processing the bug there and please update any external references or bookmarks.