Re: [GNC-dev] yelp and khelpcenter
Am 07.09.19 um 18:15 schrieb Geert Janssens: > Yes. GnuCash is a still geared towards the gnome facilities, so yelp is > normally installed for help. There's currently no way to integrate our > documentation in the kde help system. > > I will add for completeness both yelp and khelpcenter can also display html > based documentation. So these platforms are not forcing us to stick with > docbook as base documentation format. But that's of course a totally different > discussion. AFAIK both use XML (docbook and derivates) as primary source format and render them as HTML, but can also output HTML files. While "developing docs" one benefit is, they can display your changes by a simple reload - without waiting minutes before 'make/ninja html' finish. If we can get our docs in both apps by * adding a metafile (.omf or .desktop) at the right place and * probably reordering component and language of the path it would be worth the effort. BTW I prefer to stick with docbook as source format as it is well defined and we have the validation by xmllint. To illustrate it, just compare gnucash (docbook) with the from the content ways less complex gnucash-htdocs (HTML in variants 1.0 - xhtml) with some PHP glue, which is almost unmaintainable. When I the last time tried https://validator.w3.org/check, I gave up after 2 days of fixing. –Frank ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] CMake build system for gnucash-docs
Op donderdag 5 september 2019 10:11:06 CEST schreef Frank H. Ellenberger: > Hi, > > Am Mi., 4. Sept. 2019 um 19:19 Uhr schrieb Geert Janssens > > : > > Op woensdag 4 september 2019 18:44:14 CEST schreef Frank H. Ellenberger: > > > 2.3 Replace of over a decade outdatet GDP parts: I estimate 99% of xsl > > > came from them and I suspect it for many output glitches. Also many > > > docs contain their templates "Do not remove..." > > > GDP has been the Gnome1 ancestor of GDU, which ended with Gnome2. And > > > from there came also the OMF generation. But OMF should not simply be > > > dropped but replaced by other forms of metadata like e.g. .desktop > > > files. > > > > If you have more details on these, I'm interested. > > After hours I found the main part of my previous research in > https://wiki.gnucash.org/wiki/Gnome_Doc_Utils Thanks. I ran across that page a few days ago as well. > At least as long as a cleanup is not finished, I would prefer to keep > autotools to run experiments. I'm trying to understand what exactly you want to do with our documentation that is still related to GDP ? The xsl base files come from the docbook project with a few amendments in a higher level directory. Are those amendments originally from GDP or it's predecessor ? In the wiki page you refer to merging templates into our documentation files. Does that mean our documents follow an outdated template structure and you want to update them to follow a newer structure ? > > I don't see how .desktop files would replace the .omf file ? Where is that > > currently being used ? > See e.g. https://github.com/KDE/khelpcenter/README.metadata Ah. We have never formally supported KDE's khelpcenter. GnuCash is currently still very much a Gnome oriented application. KDE's help and Gnome's help are not compatible. I personally don't see much gain in trying to support this currently. Our application itself expects to find the documentation in the Gnome's help specific locations. Adding support for this in gnucash would mean adding KDE as an extra target platform with its own set of specific customizations. While this is a nice thought (I have even considered this in the past), doing this only to be able to open help in KHelpcenter from within gnucash is a bit silly. There's also the other entry point, where a user wants an easy way to open the gnucash documentation easily from within the KHelpCenter. That would again require our application's desktop file to be altered with KDE help specific extensions. And then we'd have to install a copy of our documentation under /usr/share/doc/HTML instead of /usr/share/help Again I'm not sure of the benefit of adding support for all that at this point. I think more interesting areas of study could be whether we can support a Macos native document format or whether the Windows help system has a way of identifying application documentation system-wide (that is outside of the application) and whether we need to add something to tap into that. Those are two platforms we do try to integrate with next to our gnome integration. As an aside, I have been experimenting a bit to adjust our documentation to adhere to the xdg help specification https://www.freedesktop.org/wiki/Specifications/help-spec/ That is what yelp currently considers its main documentation location specification. That would require us to change the installation location from /usr/share/gnome/help// to /usr/share/help// and rename the main files from gnucash-guide.xml and gnucash-help.xml to index.docbook A first and incomplete experiment is here: https://github.com/gjanssens/gnucash-docs/tree/xdghelp In there I did the first part of the above changes. I believe making the full transition is best done for master only as it also requires our application to use help: instead of ghelp: to continue to find its documentation. Regards, Geert ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] CMake build system for gnucash-docs
Op zaterdag 7 september 2019 16:04:08 CEST schreef John Ralls: > > On Sep 7, 2019, at 5:44 AM, Geert Janssens > > wrote: > > > > Again I'm not sure of the benefit of adding support for all that at this > > point. I think more interesting areas of study could be whether we can > > support a Macos native document format or whether the Windows help system > > has a way of identifying application documentation system-wide (that is > > outside of the application) and whether we need to add something to tap > > into that. Those are two platforms we do try to integrate with next to > > our gnome integration. > MacOS Help's native format is HTML just like everyone else's, packed in a > peculiar way just like everyone else's. It displays in an obnoxious window > that stays on top of everything. Many third-party applications do what > GnuCash already does, which is to use the user's default browser to display > help. As for Windows I've noticed that very few Windows 10 applications > still use the old Windows-3 help viewer. Most, including Microsoft's, > either display help in their own window or use the default browser. > Good point. > Maybe we should follow that trend and get rid of *all* of the system/desktop > environment specializations and just open docs in a GtkWebKitView like we > do reports... alternatively given the troubles with WebKit maybe we should > switch to using the default browser for both reports and docs. A few remarks: * For Windows and Macos publishing the documentation as html is probably a good way to go for the future, though I find our plain html output a bit bland. If we want to make that our main format, it could do with some well- written css for a nicer visual presentation. * While on Windows and Macos it may be common to just open a webbrowser with html pages, in the gnome and kde ecosystem the native help browser remains very popular (yelp and khelpcenter respectively). So I wouldn't drop support for ghelp just yet. * Opening an external browser for reports will solve our WebKit troubles at the expense of backlinks into the rest of the gnucash data. Some reports have links that refer to a register page, an invoice, another report... All of those can only be handled because we integrate a webviewer inside the application. Regards, Geert ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] CMake build system for gnucash-docs
With my last set of commits I believe the CMake build system for gnucash-docs now matches the autotools build system (modulo the scrollkeeper info that's not used by gnome's help system any more). To use it: - clone gnucash-docs and check out the maint branch - make a build directory somewhere and cd into it - run: cmake -DCMAKE_INSTALL_PREFIX= \ That configures the build system. Note you can leave out the CMAKE_INSTALL_PREFIX if you don't intend to install the documentation. It's normally not needed unless you are a software packager as the build will replicate the installation locations in the build directory. On all platforms except Windows the build system will enable these document formats by default: * html: a set of html documents (used by the gnucash website) * epub * pdf * ghelp: the documentation format and installation locations for use with the gnome help system On Windows, by default only the chm format is enabled (the Windows native help format). You can control which formats to enable/disable by setting the following flags on the cmake command line: -DWITH_HTML -DWITH_EPUB -DWITH_MOBI -DWITH_PDF -DWITH_GHELP -DWITH_CHM For example cmake -DWITH_PDF=OFF -DWITH_MOBI=ON will configure the build system without pdf support and with mobipocket support. Acutally generating the documentation involves running "make" or "ninja" (if you had passed "-G Ninja" to the cmake command). There is no default target, which means just running "make" or "ninja" will do nothing. Instead you have to specify which document to build in which language and which document format. There are more generic targets to build a document in a given format for all languages and even more generic targets to build all documents in all languages in a specific document format as well. To see all available targets, the easiest is to run make help (or ninja-help) A few examples * to build the gnucash guide as html in German make de-gnucash-guide-html * to build all help documentation in pdf make gnucash-help-pdf * to build all documentation in epub make epub There is also a check target (and the subtargets -check and - -check) to run xmllint on the source files. Specifically for document writers working on linux, the ghelp target (or one of the subtargets -ghelp and --ghelp) will come in handy: these targets will install the document sources in the build directory in paths that can be used to test the documentation with yelp. More specifically, the documentation will be installed under /share/gnome/help/// By adding /share to the XDG_DATA_DIRS environment variable yelp will pick up the copy of the documentation that's installed there. For example to open your version of the German language gnucash-help on the command line: LANG=de XDG_DATA_DIRS=/share:$XDG_DATA_DIRS yelp ghelp:gnucash-help A few other targets that are less relevant unless you're a packager: * install: this is only implemented for ghelp (to be included in linux distribution packages) and chm (to be included in the Windows installer). Note if both the ghelp and the chm targets are configured, install will install both. This can be avoided by setting environment variable "CMAKE_INSTALL_COMPONENT" to one of "ghelp" or "chm". As the chm and ghelp targets are normally not enabled together by default this is usually not necessary. * uninstall: does the opposite of install * dist, distcheck: two targets for the release manager Please test and give feedback. Regards, Geert Op maandag 2 september 2019 19:29:00 CEST schreef Geert Janssens: > Over the weekend I spent a few cycles to port the gnucash-docs autotools > build system to cmake. > > Most of it is done and can be played with by checking out the current maint > branch on gnucash-docs. > The main missing elements are: > - generating the Windows specific chm files > - uninstall rules > - omf/scrollkeeper/rarian support > > The last one is easy: I don't intend to add this. It was there because old > versions of yelp (<2.23) required it. No platform we care about still uses > that old yelp version so omf is obsolete. > > The other two will follow hopefully somewhere next week. > > Other than that there are a few important changes between the autotools > system and the cmake system. The most important one is that autotools > provided a fully self-contained Makefile in each document directory. Cmake > on the other hand works with a single top-level makefile (or ninja ruleset > if you prefer). > > That is, with autotools you could > cd guide/C > make html > And that would build you the html version of the English guide > > This is not possible in cmake. However I have tried to provide equivalent > targets instead wherever possible. So to achieve the above you can instead > do make C-gnucash-guide-html > > The targets are always named > -- > > So similarly you will find > de-gnucash-help-pdf > pt-gnucash-help-epub > ja-gnucash-guide-mobi > > and
Re: [GNC-dev] CMake build system for gnucash-docs
> On Sep 7, 2019, at 7:14 AM, Geert Janssens wrote: > > Op zaterdag 7 september 2019 16:04:08 CEST schreef John Ralls: >>> On Sep 7, 2019, at 5:44 AM, Geert Janssens >>> wrote: >>> >>> Again I'm not sure of the benefit of adding support for all that at this >>> point. I think more interesting areas of study could be whether we can >>> support a Macos native document format or whether the Windows help system >>> has a way of identifying application documentation system-wide (that is >>> outside of the application) and whether we need to add something to tap >>> into that. Those are two platforms we do try to integrate with next to >>> our gnome integration. >> MacOS Help's native format is HTML just like everyone else's, packed in a >> peculiar way just like everyone else's. It displays in an obnoxious window >> that stays on top of everything. Many third-party applications do what >> GnuCash already does, which is to use the user's default browser to display >> help. As for Windows I've noticed that very few Windows 10 applications >> still use the old Windows-3 help viewer. Most, including Microsoft's, >> either display help in their own window or use the default browser. >> > Good point. > >> Maybe we should follow that trend and get rid of *all* of the system/desktop >> environment specializations and just open docs in a GtkWebKitView like we >> do reports... alternatively given the troubles with WebKit maybe we should >> switch to using the default browser for both reports and docs. > > A few remarks: > * For Windows and Macos publishing the documentation as html is probably a > good way to go for the future, though I find our plain html output a bit > bland. If we want to make that our main format, it could do with some well- > written css for a nicer visual presentation. > * While on Windows and Macos it may be common to just open a webbrowser with > html pages, in the gnome and kde ecosystem the native help browser remains > very popular (yelp and khelpcenter respectively). So I wouldn't drop support > for ghelp just yet. I guess that's OK for Yelp, but as you pointed out to Frank we don't support KHelpCenter. Do we require KDE users to install Yelp so that we can display our docs? > * Opening an external browser for reports will solve our WebKit troubles at > the expense of backlinks into the rest of the gnucash data. Some reports have > links that refer to a register page, an invoice, another report... All of > those can only be handled because we integrate a webviewer inside the > application. Roger, but the way things are headed on Windows the choice may be between having the links and being able to display reports at all: https://bugs.gnucash.org/show_bug.cgi?id=797283 On that note, I tried to build mingw-w64-webkitgtk on the current mingw32. It fails with a symbol not found error linking libjavascript.dll which is probably why Alex decided to drop it. I'll poke at it a bit more after the release, but it's yet another indication that we need to find a different solution for displaying reports on Windows. Regards, John Ralls ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] CMake build system for gnucash-docs
Op zaterdag 7 september 2019 17:56:46 CEST schreef John Ralls: > > On Sep 7, 2019, at 7:14 AM, Geert Janssens > > wrote:> > > Op zaterdag 7 september 2019 16:04:08 CEST schreef John Ralls: > >>> On Sep 7, 2019, at 5:44 AM, Geert Janssens > >>> wrote: > >>> > >>> Again I'm not sure of the benefit of adding support for all that at this > >>> point. I think more interesting areas of study could be whether we can > >>> support a Macos native document format or whether the Windows help > >>> system > >>> has a way of identifying application documentation system-wide (that is > >>> outside of the application) and whether we need to add something to tap > >>> into that. Those are two platforms we do try to integrate with next to > >>> our gnome integration. > >> > >> MacOS Help's native format is HTML just like everyone else's, packed in a > >> peculiar way just like everyone else's. It displays in an obnoxious > >> window > >> that stays on top of everything. Many third-party applications do what > >> GnuCash already does, which is to use the user's default browser to > >> display > >> help. As for Windows I've noticed that very few Windows 10 applications > >> still use the old Windows-3 help viewer. Most, including Microsoft's, > >> either display help in their own window or use the default browser. > > > > Good point. > > > >> Maybe we should follow that trend and get rid of *all* of the > >> system/desktop environment specializations and just open docs in a > >> GtkWebKitView like we do reports... alternatively given the troubles > >> with WebKit maybe we should switch to using the default browser for both > >> reports and docs. > > > > A few remarks: > > * For Windows and Macos publishing the documentation as html is probably a > > good way to go for the future, though I find our plain html output a bit > > bland. If we want to make that our main format, it could do with some > > well- > > written css for a nicer visual presentation. > > * While on Windows and Macos it may be common to just open a webbrowser > > with html pages, in the gnome and kde ecosystem the native help browser > > remains very popular (yelp and khelpcenter respectively). So I wouldn't > > drop support for ghelp just yet. > > I guess that's OK for Yelp, but as you pointed out to Frank we don't support > KHelpCenter. Do we require KDE users to install Yelp so that we can display > our docs? > > * Opening an external browser for reports will solve our WebKit troubles > > at > > the expense of backlinks into the rest of the gnucash data. Some reports > > have links that refer to a register page, an invoice, another report... > > All of those can only be handled because we integrate a webviewer inside > > the application. > > Roger, but the way things are headed on Windows the choice may be between > having the links and being able to display reports at all: > https://bugs.gnucash.org/show_bug.cgi?id=797283 > > On that note, I tried to build mingw-w64-webkitgtk on the current mingw32. > It fails with a symbol not found error linking libjavascript.dll which is > probably why Alex decided to drop it. I'll poke at it a bit more after the > release, but it's yet another indication that we need to find a different > solution for displaying reports on Windows. Yes, agreed. I have been thinking to deal with it the way wxWidgets does [1]: on linux it links webkit for it's htmlview, on Windows it links to Windows' own html component. As our htmlbackend is swappable we may be able to do a similar thing for gnucash. That's the idea, but I haven't had time so far to try this. Regards, Geert [1] https://docs.wxwidgets.org/3.0/classwx_web_view.html ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] CMake build system for gnucash-docs
Op zaterdag 7 september 2019 17:56:46 CEST schreef John Ralls: > > On Sep 7, 2019, at 7:14 AM, Geert Janssens > > wrote:> > > Op zaterdag 7 september 2019 16:04:08 CEST schreef John Ralls: > >>> On Sep 7, 2019, at 5:44 AM, Geert Janssens > >>> wrote: > >>> > >>> Again I'm not sure of the benefit of adding support for all that at this > >>> point. I think more interesting areas of study could be whether we can > >>> support a Macos native document format or whether the Windows help > >>> system > >>> has a way of identifying application documentation system-wide (that is > >>> outside of the application) and whether we need to add something to tap > >>> into that. Those are two platforms we do try to integrate with next to > >>> our gnome integration. > >> > >> MacOS Help's native format is HTML just like everyone else's, packed in a > >> peculiar way just like everyone else's. It displays in an obnoxious > >> window > >> that stays on top of everything. Many third-party applications do what > >> GnuCash already does, which is to use the user's default browser to > >> display > >> help. As for Windows I've noticed that very few Windows 10 applications > >> still use the old Windows-3 help viewer. Most, including Microsoft's, > >> either display help in their own window or use the default browser. > > > > Good point. > > > >> Maybe we should follow that trend and get rid of *all* of the > >> system/desktop environment specializations and just open docs in a > >> GtkWebKitView like we do reports... alternatively given the troubles > >> with WebKit maybe we should switch to using the default browser for both > >> reports and docs. > > > > A few remarks: > > * For Windows and Macos publishing the documentation as html is probably a > > good way to go for the future, though I find our plain html output a bit > > bland. If we want to make that our main format, it could do with some > > well- > > written css for a nicer visual presentation. > > * While on Windows and Macos it may be common to just open a webbrowser > > with html pages, in the gnome and kde ecosystem the native help browser > > remains very popular (yelp and khelpcenter respectively). So I wouldn't > > drop support for ghelp just yet. > > I guess that's OK for Yelp, but as you pointed out to Frank we don't support > KHelpCenter. Do we require KDE users to install Yelp so that we can display > our docs? Yes. GnuCash is a still geared towards the gnome facilities, so yelp is normally installed for help. There's currently no way to integrate our documentation in the kde help system. I will add for completeness both yelp and khelpcenter can also display html based documentation. So these platforms are not forcing us to stick with docbook as base documentation format. But that's of course a totally different discussion. Geert ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] CMake build system for gnucash-docs
> On Sep 7, 2019, at 5:44 AM, Geert Janssens wrote: > > Again I'm not sure of the benefit of adding support for all that at this > point. I think more interesting areas of study could be whether we can > support > a Macos native document format or whether the Windows help system has a way > of > identifying application documentation system-wide (that is outside of the > application) and whether we need to add something to tap into that. Those are > two platforms we do try to integrate with next to our gnome integration. MacOS Help's native format is HTML just like everyone else's, packed in a peculiar way just like everyone else's. It displays in an obnoxious window that stays on top of everything. Many third-party applications do what GnuCash already does, which is to use the user's default browser to display help. As for Windows I've noticed that very few Windows 10 applications still use the old Windows-3 help viewer. Most, including Microsoft's, either display help in their own window or use the default browser. Maybe we should follow that trend and get rid of *all* of the system/desktop environment specializations and just open docs in a GtkWebKitView like we do reports... alternatively given the troubles with WebKit maybe we should switch to using the default browser for both reports and docs. Regards, John Ralls ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
