Re: [GNC-dev] CMake build system for gnucash-docs

2019-09-07 Thread John Ralls



> On Sep 7, 2019, at 9:08 AM, Geert Janssens  wrote:
> 
> 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.
> 

I've been sort-of pondering that. MacOS also uses WebKit, Apple being the 
principal WebKit developers, and the latest Edge browser from Microsoft is 
built on Chromium which is pretty much WebKit with a different Javascript 
interpreter. The trick for both Windows and MacOS will be to get the rendered 
page drawn on a cairo surface to pass to GtkDrawingArea.

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

2019-09-07 Thread Geert Janssens
I forgot to mention  the new cmake build system for gnucash-docs even works 
with ninja on Windows though it doesn't seem to affect build times much.

Geert


Op zaterdag 7 september 2019 15:42:37 CEST schreef Geert Janssens:
> 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
> 



___
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

2019-09-07 Thread Geert Janssens
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

2019-09-07 Thread Geert Janssens
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

2019-09-07 Thread 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.

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

2019-09-07 Thread Geert Janssens
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

2019-09-07 Thread 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.

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


Re: [GNC-dev] CMake build system for gnucash-docs

2019-09-07 Thread Geert Janssens
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

2019-09-07 Thread Geert Janssens
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

2019-09-05 Thread 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
At least as long as a cleanup is not finished, I would prefer to keep
autotools to run experiments.

> 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

> Geert

~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

2019-09-04 Thread Geert Janssens
Op woensdag 4 september 2019 18:44:14 CEST schreef Frank H. Ellenberger:
> Dear Geert,
> 
> I currently see no reason to do this now
> - release this weekend - and

There's no impact on release. The autotools build system is still in place and 
unchanged. The cmake build system should be seen as a tech preview. Interested 
people can test it and provide feedback. CMake was introduced in the same way 
in the 2.6 release series and then made default in 3.x. I'm planning the same 
steps for docs. If we can successfully reproduce all the autotools 
capabilities, it hope it cmake to become to default for the 4.x series.

> am also tired to rewrite the related wiki parts.

I'm sorry to hear that. Nobody says you have to of course. This is a volunteer 
project after all. And for clarity your work *is* appreciated.
For me migrating docs to cmake follows naturally from migrating code to cmake. 
It has always been my intention to end up with one build system only. It 
should reduce the amount of build system documentation we have to write as 
there's only one left. Now we have to explain the peculiarities of both cmake 
and autotools.
> I think there are
> several more important projects.

Perhaps.

> 
> 1. About CMake
> In Code we should clean up CMake. Many parts were written a decade
> ago. In between CMake got many modules, which on the long run might be
> more error prone than our self written ancestors.
> 
I agree CMake in code could use a review. That's a huge project impacting the 
actual code base. The CMake introduction on maint on the other hand doesn't 
impact the current build processes at all as autotools is still there and the 
default.

> 2. in Docs:
> 2.1 Conversion to po based translation. Current state: Apply recently
> defined enities on documents.
> 
I see my involvement here more on the structural level: help provide the tools 
to do po based translation and possibly even help in a semi-automated 
conversion of the existing documents to the po format.

However I prefer to do that on cmake rather than autotools. We'll have to 
write new build rules to support a po based workflow. Doing so first in 
autotools means we have to port even more build system to cmake afterwards.

> 2.2 The incomplete restructuring
> 
> 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. I don't see how .desktop 
files would replace the .omf file ? Where is that currently being used ?

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

2019-09-04 Thread Frank H. Ellenberger
Dear Geert,

I currently see no reason to do this now - release this weekend - and
am also tired to rewrite the related wiki parts. I think there are
several more important projects.

1. About CMake
In Code we should clean up CMake. Many parts were written a decade
ago. In between CMake got many modules, which on the long run might be
more error prone than our self written ancestors.

2. in Docs:
2.1 Conversion to po based translation. Current state: Apply recently
defined enities on documents.

2.2 The incomplete restructuring

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.

Just my 2ยข
Frank


Am 02.09.19 um 19:29 schrieb 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 so on.
>
> Entering
> make help
> will provide a list of available targets to choose from.
>
> This gets even more complicated when attempting to install. There is only one
> global install target (inherit to cmake). However one can restrict what to
> install by setting environment variable CMAKE_INSTALL_COMPONENT to one of the
> targets mentioned above (at least one for which install is implemented/makes
> sense). So for example
>
> CMAKE_INSTALL_COMPONENT=C-gnucash-guide-html make install
>
> That will only install the English guide in html format. Currently this will
> work for xml and html targets. The pdf, epub and mobi targets don't have
> install rules. And I'm even considering dropping them for html. It doesn't
> make much sense to have an install rule for html as it's not something a
> packager will want to install on their system. They should use the xml target
> instead.
>
> The last tidbit I'm still considering for improvement is to replicate the
> install paths in the build directory, much like we do for the gnucash build
> system as well. That is, instead of storing the pdf file in
> /guide/C
> store it in
> /share/gnucash-docs/C
>
> There are a few additional notes in https://github.com/Gnucash/gnucash-docs/
> blob/maint/CMakeNotes.txt
>
> Feedback is welcome.
>
> Regards,
>
> Geert
>
>
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel