GNOME Bugzilla – Bug 633550
Help and concepts guide are missing from the prebuilt binary (because xsltproc chokes on undefined entities)
Last modified: 2018-06-29 22:46:23 UTC
See this mailing list thread for the latest status: https://lists.gnucash.org/pipermail/gnucash-devel/2010-September/029588.html In short: it seems the Windows tool html help compiler (hhc.exe) crashes when it tries to convert the GnuCash help manual into Windows' native compressed html. Until the cause for this is found, the creation of the help manual on Windows has been disabled.
Until this is fixed, is it possible to provide plain HTML documentation and make it start up in the user's default browser when the user clicks on the Help > Contents menu item?
Should be. That's what I do for OSX.
(In reply to comment #2) > Should be. That's what I do for OSX. Hadn't realised that, very cool!
To rephrase the original bug again: The chm help files were disabled by me in http://svn.gnucash.org/trac/changeset/19607 because hhc.exe kept crashing and stopping the build every time. You can't see that directly in the logs, but http://code.gnucash.org/builds/win32/trunk/build-2010-09-23.log is the last log where we still ran "Processing help (C) ...". What happened is that it crashed after printing the following lines: > Searching for anchors ... > `htmlhelp.chm' -> `/c/soft/gnucash/inst/share/gnucash/help/C/gnucash-help.chm' > `htmlhelp.hhmap' -> `/c/soft/gnucash/inst/share/gnucash/help/C/gnucash-help.hhmap' The build didn't continue until Derek or myself logged into the computer and clicked away the "blabla has crashed" dialog box, after which the build continued as if nothing had happened. *This* is visible because of the significantly later wall clock time of when this log file was finally written (15:50h instead of 02:42h) To debug this, someone must set up a system to reproduce this crash, then try to tickle hhc.exe to print some debug message hinting towards the root of this crash. IIRC the last help build without such a crash was on 2010-09-14, but there wasn't any change in gnucash-docs/help/C after 2010-08-26 (twice gjanssens, but completely trivial and cannot have caused this crash) http://svn.gnucash.org/trac/log/gnucash-docs/trunk/help/C ; the next commit in help/C is r19615 on 2010-09-27 but the crash occurred already before that. Nevertheless as usual one debugging possibility is to go back in the help/C commits until it works again. Concerning a crashing hhc, http://svn.haxx.se/tsvn/archive-2006-01/0067.shtml says >> - Got an exception in hhc.exe together with the question from VS.net >> if I want to debug hhc.exe... > > I sometimes get that one too. If you get it all the time, you must > install language support for eastern languages Maybe this hints toward the right direction, but then again, it's help/C that's crashing and not, say, guide/jp_JP.
http://helpware.net/FAR/far_faq.htm#fail
Oops. I've been able to reproduce the crashing xsltproc.exe on some win32 system here. Turns out the crash has been caused by DLL hell again, but the solution is already in our SVN. In particular, xsltproc.exe depends on iconv.dll and zlib1.dll (both through libxml2.dll). Previously, our install.sh downloaded only the xsltproc and libxml2 package, but not the suitable iconv and zlib1. This resulted in some iconv.dll and zlib.dll being picked up from the patch, in our case from the gnome/bin directory. However, those were slightly wrong versions. Instead, we must ensure that xsltproc.exe picks up those two DLLs in exactly the right versions which were used when building xsltproc and libxml2. However, I discovered that already in September and fixed our install.sh accordingly in http://svn.gnucash.org/trac/changeset/19592 . On my win32 system, all that I had to do was to remove the ${LIBXSLT_DIR} folder so that the new download including iconv.dll and zlib.dll is done. After that, the crash disappeared and all run fine again. Hence, {Derek,Geert,myself} must log into our build server and remove the c:\soft\libxslt directory, then enable the line for the help/C processing again and check whether the build runs fine now.
Ok, I went in and removed the libxslt directory, enabled the English documentation processing again (in svn) and finally updated the packaging directory on the build server just to be sure. Tomorrow's build will tell us if it worked.
For the record, the build failed again, because xsltproc fails to load the dtd from the docbook website. As a result a number of entities aren't defined. We probably could work around this by downloading the dtd files ourselves (as part of the build scripts) and have xsltproc use the local version.
Ohhh. Indeed the docs build fails much earlier than with the help/C, but instead by the guide/C (the very first xml document to process). It fails because of undefined entities, even though we expected those entities to be valid HTML entities. I don't think this is related to the "failed to load external entity "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" warning; instead, somehow xsltproc just doesn't accept the HTML entities as we expected it. How can we fix that?
Actually I believe the failed loading of the dtd *is* the reason the html entities are not defined. To verify this, I have just ran some tests in my local build system. Using the xsltproc command as is in our build scripts, the documentation is not generated due to the missing html entities. Next I downloaded http://www.oasis-open.org/docbook/xml/4.1.2/docbkx412.zip and unpacked it. This file contains the dtd our documentation uses and a number of entity definitions that seem to be related. With this in place, I ran xsltproc --path <path to unzipped docbkx412> <path to the xslt> gnucash-guide.xml This ran successfully without any errors or warnings. So for some reason, xsltproc used to be able to go online and get the dtd and it currently isn't anymore. I don't know why that would be. Perhaps a Windows update that subtly changes the internet api's ? Depends.exe shows some issues with functions that have to do with network access at least, although I couldn't tell if this would be related. Having the dtd available locally at least solves the problem for me. I'll try to commit a change in that direction later today to see if it also fixes the problems on our build server.
Well, the dtd loading failed for a long time by now but it hasn't been the reason for stopping the build for a long time (e.g. http://code.gnucash.org/builds/win32/trunk/build-2010-06-09.log). Only after those entities were added by the docs writer we are running into xsltproc failure. Maybe you are right and if we get to have it loaded correctly, also the entities are defined correctly.
Indeed, you are right. The DTD download failed for a long time and the xsltproc errors appear for the first time when the html entities were introduced on September 27th. It appears we were lucky until then, because for some reason xsltproc finds the entity definitions where it finds the DTD. In commit r19827 I have added some code to download the dtd package, install it locally and have xsltproc use that location. With these changes, my windows build completes without errors. Let's see if the build server reacts the same way tonight.
Gee. Now finally we've finished this issue. Starting with the 2010-11-19 build (r19832), the docs are included fully again. This is impressively visible by the size of the win32 installer which now jumped from 62 MB to 91 MB again. Thanks Geert!
GnuCash bug tracking has moved to a new Bugzilla host. This bug has been copied to https://bugs.gnucash.org/show_bug.cgi?id=633550. Please update any external references or bookmarks.