Re: [GNC-dev] Documentation update problems

[Geert Janssens]

Op vrijdag 21 september 2018 04:13:22 CEST schreef David Cousens:
> Geert
> 
> "I think a generic page for autotools based build and one for cmake based
> builds would be useful. We can even consider abandoning the autotools based
> page to save time. This should be accompanied with a page that explains how
> to
> set up the proper dependencies based on your platform. The Build
> instructions
> page itself would then become a very short recipe referring to these two or
> three pages. "
> 
> 
> These pages largely exist in some form in the breakouts from
> BuildUbuntu16.04
> so I will copy them back to the Build on Linux page.

Ok.

> The autotools build also
> applies to building the documentation so it could also be linked from there

I believe that's not completely accurate. The documentation build system is 
also autotools based, but as John pointed out somewhere recently the make 
targets are completely different.

For the application one would run "make" to build. For documentation this does 
nothing.

For the application the primary targets of interest are
- all (the default target if none is specified)
- check (to run our test suite)
- install (to install the application in the proper prefix)

For documentation on the other hand the primary targets of interest are
- html
- pdf
- epub
- mobi
- check (which will run xmllint on the docbook sources)
The "all" target (default when none is specified) will do nothing.


Additionally the current application build expects the user to run the make 
(or ninja) command in the top-level build directory. For the documentation the 
commands can be run in any sub directory to limit the which documentation is 
built.

So I'm not sure whether linking to the autotools instructions for the 
application from the build instructions for the documentation will keep things 
sufficiently clear.

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Geert Janssens]

Op vrijdag 21 september 2018 01:16:51 CEST schreef David Cousens:
> Adrien,
> 
> I think it is better to leave packaging apps to specialists rather than the
> general user.

> Using flatpak and snap can be better addressed on the
> Installation page rather than a building page which also addresses using ,
> Software Mmanager and installation of the version supported by the
> particular distribution version.
> 
I have recently played a bit with flatpak, and I think it's useful to see it 
as an independent platform.

The "generic" instructions as we are currently presenting them work for linux 
and likely also for other open systems such as the BSD*'s, MacPorts, 
Homebrew,... For all these systems the preparations (that is setting up the 
dependencies) vary wildly, but the eventual build steps are always the same.

For the integrated MacOS and Windows builds we have set up specific build and 
package tooling (in the gnucash-on-osx and gnucash-on-windows repositories). 
The build instructions in these cases are different (though with some extra 
effort one code even use the generic instructions for part of the process). 
That's why I hinted earlier to treat them separately.

The same goes flatpak builds. The instructions are completely different. On 
the other hand it's surprisingly easy to generate a flatpak once one has 
access to a proper manifest. So as the build result is distro agnostic I think 
it's worth documenting it. Thing is I'm still pretty new to it, so I don't 
know the pitfalls yet.

> I was thinking more of a few notes that people ouside the GnuCash developer
> user group might pick up on to remind them to compile with all options and
> setup access to the operating system utilities where needed, preferrably as
> part of the app setup rather than a post configuration. I don't know enough
> about flatchat or snap to know if it is possible to do that but I would
> expect it to be possible
> 
I don't know about snap either.

But in theory one could do that for flatpaks indeed. The flatpak manifest for 
gnucash already allows fairly broad access by default. There is a bug in it 
still with respect to "localhost" access to a db server running on the local 
PC. 127.0.0.1 works as a workaround.

The other issue is drives and usb sticks mounted outside of the user's home 
directory. It's pretty hard to configure this universally though as it depends 
on the linux distribution and/or user configuration where they will end up.

Regards,

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David Cousens]

Geert

"I think a generic page for autotools based build and one for cmake based 
builds would be useful. We can even consider abandoning the autotools based 
page to save time. This should be accompanied with a page that explains how
to 
set up the proper dependencies based on your platform. The Build
instructions 
page itself would then become a very short recipe referring to these two or 
three pages. "


These pages largely exist in some form in the breakouts from
BuildUbuntu16.04
so I will copy them back to the Build on Linux page. The autotools build
also 
applies to building the documentation so it could also be linked from there

David Cousens



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David Cousens]

Adrien,

I think it is better to leave packaging apps to specialists rather than the
general user. Using flatpak and snap can be better addressed on the
Installation page rather than a building page which also addresses using ,
Software Mmanager and installation of the version supported by the
particular distribution version.

I was thinking more of a few notes that people ouside the GnuCash developer
user group might pick up on to remind them to compile with all options and
setup access to the operating system utilities where needed, preferrably as
part of the app setup rather than a post configuration. I don't know enough
about flatchat or snap to know if it is possible to do that but I would
expect it to be possible

The current building page is linked in from the Installation page as an if
all else fails try building option (not quite in those terms).

David



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David Cousens]

On Thu, 2018-09-20 at 11:42 -0500, Adrien Monteleone wrote:
> While you’re tweaking this, consider changing the debian/derivative 
> instructions to use ‘apt’ instead of ‘apt-get’ as
> my understanding the distro preferences are for the newer ‘apt’ user tool. 
> (not to be confused, due to unfortunate
> naming, with the low level ‘apt’)

I was torn between using apt or apt-get when updating the Ubuntu16.04 but 
seeing that apt is the new package in 16.04.
I'll just use apt add a note to the effect that it may be apt-get in some 
distributions/versions along with reference to
the package managers


David
> 
> Regards,
> Adrien
> 
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Adrien Monteleone]

I was thinking more along the lines of .deb/.rpm but if it adds complexity to 
get up and running, certainly, it should not be included. (or perhaps as a 
breakout page option)

I don’t take that route for my own installations as I’m more familiar with 
building and cleaning up after myself.

Regards,
Adrien

> On Sep 20, 2018, at 12:14 PM, Geert Janssens  
> wrote:
> 
> Op donderdag 20 september 2018 19:09:10 CEST schreef Adrien Monteleone:
>>> On Sep 20, 2018, at 5:46 AM, David Cousens 
>>> wrote:
>>> 
>>> 
>>> I'll set the examples up to default to a /home/user/.local install and
>>> then perhaps add an extra section on installing for all users and the
>>> various options there and the need for administrator privileges. Most
>>> Linux users do get used to that pretty quickly
>> 
>> If the target is going to be casual builders, should the recommendation
>> instead include in the recipe the commands to package the app first and
>> then install via the system package manager? That would seem a cleaner
>> approach and remove the need for retaining build directories for removal,
>> having to probably revisit the wiki to figure out how to uninstall just use
>> their regular package manager to handle it.
> 
> I think that goes very much in the direction of flatpak, snap and friends.
> 
> I personally don't think adding information on packaging will make it any 
> easier. This is in general rather challenging in fact.
> 
> Geert
> 
> 
> 


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Geert Janssens]

Op donderdag 20 september 2018 19:09:10 CEST schreef Adrien Monteleone:
> > On Sep 20, 2018, at 5:46 AM, David Cousens 
> > wrote:
> > 
> > 
> > I'll set the examples up to default to a /home/user/.local install and
> > then perhaps add an extra section on installing for all users and the
> > various options there and the need for administrator privileges. Most
> > Linux users do get used to that pretty quickly
> 
> If the target is going to be casual builders, should the recommendation
> instead include in the recipe the commands to package the app first and
> then install via the system package manager? That would seem a cleaner
> approach and remove the need for retaining build directories for removal,
> having to probably revisit the wiki to figure out how to uninstall just use
> their regular package manager to handle it.

I think that goes very much in the direction of flatpak, snap and friends.

I personally don't think adding information on packaging will make it any 
easier. This is in general rather challenging in fact.

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Adrien Monteleone]

> On Sep 20, 2018, at 5:46 AM, David Cousens  wrote:
> 
>> 
> I'll set the examples up to default to a /home/user/.local install and then 
> perhaps
> add an extra section on installing for all users and the various options 
> there and 
> the need for administrator privileges. Most Linux users do get used to that 
> pretty
> quickly

If the target is going to be casual builders, should the recommendation instead 
include in the recipe the commands to package the app first and then install 
via the system package manager? That would seem a cleaner approach and remove 
the need for retaining build directories for removal, having to probably 
revisit the wiki to figure out how to uninstall just use their regular package 
manager to handle it.

Regards,
Adrien


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Adrien Monteleone]

While you’re tweaking this, consider changing the debian/derivative 
instructions to use ‘apt’ instead of ‘apt-get’ as my understanding the distro 
preferences are for the newer ‘apt’ user tool. (not to be confused, due to 
unfortunate naming, with the low level ‘apt’)

Regards,
Adrien

> On Sep 19, 2018, at 4:51 PM, David Cousens  wrote:
> 
> John, Geert, Adrien, David
> 
> Thanks for all the prespectives. I will attempt a restructure of the Building 
> Gnucash page and its derivatives, trying
> to push as much information back to the generic Linux level as I can from the 
> BuildingUbuntu 16.04 pages. I have no
> experience of building on Windows or MacOS X so I will definitely leave that 
> to someone else. I'll start with Geert's
> comments as an overall plan and try to address the rest of your comments. I 
> can set VMs up for the other distros so I
> can check them out a bit better
> 
> With the dependencies I compiled as complete a list as I was able to from my 
> own experience and other users experiences
> when a lot of people were building v3.0-3.2 as it wasn't available from the 
> distros. . I had a clean Linux Mint install
> at the time I did that so I captured a few that are usually already installed 
> once you get a bit of other software on
> board. Some distros do seem to use slightly different names for some 
> libraries and headers so perhaps a warning to check
> your own distros naming using the equivalent of apt-cache search. I'll do as 
> much as I can from the online documentation
> for the other distros. I  I'll have a closer look and if I can get away 
> perhaps with a subsitute "dnf" and "yum"and
> "apt" for apt-get as a note along the lines if compiling on xxx subsitute yyy 
> for apt-get in the following.
> 
> I was reluctant originally to touch the Fedora and Gentoo sections as I 
> hadn't had any experience of them. It would
> appear the major difference is likely to be the name of the package manager 
> on the various distros. I appreciate there
> are sometimes also slight differences in the interpretation of the Linux File 
> Heirarchy as well.
> 
> I'll come back when I've done a restructure and get everyone to check it out
> 
> David Cousens
> 

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David Cousens]

> 
> Didn't apt-get build-dep gnucash install most of the dependencies already ?

It does , but it installs the dependencies for the version of GnuCash that the 
distribution supports in its package management system. I ran into this problem
with 3.0-3.2 where a few libraries were up dated. Can always use it as a 
starting
point and then get users to update whatever fails the cmake /configure.
> 
> I think it's nice to have an overview of the real dependencies, but probably 
> rather as background information than as a build recipe. These could then 
> become slightly more generic by using normal library names instead of package 
> names. And it appears we have such a page already, though it may need review:
> https://wiki.gnucash.org/wiki/Dependencies
> Another opportunity for deduplication.
> 
> > Some distros do seem to use slightly different names for some libraries and
> > headers so perhaps a warning to check your own distros naming using the
> > equivalent of apt-cache search.
> 
> Good idea. FYI on fedora you can use "dnf search" for the same. I don't know 
> what other package managers support (Arch uses pacman, Sabayon uses equo, 
> OpenSuse uses or used to use yast,...)
> 
> > I'll do as much as I can from the online
> > documentation for the other distros. I  I'll have a closer look and if I
> > can get away perhaps with a subsitute "dnf" and "yum"and "apt" for apt-get
> > as a note along the lines if compiling on xxx subsitute yyy for apt-get in
> > the following.
> 
> I fear that will quickly get hairy. It's not only the tool that has a 
> different name (dnf vs yum vs apt-get vs pacman vs yast,...) their options 
> also differ - "dnf builddep" vs "apt-get build-dep" for example. The command 
> is very similar, but not the same. And as you note package names differ 
> slightly also. Development packager on Fedora end in -devel, where on debian 
> and derivatives they end in -dev. Some distros split out packages in a 
> different way (I know on some platforms both a libxml and an xml-tools 
> package 
> exist and should be installed, on others it's only libxml2).

Point taken. It would be nice if you could get readers to specify their 
distribution 
up front and then just display the relevant bits downstream. I don't know if a 
wiki can do that
but will try and find out. 
https://www.mediawiki.org/wiki/Manual:Magic_words looks promising
> 
> Considering we want the instructions to be recipe like it makes sense to 
> detail the instructions per distro/package manager as long as there are 
> differences.
> > 
> > I was reluctant originally to touch the Fedora and Gentoo sections as I
> > hadn't had any experience of them. It would appear the major difference is
> > likely to be the name of the package manager on the various distros.
> 
> The package manager and subtleties in packaging and package naming.
> 
> > I appreciate there are sometimes also slight differences in the
> > interpretation of the Linux File Heirarchy as well.
> > 
> 
> There are, but they shouldn't affect building as far as I can see. If 
> dependencies are set up properly, the generic instructions should work on all 
> platforms. If not, that's likely a bug in our build system.
> 
> But this does bring up another point I'd like to bring up:
> I think the generic, user-oriented build instructions should default to 
> installing in the user's home directory. However unless an install prefix is 
> passed to cmake the installation will default to /usr/local.

>  
I'll set the examples up to default to a /home/user/.local install and then 
perhaps
add an extra section on installing for all users and the various options there 
and 
the need for administrator privileges. Most Linux users do get used to that 
pretty
quickly

> That is however 
> administrator territory and not without pitfalls. So it should be reserved 
> for 
> advanced users with system management experience. I agree with Adrien our 
> target audience should be users that casually compile an application, but 
> otherwise don't have much experience with this.
> 
> Geert
> 
> 
David 
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Geert Janssens]

Op woensdag 19 september 2018 23:51:35 CEST schreef David Cousens:
> John, Geert, Adrien, David
> 
> Thanks for all the prespectives. I will attempt a restructure of the
> Building Gnucash page and its derivatives, trying to push as much
> information back to the generic Linux level as I can from the
> BuildingUbuntu 16.04 pages. I have no experience of building on Windows or
> MacOS X so I will definitely leave that to someone else. I'll start with
> Geert's comments as an overall plan and try to address the rest of your
> comments. I can set VMs up for the other distros so I can check them out a
> bit better
> 
Great!

> With the dependencies I compiled as complete a list as I was able to from my
> own experience and other users experiences when a lot of people were
> building v3.0-3.2 as it wasn't available from the distros. . I had a clean
> Linux Mint install at the time I did that so I captured a few that are
> usually already installed once you get a bit of other software on board.

Didn't apt-get build-dep gnucash install most of the dependencies already ?

I think it's nice to have an overview of the real dependencies, but probably 
rather as background information than as a build recipe. These could then 
become slightly more generic by using normal library names instead of package 
names. And it appears we have such a page already, though it may need review:
https://wiki.gnucash.org/wiki/Dependencies
Another opportunity for deduplication.

> Some distros do seem to use slightly different names for some libraries and
> headers so perhaps a warning to check your own distros naming using the
> equivalent of apt-cache search.
Good idea. FYI on fedora you can use "dnf search" for the same. I don't know 
what other package managers support (Arch uses pacman, Sabayon uses equo, 
OpenSuse uses or used to use yast,...)

> I'll do as much as I can from the online
> documentation for the other distros. I  I'll have a closer look and if I
> can get away perhaps with a subsitute "dnf" and "yum"and "apt" for apt-get
> as a note along the lines if compiling on xxx subsitute yyy for apt-get in
> the following.

I fear that will quickly get hairy. It's not only the tool that has a 
different name (dnf vs yum vs apt-get vs pacman vs yast,...) their options 
also differ - "dnf builddep" vs "apt-get build-dep" for example. The command 
is very similar, but not the same. And as you note package names differ 
slightly also. Development packager on Fedora end in -devel, where on debian 
and derivatives they end in -dev. Some distros split out packages in a 
different way (I know on some platforms both a libxml and an xml-tools package 
exist and should be installed, on others it's only libxml2).

Considering we want the instructions to be recipe like it makes sense to 
detail the instructions per distro/package manager as long as there are 
differences.
> 
> I was reluctant originally to touch the Fedora and Gentoo sections as I
> hadn't had any experience of them. It would appear the major difference is
> likely to be the name of the package manager on the various distros.

The package manager and subtleties in packaging and package naming.

> I appreciate there are sometimes also slight differences in the
> interpretation of the Linux File Heirarchy as well.
> 
There are, but they shouldn't affect building as far as I can see. If 
dependencies are set up properly, the generic instructions should work on all 
platforms. If not, that's likely a bug in our build system.

But this does bring up another point I'd like to bring up:
I think the generic, user-oriented build instructions should default to 
installing in the user's home directory. However unless an install prefix is 
passed to cmake the installation will default to /usr/local. That is however 
administrator territory and not without pitfalls. So it should be reserved for 
advanced users with system management experience. I agree with Adrien our 
target audience should be users that casually compile an application, but 
otherwise don't have much experience with this.

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David Cousens]

John, Geert, Adrien, David

Thanks for all the prespectives. I will attempt a restructure of the Building 
Gnucash page and its derivatives, trying
to push as much information back to the generic Linux level as I can from the 
BuildingUbuntu 16.04 pages. I have no
experience of building on Windows or MacOS X so I will definitely leave that to 
someone else. I'll start with Geert's
comments as an overall plan and try to address the rest of your comments. I can 
set VMs up for the other distros so I
can check them out a bit better

With the dependencies I compiled as complete a list as I was able to from my 
own experience and other users experiences
when a lot of people were building v3.0-3.2 as it wasn't available from the 
distros. . I had a clean Linux Mint install
at the time I did that so I captured a few that are usually already installed 
once you get a bit of other software on
board. Some distros do seem to use slightly different names for some libraries 
and headers so perhaps a warning to check
your own distros naming using the equivalent of apt-cache search. I'll do as 
much as I can from the online documentation
for the other distros. I  I'll have a closer look and if I can get away perhaps 
with a subsitute "dnf" and "yum"and
"apt" for apt-get as a note along the lines if compiling on xxx subsitute yyy 
for apt-get in the following.

I was reluctant originally to touch the Fedora and Gentoo sections as I hadn't 
had any experience of them. It would
appear the major difference is likely to be the name of the package manager on 
the various distros. I appreciate there
are sometimes also slight differences in the interpretation of the Linux File 
Heirarchy as well.

I'll come back when I've done a restructure and get everyone to check it out

David Cousens


On Wed, 2018-09-19 at 10:34 +0200, Geert Janssens wrote:
> Op dinsdag 18 september 2018 10:19:02 CEST schreef David Cousens:
> > John, David, Frank
> > 
> > I wonder at the value of the Build Tools page as a separate orphan entity
> > given the more detailed instructions given in the Building Gnucash page.
> > There is a fairly good example of dupllcation with it and the following for
> > the Gnucash progarm build.
> > 
> > https://wiki.gnucash.org/wiki/Building
> > 
> > and the breakout from it for recent Ubuntu versions
> > 
> > https://wiki.gnucash.org/wiki/BuildUbuntu16.04
> > 
> > The main building page is a massive tome. I did start breaking out some
> > parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
> > ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). The Build
> > Tools page may be a logical breakout from there with some of the detail in
> > the first page cut into it. There is also a short summary recipe for
> > building the Docs at the end of the BuildUbuntu16.04 page which lacks detail
> > but does work on Ubuntu and most linux distros. It has no details about the
> > dependencies in it though.
> > 
> > Would a page on building the docs be better as a breakout from the main
> > building Gnucash page perhaps with a shared section on the build tools
> > referenced from both. For build instructions I ususaly find the recipe the
> > most useful bit with explantions of the specific tools as breakouts. If you
> > need the information and background you can follow the links. If you only do
> > a build occasionally you follow the recipe.  I.e only read the manual when
> > you have to.
> > 
> 
> I wrote my previous mail before looking at the wiki pages you mentioned and I 
> agree the current structuring is not guiding the reader to a successful build 
> in the most efficient way.
> 
> The page could be restructured to be more recipe like with links to pages/
> sections with more details.
> 
> The general structure of the general instructions is good, but I would not 
> differentiate between general and distro specific variants. Building on 
> Windows and OS X do merit a separate mention as their build instructions are 
> very different. For linux distros as written before the only difference is 
> how 
> to get the necessary dependencies set up. It would make sense to add a 
> section 
> for this right before getting the gnucash sources.
> 
> And as I suggested, the info should be very short on the main building page, 
> with a link to a more detailed page specifically about setting up 
> dependencies 
> per distro or distro group.
> 
> The configuring gnucash section could be reduced to indicating what to do for 
> gnucash 2.6.x and what to do for gnucash 3.x by default. More details on 
> configuration options could go to a more detailed page on configuring gnucash.
> 
> In my opinion the mention of the compiler is not relevant here. If it should 
> be mentioned it should be in the section or details on setting up 
> dependencies.
> 
> All the sections under OS/Distro specific information (other than the two 
> links to OS X and Windows should IMO be removed from this page. The details 
> of 

Re: [GNC-dev] Documentation update problems

[Adrien Monteleone]

For users to be able to obtain the latest (or otherwise particularly desired) 
version not in their repos, I would agree with David C. & Geert here that a 
single generic linux recipe for tarballs, augmented with links to quirks for 
particular *non-deprecated* distributions and/or historical GnuCash versions 
would be the simplest and non-developer friendly approach.

Any other build would be from git, would be more geared to developers/testers, 
or those who wanted/needed bleeding edge nightlies. Those build instructions 
would more likely cover Windows and Mac in addition to Linux, and explain the 
GnuCash git repos. (and any build quirks from trying to use them)

I don’t think that latter sort of info should be on the same page(s) as those 
geared towards non-developers/testers. It will only serve to confuse.

Regards,
Adrien

> On Sep 19, 2018, at 4:16 PM, David Cousens  wrote:
> 
> On Tue, 2018-09-18 at 13:16 -0400, David T. via gnucash-devel wrote:
>> Hello,
>> 
>> I have a general question about building. Forgive me if this is naive. The 
>> last time I used Linux was last century,
>> and I believe that Linux has changed just a tad since then.
>> 
>> Since GnuCash is now developed over git, can't 
>> users|developers|writers|yetis use git for most distros to obtain
>> source code and compile it on their machines? IOW, rather than offer 
>> voluminous directions on how to obtain the
>> sources and compile GnuCash on every variant of YetiCompute, could we simply 
>> advise the majority of the community
>> (yetis included) to use git to clone our repos and compile using git? It 
>> seems to me to be a colossal waste of
>> community effort to attempt to account for every flavor of every distro. I 
>> contrast this with the (IMHO correct)
>> stance on encryption, in which circumstance we advise users to find 
>> appropriate encryption tools, rather than build a
>> half-crap version of our own.
> 
> David, 
> A lot of users rather than developers will build from the tarballs rather 
> than from the github repositories. While this
> page was I think originally targeted primarily at developers, with the 
> release of v3.2 quite a lot of users on Ubuntu
> based systems started building because the distribution repositories didn't 
> have, and still don't have in may cases, the
> latest Gnucash available. More people were also moving to Ubuntu 18.04 and 
> Linux Mint Tara based on Ubuntu 18.04 was
> also being released. The change to 3.2 also resulted in some updates to the 
> dependencies along with the move to cmake
> form./configure becoming compulsory. I had a few problems initially  with the 
> build, so I updated the
> BuildingUbuntu16.04 page as I sorted out issues and I updated it as other 
> issues came up on the Gnucash User forum along
> with a few other contributors.
> 
>> Focusing our efforts on *a* GnuCash Way of building the program would 
>> simplify the wiki immensely.
> 
> I think the prefrred way for users is from the tarballs not github. Too many 
> options with master maint, tags on releases
> etc., that unless you have some programming background it would put new users 
> off rather than encourage them.
> 
> 
> David Cousens
>> 
>>> On Sep 18, 2018, at 12:18 PM, Adrien Monteleone 
>>>  wrote:
 
> The main building page is a massive tome. I did start breaking out some
> parts of it into smaller logical chunks when I updated the 
> BuildUbuntu16.04
> ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). 
 
 Shouldn’t it be renamed to BuildUbuntu then?
>>> 
>>> I agree, the link text/page title is confusing and there have already been 
>>> questions about what instructions to use
>>> for building on 18.04.(yes, I see that it says this is for 18.04 as well, 
>>> but clearly someone didn’t or they
>>> wouldn’t have asked)
>> 
>> If we continue with the Massive Tome Approach, I would recommend a title of 
>> “Building on Ubuntu"
>> 
>>> 
>>> If replacing content with a link to a dedicated page is desired practice 
>>> for cleaning up the wiki, then I’d propose
>>> all of the material for building on Ubuntu be moved to that page, that it 
>>> be renamed simply BuildUbuntu and that the
>>> main build page be left with a link to it for the Ubuntu section. As it is, 
>>> the original build page still contains
>>> long outdated info. I would have instead expected to see the most current 
>>> instructions there and then maybe a link
>>> for older versions.
>>> 
>>> Along with that, if older material for older systems and versions isn’t 
>>> going to be moved to its own ‘archive’ page,
>>> then it should always appear down the page in chronological order. The 
>>> current state of the build instructions is a
>>> bit messy in that regard.
>> 
>> Older content should be removed altogether, not archived.
>> 
>> 
>>> 
>>> Regards,
>>> Adrien
>>> ___
>>> gnucash-devel mailing list
>>> gnucash-devel@gnucash.org
>>> 

Re: [GNC-dev] Documentation update problems

[David Cousens]

On Tue, 2018-09-18 at 13:16 -0400, David T. via gnucash-devel wrote:
> Hello,
> 
> I have a general question about building. Forgive me if this is naive. The 
> last time I used Linux was last century,
> and I believe that Linux has changed just a tad since then.
> 
> Since GnuCash is now developed over git, can't users|developers|writers|yetis 
> use git for most distros to obtain
> source code and compile it on their machines? IOW, rather than offer 
> voluminous directions on how to obtain the
> sources and compile GnuCash on every variant of YetiCompute, could we simply 
> advise the majority of the community
> (yetis included) to use git to clone our repos and compile using git? It 
> seems to me to be a colossal waste of
> community effort to attempt to account for every flavor of every distro. I 
> contrast this with the (IMHO correct)
> stance on encryption, in which circumstance we advise users to find 
> appropriate encryption tools, rather than build a
> half-crap version of our own.

David, 
A lot of users rather than developers will build from the tarballs rather than 
from the github repositories. While this
page was I think originally targeted primarily at developers, with the release 
of v3.2 quite a lot of users on Ubuntu
based systems started building because the distribution repositories didn't 
have, and still don't have in may cases, the
latest Gnucash available. More people were also moving to Ubuntu 18.04 and 
Linux Mint Tara based on Ubuntu 18.04 was
also being released. The change to 3.2 also resulted in some updates to the 
dependencies along with the move to cmake
form./configure becoming compulsory. I had a few problems initially  with the 
build, so I updated the
BuildingUbuntu16.04 page as I sorted out issues and I updated it as other 
issues came up on the Gnucash User forum along
with a few other contributors.
 
> Focusing our efforts on *a* GnuCash Way of building the program would 
> simplify the wiki immensely.

I think the prefrred way for users is from the tarballs not github. Too many 
options with master maint, tags on releases
etc., that unless you have some programming background it would put new users 
off rather than encourage them.


David Cousens
> 
> > On Sep 18, 2018, at 12:18 PM, Adrien Monteleone 
> >  wrote:
> > > 
> > > > The main building page is a massive tome. I did start breaking out some
> > > > parts of it into smaller logical chunks when I updated the 
> > > > BuildUbuntu16.04
> > > > ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). 
> > > 
> > > Shouldn’t it be renamed to BuildUbuntu then?
> > 
> > I agree, the link text/page title is confusing and there have already been 
> > questions about what instructions to use
> > for building on 18.04.(yes, I see that it says this is for 18.04 as well, 
> > but clearly someone didn’t or they
> > wouldn’t have asked)
> 
> If we continue with the Massive Tome Approach, I would recommend a title of 
> “Building on Ubuntu"
> 
> > 
> > If replacing content with a link to a dedicated page is desired practice 
> > for cleaning up the wiki, then I’d propose
> > all of the material for building on Ubuntu be moved to that page, that it 
> > be renamed simply BuildUbuntu and that the
> > main build page be left with a link to it for the Ubuntu section. As it is, 
> > the original build page still contains
> > long outdated info. I would have instead expected to see the most current 
> > instructions there and then maybe a link
> > for older versions.
> > 
> > Along with that, if older material for older systems and versions isn’t 
> > going to be moved to its own ‘archive’ page,
> > then it should always appear down the page in chronological order. The 
> > current state of the build instructions is a
> > bit messy in that regard.
> 
> Older content should be removed altogether, not archived.
> 
> 
> > 
> > Regards,
> > Adrien
> > ___
> > 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
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Geert Janssens]

Op dinsdag 18 september 2018 10:19:02 CEST schreef David Cousens:
> John, David, Frank
> 
> I wonder at the value of the Build Tools page as a separate orphan entity
> given the more detailed instructions given in the Building Gnucash page.
> There is a fairly good example of dupllcation with it and the following for
> the Gnucash progarm build.
> 
> https://wiki.gnucash.org/wiki/Building
> 
> and the breakout from it for recent Ubuntu versions
> 
> https://wiki.gnucash.org/wiki/BuildUbuntu16.04
> 
> The main building page is a massive tome. I did start breaking out some
> parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
> ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). The Build
> Tools page may be a logical breakout from there with some of the detail in
> the first page cut into it. There is also a short summary recipe for
> building the Docs at the end of the BuildUbuntu16.04 page which lacks detail
> but does work on Ubuntu and most linux distros. It has no details about the
> dependencies in it though.
> 
> Would a page on building the docs be better as a breakout from the main
> building Gnucash page perhaps with a shared section on the build tools
> referenced from both. For build instructions I ususaly find the recipe the
> most useful bit with explantions of the specific tools as breakouts. If you
> need the information and background you can follow the links. If you only do
> a build occasionally you follow the recipe.  I.e only read the manual when
> you have to.
> 
I wrote my previous mail before looking at the wiki pages you mentioned and I 
agree the current structuring is not guiding the reader to a successful build 
in the most efficient way.

The page could be restructured to be more recipe like with links to pages/
sections with more details.

The general structure of the general instructions is good, but I would not 
differentiate between general and distro specific variants. Building on 
Windows and OS X do merit a separate mention as their build instructions are 
very different. For linux distros as written before the only difference is how 
to get the necessary dependencies set up. It would make sense to add a section 
for this right before getting the gnucash sources.

And as I suggested, the info should be very short on the main building page, 
with a link to a more detailed page specifically about setting up dependencies 
per distro or distro group.

The configuring gnucash section could be reduced to indicating what to do for 
gnucash 2.6.x and what to do for gnucash 3.x by default. More details on 
configuration options could go to a more detailed page on configuring gnucash.

In my opinion the mention of the compiler is not relevant here. If it should 
be mentioned it should be in the section or details on setting up 
dependencies.

All the sections under OS/Distro specific information (other than the two 
links to OS X and Windows should IMO be removed from this page. The details of 
setting up dependencies can be grouped on the new page for this, the build 
instructions themselves are identical for all distros. Oh and anything that's 
valid only for obsolete distros should be removed completely. The oldest 
supported Ubuntu distro is 14.04 LTS, for Fedora that's 27. I would not 
mention distro releases unless it's necessary to differentiate. In that case I 
would write the default instructions for the current distro (omitting distro 
release info) and exceptional instructions for the older distro(s) (adding for 
which distro this matters). That will make it easier to maintain the 
documentation in the future:
- if nothing changes when a new disto release comes out, documentation doesn't 
need to be updated
- if a distro becomes obsolete, it's easy to find and remove all info that's 
no longer relevant.

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Geert Janssens]

Op woensdag 19 september 2018 05:19:08 CEST schreef John Ralls:
> It’s Debian and derivatives: Ubuntu is a derivative--or these days maybe a
> symbiote, there are Canonical reps on the Debian board--of Debian.
> 
> I frankly don’t understand why Ubuntu needs a per-release explanation of how
> to build it, especially since Debian doesn’t. `sudo apt-get build-dep
> gnucash` installs everything you need to build 2.6; there are a few
> additional packages (cmake, ninja, swig, xsltproc, libgtk-3-dev,
> libboost-all-dev, googletest, and libwebkit2gtk-3.0-dev) to build 3. After
> that it’s the same directory creation, clone gnucash.git, cmake, and ninja
> reqardless of distro version.
> 
+1

The build instructions are generic for *all* linux distributions, not only 
Debian and derivatives. The only part that differs is getting the required 
dependencies on your system. As there are plenty flavors of package managers, 
this part needs to be detailed per platform.

The Debian/Ubuntu world has more or less standardized on the apt family of 
tools, so for those the same instructions can probably be used.

On Fedora the primary package manager is dnf, and the instructions would be 
written for dnf. The dnf equivalent of
"sudo apt-get build-dep gnucash"
is
"sudo dnf builddep install gnucash"

The devil on the other hand is in the details.

While we don't actively develop on gnucash 2.6 any more we know many users 
will stick to this series until they are comfortable to make the switch. There 
are even users on 2.4 still. We decided recently that any wiki information 
older than that release should be considered obsolete. Which inversely also 
means anything more recent is not.

That's why we still have build documentation for 2.6.x next to documentation 
for 3.x. While the effort to migrate to cmake was started in the 2.6 series 
I'm not sure it was bug free. So I understand build instructions for 2.6.x are 
still documenting the autotools way. Yet in 3.x cmake is the only supported 
build environment. That leads already to two different sets of build 
instructions.

Next, what "apt-get build-dep gnucash" and "dnf builddep install gnucash" 
really install depends on the version of gnucash supported by default on the 
chosen system. For example Fedora 27 by default still ships gnucas 2.6.21, so 
the builddep command will install build dependencies for that version. If you 
want to build gnucash 3.x on that system one has to manually install the new 
dependencies, as John mentioned for apt above. In theory it would be the other 
way around when your distro ships gnucash 3.x by default. In practice however 
it's very unlikely you can still "easily" build gnucash 2.6 on such systems. 
Most of these distros have dropped libwebkitgtk-1 due to security issues.

So how do we proceed practically from here?

I think a generic page for autotools based build and one for cmake based 
builds would be useful. We can even consider abandoning the autotools based 
page to save time. This should be accompanied with a page that explains how to 
set up the proper dependencies based on your platform. The Build instructions 
page itself would then become a very short recipe referring to these two or 
three pages.

Zooming in on the generic build instructions, it may be worth starting with a 
preferred directory setup, a section (or a link to) how to clone the git repo 
and check out the proper branch.

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[John Ralls]

It’s Debian and derivatives: Ubuntu is a derivative--or these days maybe a 
symbiote, there are Canonical reps on the Debian board--of Debian.

I frankly don’t understand why Ubuntu needs a per-release explanation of how to 
build it, especially since Debian doesn’t. `sudo apt-get build-dep gnucash` 
installs everything you need to build 2.6; there are a few additional packages 
(cmake, ninja, swig, xsltproc, libgtk-3-dev, libboost-all-dev, googletest, and 
libwebkit2gtk-3.0-dev) to build 3. After that it’s the same directory creation, 
clone gnucash.git, cmake, and ninja reqardless of distro version.

Regards,
John Ralls


> On Sep 18, 2018, at 6:52 PM, David Cousens  wrote:
> 
> On Tue, 2018-09-18 at 11:18 -0500, Adrien Monteleone wrote:
>>> On Sep 18, 2018, at 7:53 AM, Frank H. Ellenberger 
>>>  wrote:
>>> 
>>> 
>>> Perhaps you can do some cleanup: Is Gutsy outdated?
>> 
>> That was version 7.10 of Ubuntu, that is, released October 2007. By far, it 
>> is no longer supported by Canonical.
>> (wasn’t even a Long Term Support release) And there is not even a hardware 
>> reason that anyone should be running it. I
>> don’t even think the repos for it are even available any longer.
>> 
>> The oldest supported Ubuntu version is 14.04 (and then only until next 
>> April) I shouldn’t think any build instructions
>> are necessary (unless in an archived page if desired) for anything older 
>> than this.
>> 
>>> 
 The main building page is a massive tome. I did start breaking out some
 parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
 ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). 
>>> 
>>> Shouldn’t it be renamed to BuildUbuntu then?
>> 
>> I agree, the link text/page title is confusing and there have already been 
>> questions about what instructions to use
>> for building on 18.04.(yes, I see that it says this is for 18.04 as well, 
>> but clearly someone didn’t or they wouldn’t
>> have asked)
>> 
>> If replacing content with a link to a dedicated page is desired practice for 
>> cleaning up the wiki, then I’d propose
>> all of the material for building on Ubuntu be moved to that page, that it be 
>> renamed simply BuildUbuntu and that the
>> main build page be left with a link to it for the Ubuntu section. As it is, 
>> the original build page still contains
>> long outdated info. I would have instead expected to see the most current 
>> instructions there and then maybe a link for
>> older versions.
> 
> Adrien ,John
> 
> I too think the break out from that main page  could be better structured and 
> the BuildingUbuntu16.04 renamed something
> like BuildingUbuntu I had intended to address that after 
> rewriting the BuildUbuntu16.04 but ended up
> distracted with other priorities. 
> 
> Also the main page could perhaps have a one line breakout to a Building on 
> Linux page. The page name as long as it is
> descriptive to some extent is less important than the information in the link 
> specifying what it links to e.g.
> [[BuildingUbuntu | Building on Ubuntu 16.04, 18.04 and Linux 
> Mint]]. Despite this I think it is important to
> get to the information the user will actually use in the minimum number of 
> steps. Wiki navigation can be  dodgy at
> times. I would propose a link to the at least the general Building page 
> somewhere on the wiki entry point page might
> help achieve that given John's comment and info in another post on searching 
> of wiki pages.
> 
> David Cousens
>> 
>> Along with that, if older material for older systems and versions isn’t 
>> going to be moved to its own ‘archive’ page,
>> then it should always appear down the page in chronological order. The 
>> current state of the build instructions is a
>> bit messy in that regard.
>> 
>> Regards,
>> Adrien
>> ___
>> 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 
> 
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David Cousens]

On Tue, 2018-09-18 at 11:18 -0500, Adrien Monteleone wrote:
> > On Sep 18, 2018, at 7:53 AM, Frank H. Ellenberger 
> >  wrote:
> > 
> > 
> > Perhaps you can do some cleanup: Is Gutsy outdated?
> 
> That was version 7.10 of Ubuntu, that is, released October 2007. By far, it 
> is no longer supported by Canonical.
> (wasn’t even a Long Term Support release) And there is not even a hardware 
> reason that anyone should be running it. I
> don’t even think the repos for it are even available any longer.
> 
> The oldest supported Ubuntu version is 14.04 (and then only until next April) 
> I shouldn’t think any build instructions
> are necessary (unless in an archived page if desired) for anything older than 
> this.
> 
> > 
> > > The main building page is a massive tome. I did start breaking out some
> > > parts of it into smaller logical chunks when I updated the 
> > > BuildUbuntu16.04
> > > ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). 
> > 
> > Shouldn’t it be renamed to BuildUbuntu then?
> 
> I agree, the link text/page title is confusing and there have already been 
> questions about what instructions to use
> for building on 18.04.(yes, I see that it says this is for 18.04 as well, but 
> clearly someone didn’t or they wouldn’t
> have asked)
> 
> If replacing content with a link to a dedicated page is desired practice for 
> cleaning up the wiki, then I’d propose
> all of the material for building on Ubuntu be moved to that page, that it be 
> renamed simply BuildUbuntu and that the
> main build page be left with a link to it for the Ubuntu section. As it is, 
> the original build page still contains
> long outdated info. I would have instead expected to see the most current 
> instructions there and then maybe a link for
> older versions.

Adrien ,John

I too think the break out from that main page  could be better structured and 
the BuildingUbuntu16.04 renamed something
like BuildingUbuntu I had intended to address that after rewriting 
the BuildUbuntu16.04 but ended up
distracted with other priorities. 

Also the main page could perhaps have a one line breakout to a Building on 
Linux page. The page name as long as it is
descriptive to some extent is less important than the information in the link 
specifying what it links to e.g.
[[BuildingUbuntu | Building on Ubuntu 16.04, 18.04 and Linux 
Mint]]. Despite this I think it is important to
get to the information the user will actually use in the minimum number of 
steps. Wiki navigation can be  dodgy at
times. I would propose a link to the at least the general Building page 
somewhere on the wiki entry point page might
help achieve that given John's comment and info in another post on searching of 
wiki pages.

David Cousens
> 
> Along with that, if older material for older systems and versions isn’t going 
> to be moved to its own ‘archive’ page,
> then it should always appear down the page in chronological order. The 
> current state of the build instructions is a
> bit messy in that regard.
> 
> Regards,
> Adrien
> ___
> 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

Re: [GNC-dev] Documentation update problems

[Adrien Monteleone]

> On Sep 18, 2018, at 12:16 PM, David T.  wrote:
> 
>> 
>> Along with that, if older material for older systems and versions isn’t 
>> going to be moved to its own ‘archive’ page, then it should always appear 
>> down the page in chronological order. The current state of the build 
>> instructions is a bit messy in that regard.
> 
> Older content should be removed altogether, not archived.

I should have specified that what I meant by ‘older material’ was the 
instructions for say building 2.6.x using Autotools instead of Cmake, or 
building either 2.6.x or 3.x on 14.04. (which admittedly will be unsupported in 
less than 8 months) Obsolete instructions should be removed entirely. But if 
something changes between now and say Ubuntu 20.04 that would necessitate 
different treatment, then the current instructions should be archived or bumped 
down the page, not removed, because 16.04 & 18.04 will still be supported and 
in active use.

Though, and I may be misunderstanding the GnuCash support policy, if 2.6.x is 
not being actively developed (is that not the same thing as ‘not supported’?) 
then the recipe should be for 3.x with Cmake only.

As for different architectures and distros, I should think any notes are just 
specific quirks based on what may or may not be on the system by default. I 
should think the dependencies are what they are, and the recipe should be the 
same. (disclosure - I’m not familiar with building on a regular basis on 
different systems other than MacOS and Ubuntu/Debian)

Regards,
Adrien
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David T. via gnucash-devel]

Hello,

I have a general question about building. Forgive me if this is naive. The last 
time I used Linux was last century, and I believe that Linux has changed just a 
tad since then.

Since GnuCash is now developed over git, can't users|developers|writers|yetis 
use git for most distros to obtain source code and compile it on their 
machines? IOW, rather than offer voluminous directions on how to obtain the 
sources and compile GnuCash on every variant of YetiCompute, could we simply 
advise the majority of the community (yetis included) to use git to clone our 
repos and compile using git? It seems to me to be a colossal waste of community 
effort to attempt to account for every flavor of every distro. I contrast this 
with the (IMHO correct) stance on encryption, in which circumstance we advise 
users to find appropriate encryption tools, rather than build a half-crap 
version of our own.

Focusing our efforts on *a* GnuCash Way of building the program would simplify 
the wiki immensely.

> On Sep 18, 2018, at 12:18 PM, Adrien Monteleone 
>  wrote:
>> 
>>> The main building page is a massive tome. I did start breaking out some
>>> parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
>>> ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). 
>> 
>> Shouldn’t it be renamed to BuildUbuntu then?
> 
> I agree, the link text/page title is confusing and there have already been 
> questions about what instructions to use for building on 18.04.(yes, I see 
> that it says this is for 18.04 as well, but clearly someone didn’t or they 
> wouldn’t have asked)

If we continue with the Massive Tome Approach, I would recommend a title of 
“Building on Ubuntu"

> 
> If replacing content with a link to a dedicated page is desired practice for 
> cleaning up the wiki, then I’d propose all of the material for building on 
> Ubuntu be moved to that page, that it be renamed simply BuildUbuntu and that 
> the main build page be left with a link to it for the Ubuntu section. As it 
> is, the original build page still contains long outdated info. I would have 
> instead expected to see the most current instructions there and then maybe a 
> link for older versions.
> 
> Along with that, if older material for older systems and versions isn’t going 
> to be moved to its own ‘archive’ page, then it should always appear down the 
> page in chronological order. The current state of the build instructions is a 
> bit messy in that regard.

Older content should be removed altogether, not archived.


> 
> Regards,
> Adrien
> ___
> 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

Re: [GNC-dev] Documentation update problems

[Adrien Monteleone]

> On Sep 18, 2018, at 7:53 AM, Frank H. Ellenberger 
>  wrote:
> 
> 
> Perhaps you can do some cleanup: Is Gutsy outdated?

That was version 7.10 of Ubuntu, that is, released October 2007. By far, it is 
no longer supported by Canonical. (wasn’t even a Long Term Support release) And 
there is not even a hardware reason that anyone should be running it. I don’t 
even think the repos for it are even available any longer.

The oldest supported Ubuntu version is 14.04 (and then only until next April) I 
shouldn’t think any build instructions are necessary (unless in an archived 
page if desired) for anything older than this.

> 
>> The main building page is a massive tome. I did start breaking out some
>> parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
>> ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). 
> 
> Shouldn’t it be renamed to BuildUbuntu then?

I agree, the link text/page title is confusing and there have already been 
questions about what instructions to use for building on 18.04.(yes, I see that 
it says this is for 18.04 as well, but clearly someone didn’t or they wouldn’t 
have asked)

If replacing content with a link to a dedicated page is desired practice for 
cleaning up the wiki, then I’d propose all of the material for building on 
Ubuntu be moved to that page, that it be renamed simply BuildUbuntu and that 
the main build page be left with a link to it for the Ubuntu section. As it is, 
the original build page still contains long outdated info. I would have instead 
expected to see the most current instructions there and then maybe a link for 
older versions.

Along with that, if older material for older systems and versions isn’t going 
to be moved to its own ‘archive’ page, then it should always appear down the 
page in chronological order. The current state of the build instructions is a 
bit messy in that regard.

Regards,
Adrien
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Frank H. Ellenberger]

Hi David Cousens,

In general the wiki needs some modularization to reduce redundancy. That
means, where ever you see similar text, create a new page with the best
parts and replace the pold texts with a link.

OTOH there are different target groups from expirienced coders to less
techie first time contributors to the documentation or translation.

The special art is now to find the right balance.

Am 18.09.18 um 10:19 schrieb David Cousens:
> John, David, Frank
> 
> I wonder at the value of the Build Tools page as a separate orphan entity
> given the more detailed instructions given in the Building Gnucash page.

It has been an orphan until yesterday because it has been a draft with
the intension to clarify some confusion about terms around "make". After
David T. confirmed the usability, we should replace similar texts in
other pages by a link, e.g.
https://wiki.gnucash.org/wiki/The_Make_Utility

> There is a fairly good example of dupllcation with it and the following for
> the Gnucash progarm build. 
> 
> https://wiki.gnucash.org/wiki/Building
> 
> and the breakout from it for recent Ubuntu versions
> 
> https://wiki.gnucash.org/wiki/BuildUbuntu16.04

In general I do not watch distro specific pages. While other created one
page, Ubunteros are "spamming" the wiki:
BuildGutsy, BuildUbuntu16.04, UbuntuShortcuts, Unity Shortcuts ...

Perhaps you can do some cleanup: Is Gutsy outdated?

> The main building page is a massive tome. I did start breaking out some
> parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
> ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). 

Shouldn't it be renamed to BuildUbuntu then?

> The Build Tools page may be a logical breakout from there with some
> of the detail in the first page cut into it. There is also a short
> summary recipe for building the Docs at the end of the
> BuildUbuntu16.04 page which lacks detail but does work on Ubuntu and
> most linux distros. It has no details about the dependencies in it
> though.
ISTR there are some fine parts, which should either go to Building or
get their own page linked from both.

> Would a page on building the docs be better as a breakout from the main
> building Gnucash page perhaps with a shared section on the build tools
> referenced from both. 

The Docs update page was once created by a documenter, who found the
general build page ways to complicate and was for a long time almost
untouched by code developers.

> For build instructions I ususaly find the recipe the
> most useful bit with explantions of the specific tools as breakouts. If you
> need the information and background you can follow the links. If you only do
> a build occasionally you follow the recipe.  I.e only read the manual when
> you have to.
> 
> David Cousens

Frank

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David Cousens]

John, David, Frank

I wonder at the value of the Build Tools page as a separate orphan entity
given the more detailed instructions given in the Building Gnucash page.
There is a fairly good example of dupllcation with it and the following for
the Gnucash progarm build. 

https://wiki.gnucash.org/wiki/Building

and the breakout from it for recent Ubuntu versions

https://wiki.gnucash.org/wiki/BuildUbuntu16.04

The main building page is a massive tome. I did start breaking out some
parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). The Build
Tools page may be a logical breakout from there with some of the detail in
the first page cut into it. There is also a short summary recipe for
building the Docs at the end of the BuildUbuntu16.04 page which lacks detail
but does work on Ubuntu and most linux distros. It has no details about the
dependencies in it though.

Would a page on building the docs be better as a breakout from the main
building Gnucash page perhaps with a shared section on the build tools
referenced from both. For build instructions I ususaly find the recipe the
most useful bit with explantions of the specific tools as breakouts. If you
need the information and background you can follow the links. If you only do
a build occasionally you follow the recipe.  I.e only read the manual when
you have to.

David Cousens



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David T. via gnucash-devel]

John, 

Thank you for stepping in. This looks much better now, and I believe I 
understand it, maybe. I have added a link to this page from the broader 
Documentation Update Instructions page (so it won’t be lonely).

David

> On Sep 17, 2018, at 3:04 PM, John Ralls  wrote:
> 
> 
> 
>> On Sep 17, 2018, at 10:49 AM, David T. via gnucash-devel 
>>  wrote:
>> 
>> Frank,
>> 
>>> On Sep 17, 2018, at 12:23 PM, Frank H. Ellenberger 
>>>  wrote:
>>> 
>>> Am 17.09.18 um 17:24 schrieb David T.:
 
 I worked a bit on Build Tools to make the flow seem more natural; see 
 whether you agree. 
>>> 
>>> I am no fan of "__NOTOC__" because I want often send a deep link (read
>>> page#section) to a user on IRC or MLs.
>> 
>> I think that the addition of a table of contents for a simple page is a 
>> waste of space, and pushes actual content off screen. 
>> 
>>> 
>>> The order was historical, so one could add "CMake has the following
>>> benefits over autotools …”
>>> 
>> 
>> I changed the order so that information about compiling the program would be 
>> covered before the information about compiling the documentation. I don’t 
>> see any text that lists CMake benefits versus Autotools, so perhaps this is 
>> no longer an issue?
>> 
 With the rearrangement, I remain unclear on the last portion of the 
 Autotools section, beginning with “So there remain 3 basic steps”
 
 Does the following changed text capture your intent?
 
 
 
 When using Autotools, there are 3 commonly-used commands:
 
 • autogen.sh, which should be run after you check out a copy of the 
 repository. 
 • configure [options], which should be run after you install updates of 
 your tools {not sure which tools?} or modify either makefile.am or 
 configure.ac
 • make , which is run after making edits. Common targets are all, 
 check, and install.
 
 Note that which build directory you use will affect the scope and output 
 of your command.
 
 
 I will note that for me, I *still* don’t know when I am required to re-run 
 autogen.sh or configure; is there any downside to simply running them 
 every time I mess around with the docs?
>>> 
>>> Because I saw the waekness, I worked on the section again. Can you reload?
>>> And yes, apply Johns answer. I will leave the page for now.
>> 
>> I saw your changes, but they continue to be unclear to me. Let me expand on 
>> my difficulties below
>> 
>> So there remain 3 basic steps:  <— it is unclear from the context what 
>> “remain” refers to. Remaining from what? Previously, we describe two 
>> “parts”; here we refer to “3 steps”—are these the same things?
>> 
>> <— in general, when listing “3 basic steps,” it is best for the enumerated 
>> list elements to *start* with what is being enumerated. That was a core part 
>> of the suggested text I provided above, and one I feel strongly about. As I 
>> decipher it, the three steps (which I referred to as “commands”) are 
>> autogen.sh, configure, and make. Is that correct?
>> 
>> After checking out of the repository run ./autogen.sh.
>> autogen.sh  
>> checks for the existence of autotools and (probably other build tools like 
>> intltool) and prepares your directory to use them. 
>> After you updatedat least one of the in the file mentioned tools, you should 
>> rerun it.  <— there is at least a typo here; "at least one of the” … what? 
>> “in the file mentioned tools” … what is a “file mentioned tool”?
>> Decide, which build directory to use and run the following steps in your 
>> build dir.  <— I have a problem here, insofar as it sounds as if this advice 
>> applies to step 2, but is listed as a subsidiary of step 1. Or is this a 
>> more general explanation to the effect of the note text I provided in my 
>> earlier rewrite (see above)?
>> After you
>> 
>> installed updates of not in autogen.sh mentioned tools or used libraries or  
>> <— I can’t make this out. Are you trying to say “installed updates in tools 
>> other than autogen.sh or installed other libraries”?
>> modified makefile.am or configure.ac
>> run configure [options].
>> Tip
>> configure --help will give you the full list of possible options.
>> Finally after your edits run make . Some common targets are all, 
>> check, install.
>> 
> 
> I've rewritten the page in a way that I hope is clearer and more correct for 
> David to use as a starting point.
> 
> Regards,
> John Ralls
> 

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[John Ralls]

> On Sep 17, 2018, at 10:49 AM, David T. via gnucash-devel 
>  wrote:
> 
> Frank,
> 
>> On Sep 17, 2018, at 12:23 PM, Frank H. Ellenberger 
>>  wrote:
>> 
>> Am 17.09.18 um 17:24 schrieb David T.:
>>> 
>>> I worked a bit on Build Tools to make the flow seem more natural; see 
>>> whether you agree. 
>> 
>> I am no fan of "__NOTOC__" because I want often send a deep link (read
>> page#section) to a user on IRC or MLs.
> 
> I think that the addition of a table of contents for a simple page is a waste 
> of space, and pushes actual content off screen. 
> 
>> 
>> The order was historical, so one could add "CMake has the following
>> benefits over autotools …”
>> 
> 
> I changed the order so that information about compiling the program would be 
> covered before the information about compiling the documentation. I don’t see 
> any text that lists CMake benefits versus Autotools, so perhaps this is no 
> longer an issue?
> 
>>> With the rearrangement, I remain unclear on the last portion of the 
>>> Autotools section, beginning with “So there remain 3 basic steps”
>>> 
>>> Does the following changed text capture your intent?
>>> 
>>> 
>>> 
>>> When using Autotools, there are 3 commonly-used commands:
>>> 
>>> • autogen.sh, which should be run after you check out a copy of the 
>>> repository. 
>>> • configure [options], which should be run after you install updates of 
>>> your tools {not sure which tools?} or modify either makefile.am or 
>>> configure.ac
>>> • make , which is run after making edits. Common targets are all, 
>>> check, and install.
>>> 
>>> Note that which build directory you use will affect the scope and output of 
>>> your command.
>>> 
>>> 
>>> I will note that for me, I *still* don’t know when I am required to re-run 
>>> autogen.sh or configure; is there any downside to simply running them every 
>>> time I mess around with the docs?
>> 
>> Because I saw the waekness, I worked on the section again. Can you reload?
>> And yes, apply Johns answer. I will leave the page for now.
> 
> I saw your changes, but they continue to be unclear to me. Let me expand on 
> my difficulties below
> 
> So there remain 3 basic steps:  <— it is unclear from the context what 
> “remain” refers to. Remaining from what? Previously, we describe two “parts”; 
> here we refer to “3 steps”—are these the same things?
> 
> <— in general, when listing “3 basic steps,” it is best for the enumerated 
> list elements to *start* with what is being enumerated. That was a core part 
> of the suggested text I provided above, and one I feel strongly about. As I 
> decipher it, the three steps (which I referred to as “commands”) are 
> autogen.sh, configure, and make. Is that correct?
> 
> After checking out of the repository run ./autogen.sh.
> autogen.sh  
> checks for the existence of autotools and (probably other build tools like 
> intltool) and prepares your directory to use them. 
> After you updatedat least one of the in the file mentioned tools, you should 
> rerun it.  <— there is at least a typo here; "at least one of the” … what? 
> “in the file mentioned tools” … what is a “file mentioned tool”?
> Decide, which build directory to use and run the following steps in your 
> build dir.  <— I have a problem here, insofar as it sounds as if this advice 
> applies to step 2, but is listed as a subsidiary of step 1. Or is this a more 
> general explanation to the effect of the note text I provided in my earlier 
> rewrite (see above)?
> After you
> 
> installed updates of not in autogen.sh mentioned tools or used libraries or  
> <— I can’t make this out. Are you trying to say “installed updates in tools 
> other than autogen.sh or installed other libraries”?
> modified makefile.am or configure.ac
> run configure [options].
> Tip
> configure --help will give you the full list of possible options.
> Finally after your edits run make . Some common targets are all, 
> check, install.
> 

I've rewritten the page in a way that I hope is clearer and more correct for 
David to use as a starting point.

Regards,
John Ralls

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Frank H. Ellenberger]

David,

Am 17.09.18 um 19:49 schrieb David T.:
> Frank,
> 
>> On Sep 17, 2018, at 12:23 PM, Frank H. Ellenberger 
>>  wrote:
>>
>> Am 17.09.18 um 17:24 schrieb David T.:
>>>
>>> I worked a bit on Build Tools to make the flow seem more natural; see 
>>> whether you agree. 
>>
>> I am no fan of "__NOTOC__" because I want often send a deep link (read
>> page#section) to a user on IRC or MLs.
> 
> I think that the addition of a table of contents for a simple page is a waste 
> of space, and pushes actual content off screen. 

If I can not right-click->copy the link of the section, it is a waste of
my time. Guess wich one is cheaper.

>> The order was historical, so one could add "CMake has the following
>> benefits over autotools …”
>>
> 
> I changed the order so that information about compiling the program would be 
> covered before the information about compiling the documentation. I don’t see 
> any text that lists CMake benefits versus Autotools, so perhaps this is no 
> longer an issue?

Coming soon! ;-)
No I don't know if we ever will need it. But I feel, the CMake section
might probably need more extension. And I believe, the main audience of
the page might be documenters, because coders will more often already
know the content.

>>> With the rearrangement, I remain unclear on the last portion of the 
>>> Autotools section, beginning with “So there remain 3 basic steps”
>>>
>>> Does the following changed text capture your intent?
>>>
>>>
>>> 
>>> When using Autotools, there are 3 commonly-used commands:
>>>
>>> • autogen.sh, which should be run after you check out a copy of the 
>>> repository. 
>>> • configure [options], which should be run after you install updates of 
>>> your tools {not sure which tools?} or modify either makefile.am or 
>>> configure.ac
>>> • make , which is run after making edits. Common targets are all, 
>>> check, and install.
>>>
>>> Note that which build directory you use will affect the scope and output of 
>>> your command.
>>> 
>>>
>>> I will note that for me, I *still* don’t know when I am required to re-run 
>>> autogen.sh or configure; is there any downside to simply running them every 
>>> time I mess around with the docs?
>>
>> Because I saw the waekness, I worked on the section again. Can you reload?
>> And yes, apply Johns answer. I will leave the page for now.
> 
> I saw your changes, but they continue to be unclear to me. Let me expand on 
> my difficulties below
> 
> So there remain 3 basic steps:  <— it is unclear from the context what 
> “remain” refers to. Remaining from what? Previously, we describe two “parts”; 
> here we refer to “3 steps”—are these the same things?

Before you checked out a git repo and optionally created a build
directory. (So let's move buil dir section up.) Then run the typical 3
steps of autotools Autogen flavour.

> <— in general, when listing “3 basic steps,” it is best for the enumerated 
> list elements to *start* with what is being enumerated. That was a core part 
> of the suggested text I provided above, and one I feel strongly about. As I 
> decipher it, the three steps (which I referred to as “commands”) are 
> autogen.sh, configure, and make. Is that correct?

yes

> After checking out of the repository run ./autogen.sh.
> autogen.sh  
> checks for the existence of autotools and (probably other build tools like 
> intltool) and prepares your directory to use them. 
> After you updatedat least one of the in the file mentioned tools, you should 
> rerun it.  <— there is at least a typo here; "at least one of the” … what? 
> “in the file mentioned tools” … what is a “file mentioned tool”?

updated at least
autogen.sh is the file in which the tools are mentioned.

Hypothetical example: we want support gettext translations, then
autogen.sh gets a line "intltoolize" added, because intltool is the
library for which the project needs some initialization.

> Decide, which build directory to use and run the following steps in your 
> build dir.  <— I have a problem here, insofar as it sounds as if this advice 
> applies to step 2, but is listed as a subsidiary of step 1. Or is this a more 
> general explanation to the effect of the note text I provided in my earlier 
> rewrite (see above)?
move it before the 3 steps. (see above)

> After you
> 
> installed updates of not in autogen.sh mentioned tools or used libraries or  
> <— I can’t make this out. Are you trying to say “installed updates in tools 
> other than autogen.sh or installed other libraries”?

If your system got a new version of autotools, restart with autogen.sh,
if you got a new version of libxml, restart with configure. libxml is
not mentioned in autogen.sh.

> modified makefile.am or configure.ac
> run configure [options].
> Tip
> configure --help will give you the full list of possible options.
> Finally after your edits run make . Some common targets are all, 
> check, 

Re: [GNC-dev] Documentation update problems

[David T. via gnucash-devel]

Frank,

> On Sep 17, 2018, at 12:23 PM, Frank H. Ellenberger 
>  wrote:
> 
> Am 17.09.18 um 17:24 schrieb David T.:
>> 
>> I worked a bit on Build Tools to make the flow seem more natural; see 
>> whether you agree. 
> 
> I am no fan of "__NOTOC__" because I want often send a deep link (read
> page#section) to a user on IRC or MLs.

I think that the addition of a table of contents for a simple page is a waste 
of space, and pushes actual content off screen. 

> 
> The order was historical, so one could add "CMake has the following
> benefits over autotools …”
> 

I changed the order so that information about compiling the program would be 
covered before the information about compiling the documentation. I don’t see 
any text that lists CMake benefits versus Autotools, so perhaps this is no 
longer an issue?

>> With the rearrangement, I remain unclear on the last portion of the 
>> Autotools section, beginning with “So there remain 3 basic steps”
>> 
>> Does the following changed text capture your intent?
>> 
>> 
>> 
>> When using Autotools, there are 3 commonly-used commands:
>> 
>> • autogen.sh, which should be run after you check out a copy of the 
>> repository. 
>> • configure [options], which should be run after you install updates of your 
>> tools {not sure which tools?} or modify either makefile.am or configure.ac
>> • make , which is run after making edits. Common targets are all, 
>> check, and install.
>> 
>> Note that which build directory you use will affect the scope and output of 
>> your command.
>> 
>> 
>> I will note that for me, I *still* don’t know when I am required to re-run 
>> autogen.sh or configure; is there any downside to simply running them every 
>> time I mess around with the docs?
> 
> Because I saw the waekness, I worked on the section again. Can you reload?
> And yes, apply Johns answer. I will leave the page for now.

I saw your changes, but they continue to be unclear to me. Let me expand on my 
difficulties below

So there remain 3 basic steps:  <— it is unclear from the context what “remain” 
refers to. Remaining from what? Previously, we describe two “parts”; here we 
refer to “3 steps”—are these the same things?

<— in general, when listing “3 basic steps,” it is best for the enumerated list 
elements to *start* with what is being enumerated. That was a core part of the 
suggested text I provided above, and one I feel strongly about. As I decipher 
it, the three steps (which I referred to as “commands”) are autogen.sh, 
configure, and make. Is that correct?

After checking out of the repository run ./autogen.sh.
autogen.sh  
checks for the existence of autotools and (probably other build tools like 
intltool) and prepares your directory to use them. 
After you updatedat least one of the in the file mentioned tools, you should 
rerun it.  <— there is at least a typo here; "at least one of the” … what? “in 
the file mentioned tools” … what is a “file mentioned tool”?
Decide, which build directory to use and run the following steps in your build 
dir.  <— I have a problem here, insofar as it sounds as if this advice applies 
to step 2, but is listed as a subsidiary of step 1. Or is this a more general 
explanation to the effect of the note text I provided in my earlier rewrite 
(see above)?
After you

installed updates of not in autogen.sh mentioned tools or used libraries or  <— 
I can’t make this out. Are you trying to say “installed updates in tools other 
than autogen.sh or installed other libraries”?
modified makefile.am or configure.ac
run configure [options].
Tip
configure --help will give you the full list of possible options.
Finally after your edits run make . Some common targets are all, check, 
install.




___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Frank H. Ellenberger]

Am 17.09.18 um 17:24 schrieb David T.:
> Frank,
> 
>> On Sep 17, 2018, at 10:47 AM, Frank H. Ellenberger 
>>  wrote:
>>
>> Hi David,
>>
>> Am 17.09.18 um 14:59 schrieb David T.:
>>> Hello,
>>>
>>> Can anyone give me clear language on when and why a documentation creator 
>>> would need to reissue the commands in Initializing Documentation Build 
>>> Environment? I’d like to clear this issue up on the wiki before it gets 
>>> lost.
>>>
>>> David
>>
>> because of some general confusion about the term make i.e. in
>> https://wiki.gnucash.org/wiki/The_Make_Utility, I created recently
>> https://wiki.gnucash.org/wiki/Build_Tools. It might still be incomplete
>> or contain errors, so improvements are welcome. Feel free to link it,
>> where ever required.
> 
> I worked a bit on Build Tools to make the flow seem more natural; see whether 
> you agree. 

I am no fan of "__NOTOC__" because I want often send a deep link (read
page#section) to a user on IRC or MLs.

The order was historical, so one could add "CMake has the following
benefits over autotools ..."

> With the rearrangement, I remain unclear on the last portion of the Autotools 
> section, beginning with “So there remain 3 basic steps”
> 
> Does the following changed text capture your intent?
> 
> 
> 
> When using Autotools, there are 3 commonly-used commands:
> 
> • autogen.sh, which should be run after you check out a copy of the 
> repository. 
> • configure [options], which should be run after you install updates of your 
> tools {not sure which tools?} or modify either makefile.am or configure.ac
> • make , which is run after making edits. Common targets are all, 
> check, and install.
> 
> Note that which build directory you use will affect the scope and output of 
> your command.
> 
> 
> I will note that for me, I *still* don’t know when I am required to re-run 
> autogen.sh or configure; is there any downside to simply running them every 
> time I mess around with the docs?

Because I saw the waekness, I worked on the section again. Can you reload?
And yes, apply Johns answer. I will leave the page for now.

> David
> 
> P.S. - As a professionally-trained librarian, I hesitate to engage in 
> categorization of the wiki. I am not prepared to develop a logical taxonomy 
> for the wiki at this time, and half-baked taxonomies grate upon my 
> sensibilities.

Yes, we might probably run in problems later. Despite it seems useful.
Just add from the list at
https://wiki.gnucash.org/wiki/Special:Categories
See also:
https://wiki.gnucash.org/wiki/Wiki_Conventions#Categories

Frank
---8<---

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[John Ralls]

> On Sep 17, 2018, at 8:24 AM, David T. via gnucash-devel 
>  wrote:
> 
> Frank,
> 
>> On Sep 17, 2018, at 10:47 AM, Frank H. Ellenberger 
>>  wrote:
>> 
>> Hi David,
>> 
>> Am 17.09.18 um 14:59 schrieb David T.:
>>> Hello,
>>> 
>>> Can anyone give me clear language on when and why a documentation creator 
>>> would need to reissue the commands in Initializing Documentation Build 
>>> Environment? I’d like to clear this issue up on the wiki before it gets 
>>> lost.
>>> 
>>> David
>> 
>> because of some general confusion about the term make i.e. in
>> https://wiki.gnucash.org/wiki/The_Make_Utility, I created recently
>> https://wiki.gnucash.org/wiki/Build_Tools. It might still be incomplete
>> or contain errors, so improvements are welcome. Feel free to link it,
>> where ever required.
> 
> I worked a bit on Build Tools to make the flow seem more natural; see whether 
> you agree. 
> 
> With the rearrangement, I remain unclear on the last portion of the Autotools 
> section, beginning with “So there remain 3 basic steps”
> 
> Does the following changed text capture your intent?
> 
> 
> 
> When using Autotools, there are 3 commonly-used commands:
> 
> • autogen.sh, which should be run after you check out a copy of the 
> repository. 
> • configure [options], which should be run after you install updates of your 
> tools {not sure which tools?} or modify either makefile.am or configure.ac
> • make , which is run after making edits. Common targets are all, 
> check, and install.
> 
> Note that which build directory you use will affect the scope and output of 
> your command.
> 
> 
> I will note that for me, I *still* don’t know when I am required to re-run 
> autogen.sh or configure; is there any downside to simply running them every 
> time I mess around with the docs?
> 
> David
> 
> P.S. - As a professionally-trained librarian, I hesitate to engage in 
> categorization of the wiki. I am not prepared to develop a logical taxonomy 
> for the wiki at this time, and half-baked taxonomies grate upon my 
> sensibilities.

David,

Run autogen.sh any time configure.ac or any Makefile.am changes. That might be 
because you changed it yourself or because someone else committed a change in 
git. There’s no harm in running it even if it’s not required, so the safest 
course is to do so after every pull.

Running autogen.sh creates a new configure script so you need to run configure 
after having run autogen.sh.  You also need to run it if you want to enable or 
disable building MOBI files.

Make all doesn’t do what one would expect in gnucash-docs: It doesn’t actually 
make anything. For docs you need to specify explicitly the document types you 
want, the choices being html, pdf, epub, mobi, and, on Windows only, chm.

Regards,
John Ralls

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David T. via gnucash-devel]

Frank,

> On Sep 17, 2018, at 10:47 AM, Frank H. Ellenberger 
>  wrote:
> 
> Hi David,
> 
> Am 17.09.18 um 14:59 schrieb David T.:
>> Hello,
>> 
>> Can anyone give me clear language on when and why a documentation creator 
>> would need to reissue the commands in Initializing Documentation Build 
>> Environment? I’d like to clear this issue up on the wiki before it gets lost.
>> 
>> David
> 
> because of some general confusion about the term make i.e. in
> https://wiki.gnucash.org/wiki/The_Make_Utility, I created recently
> https://wiki.gnucash.org/wiki/Build_Tools. It might still be incomplete
> or contain errors, so improvements are welcome. Feel free to link it,
> where ever required.

I worked a bit on Build Tools to make the flow seem more natural; see whether 
you agree. 

With the rearrangement, I remain unclear on the last portion of the Autotools 
section, beginning with “So there remain 3 basic steps”

Does the following changed text capture your intent?



When using Autotools, there are 3 commonly-used commands:

• autogen.sh, which should be run after you check out a copy of the repository. 
• configure [options], which should be run after you install updates of your 
tools {not sure which tools?} or modify either makefile.am or configure.ac
• make , which is run after making edits. Common targets are all, 
check, and install.

Note that which build directory you use will affect the scope and output of 
your command.


I will note that for me, I *still* don’t know when I am required to re-run 
autogen.sh or configure; is there any downside to simply running them every 
time I mess around with the docs?

David

P.S. - As a professionally-trained librarian, I hesitate to engage in 
categorization of the wiki. I am not prepared to develop a logical taxonomy for 
the wiki at this time, and half-baked taxonomies grate upon my sensibilities.


> 
> You might also counter check the recent changes in
> Documentation_Update_Instructions:
> https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions=revision=14469=13948
> 
> and other pages of
> https://wiki.gnucash.org/wiki/Category:Development .
> 
> N.B.: It would be nice, if you would add categories to
> https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment
> 
>>> On Sep 14, 2018, at 10:21 AM, David T.  wrote:
>>> 
>>> Frank, Geert,
>>> 
>>> I am finally following up on this thread, and I’d like to note that the 
>>> information that Frank says “got lost,” and which Geert has re-entered on 
>>> this page were actually moved to a different page 
>>> (https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment 
>>> )
>>>  and the reference to this information was moved up to Section 2. Setting 
>>> Up Your System.
>>> 
>>> Here we have an example of how duplicative information ends up in our 
>>> ecosystem!
> 
> That is a nice example, why you should make smaller changes. Instead of
> "Major rewrite of entire page" it would be better readable, if you would
> use separate steps of logical units:
> Move Section x in a new page;
> Move section y to appropriate position;
> Rewordening of section z; ...
> 
> :
> 
> Regards
> Frank
> 

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Frank H. Ellenberger]

Hi David,

Am 17.09.18 um 14:59 schrieb David T.:
> Hello,
> 
> Can anyone give me clear language on when and why a documentation creator 
> would need to reissue the commands in Initializing Documentation Build 
> Environment? I’d like to clear this issue up on the wiki before it gets lost.
> 
> David

because of some general confusion about the term make i.e. in
https://wiki.gnucash.org/wiki/The_Make_Utility, I created recently
https://wiki.gnucash.org/wiki/Build_Tools. It might still be incomplete
or contain errors, so improvements are welcome. Feel free to link it,
where ever required.

You might also counter check the recent changes in
Documentation_Update_Instructions:
https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions=revision=14469=13948

and other pages of
https://wiki.gnucash.org/wiki/Category:Development .

N.B.: It would be nice, if you would add categories to
https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment

>> On Sep 14, 2018, at 10:21 AM, David T.  wrote:
>>
>> Frank, Geert,
>>
>> I am finally following up on this thread, and I’d like to note that the 
>> information that Frank says “got lost,” and which Geert has re-entered on 
>> this page were actually moved to a different page 
>> (https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment 
>> )
>>  and the reference to this information was moved up to Section 2. Setting Up 
>> Your System.
>>
>> Here we have an example of how duplicative information ends up in our 
>> ecosystem!

That is a nice example, why you should make smaller changes. Instead of
"Major rewrite of entire page" it would be better readable, if you would
use separate steps of logical units:
Move Section x in a new page;
Move section y to appropriate position;
Rewordening of section z; ...

:

Regards
Frank

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David T. via gnucash-devel]

Hello,

Can anyone give me clear language on when and why a documentation creator would 
need to reissue the commands in Initializing Documentation Build Environment? 
I’d like to clear this issue up on the wiki before it gets lost.

David

> On Sep 14, 2018, at 10:21 AM, David T.  wrote:
> 
> Frank, Geert,
> 
> I am finally following up on this thread, and I’d like to note that the 
> information that Frank says “got lost,” and which Geert has re-entered on 
> this page were actually moved to a different page 
> (https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment 
> ) 
> and the reference to this information was moved up to Section 2. Setting Up 
> Your System.
> 
> Here we have an example of how duplicative information ends up in our 
> ecosystem!
> 
> For the future, we should change the Documentation Update Instructions in 
> this section to point instead to the separate page set up for it. However, 
> there needs to be a clear instruction here as to why a user might need to 
> re-prepare their build environment. I, for one, have no idea why my build 
> environment was broken. I had already followed those directions previously 
> (as evidenced by the existence of the build folder structure on my system), 
> so what broke them? I imagine something along the lines of:
> 
> “If you have not built the documentation before, or if you {have changed some 
> miniscule aspect of your system | are incompetent like David T.}, it is 
> usually necessary to reconfigure your build environment as outlined in 
> Initializing Documentation Build Environment.”
> 
> Cheers,
> David
> 
>> On Aug 17, 2018, at 3:25 PM, Frank H. Ellenberger 
>> mailto:frank.h.ellenber...@gmail.com>> wrote:
>> 
>> Am 17.08.2018 um 09:18 schrieb Geert Janssens:
>>> Op vrijdag 17 augustus 2018 08:41:05 CEST schreef David T. via 
>>> gnucash-devel:
>> :
>> 
 I’m not sure why there’s a “missing” in the initial command, and I don’t
 know where config.guess is supposed to be—and I won’t even try to guess.
 
 I would love to have some guidance.
 
>>> 
>>> I went to look at the wiki page and unfortunately it's incomplete. You get 
>>> this error because a few essential commands have been omitted.
>>> 
>>> I have added a section that should fill the gap. Can you proofread this:
>>> https://wiki.gnucash.org/wiki/ 
>>> Documentation_Update_Instructions#Prepare_The_Build_Directory
>>> And report back any issues you experience ?
>>> 
>>> It's written these steps are usually done early in in the set up process, 
>>> but 
>>> you can still run them right now and then retry the validation.
>>> 
>>> Geert
>> 
>> Yeah, the missing section got lost in
>> https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions=revision=13215=12785
>>  
>> 
>> 
>> OTOH it was a major improvement of the readability.
>> 
>> Regards
>> Frank
>> 
> 

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[David T. via gnucash-devel]

Frank, Geert,

I am finally following up on this thread, and I’d like to note that the 
information that Frank says “got lost,” and which Geert has re-entered on this 
page were actually moved to a different page 
(https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment 
) 
and the reference to this information was moved up to Section 2. Setting Up 
Your System.

Here we have an example of how duplicative information ends up in our ecosystem!

For the future, we should change the Documentation Update Instructions in this 
section to point instead to the separate page set up for it. However, there 
needs to be a clear instruction here as to why a user might need to re-prepare 
their build environment. I, for one, have no idea why my build environment was 
broken. I had already followed those directions previously (as evidenced by the 
existence of the build folder structure on my system), so what broke them? I 
imagine something along the lines of:

“If you have not built the documentation before, or if you {have changed some 
miniscule aspect of your system | are incompetent like David T.}, it is usually 
necessary to reconfigure your build environment as outlined in Initializing 
Documentation Build Environment.”

Cheers,
David

> On Aug 17, 2018, at 3:25 PM, Frank H. Ellenberger 
>  wrote:
> 
> Am 17.08.2018 um 09:18 schrieb Geert Janssens:
>> Op vrijdag 17 augustus 2018 08:41:05 CEST schreef David T. via gnucash-devel:
> :
> 
>>> I’m not sure why there’s a “missing” in the initial command, and I don’t
>>> know where config.guess is supposed to be—and I won’t even try to guess.
>>> 
>>> I would love to have some guidance.
>>> 
>> 
>> I went to look at the wiki page and unfortunately it's incomplete. You get 
>> this error because a few essential commands have been omitted.
>> 
>> I have added a section that should fill the gap. Can you proofread this:
>> https://wiki.gnucash.org/wiki/
>> Documentation_Update_Instructions#Prepare_The_Build_Directory
>> And report back any issues you experience ?
>> 
>> It's written these steps are usually done early in in the set up process, 
>> but 
>> you can still run them right now and then retry the validation.
>> 
>> Geert
> 
> Yeah, the missing section got lost in
> https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions=revision=13215=12785
> 
> OTOH it was a major improvement of the readability.
> 
> Regards
> Frank
> 

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Frank H. Ellenberger]

Am 17.08.2018 um 09:18 schrieb Geert Janssens:
> Op vrijdag 17 augustus 2018 08:41:05 CEST schreef David T. via gnucash-devel:
:

>> I’m not sure why there’s a “missing” in the initial command, and I don’t
>> know where config.guess is supposed to be—and I won’t even try to guess.
>>
>> I would love to have some guidance.
>>
> 
> I went to look at the wiki page and unfortunately it's incomplete. You get 
> this error because a few essential commands have been omitted.
> 
> I have added a section that should fill the gap. Can you proofread this:
> https://wiki.gnucash.org/wiki/
> Documentation_Update_Instructions#Prepare_The_Build_Directory
> And report back any issues you experience ?
> 
> It's written these steps are usually done early in in the set up process, but 
> you can still run them right now and then retry the validation.
> 
> Geert

Yeah, the missing section got lost in
https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions=revision=13215=12785

OTOH it was a major improvement of the readability.

Regards
Frank

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation update problems

[Geert Janssens]

Op vrijdag 17 augustus 2018 08:41:05 CEST schreef David T. via gnucash-devel:
> Hello,
> 
> If I am working on updating the documentation, it must be time for me to
> bang my head against some command line hiccup!  Yup! Right
> on time.
> 
> Following my handy-dandy git cheat sheet, I’ve pulled from
> github.com/gnucash/gnucash-docs 
> and pushed to github.com/sunfish62/gnucash-docs
> . I then entered all my edits to
> ch_basics.xml and saved.
> 
> Next, I went to the wiki
> (https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Validate_Y
> our_Changes
>  our_Changes>) and found the instructions to “make check” the guide. So, in
> Terminal, I cd to my build directory for the guide
> (/Volumes/Media/Development/Gnucash/gnucash-docs/build/guide) and issue
> “make clean”
> 
> This is what I get:
> 
> cd .. && /Applications/Xcode.app/Contents/Developer/usr/bin/make 
> am--refresh CDPATH="${ZSH_VERSION+.}:" && cd .. && /bin/sh
> /Volumes/Media/Development/Gnucash/gnucash-docs/missing aclocal-1.15 cd ..
> && /bin/sh /Volumes/Media/Development/Gnucash/gnucash-docs/missing
> automake-1.15 --gnu configure.ac:6: error: required file './config.guess'
> not found
> configure.ac:6:   'automake --add-missing' can install 'config.guess'
> configure.ac:6: error: required file './config.sub' not found
> configure.ac:6:   'automake --add-missing' can install 'config.sub'
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/C/Makefile.am:42:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/C/Makefile.am:42:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/de/Makefile.am:40:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/de/Makefile.am:40:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/ja/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/ja/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/pt/Makefile.am:43:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/pt/Makefile.am:43:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/ru/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/ru/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> help/C/Makefile.am:33:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> help/C/Makefile.am:33:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> help/de/Makefile.am:20:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> help/de/Makefile.am:20:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> help/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:85: warning: 

Re: [GNC-dev] Documentation update problems

[David T. via gnucash-devel]

For what it’s worth, I was able to dig out the old xmllint/xsltproc commands 
and test and view my edits. 

I’d still love to know how I’ve f**ked up my development environment so that 
the currently-sanctioned approach (make|make clean|make install|make hay while 
the sun shines) doesn’t work.

Perhaps this is another instance of not trying to teach old dogs new tricks.

David


> On Aug 16, 2018, at 11:41 PM, David T. via gnucash-devel 
>  wrote:
> 
> Hello,
> 
> If I am working on updating the documentation, it must be time for me to bang 
> my head against some command line hiccup!  Yup! Right on time.
> 
> Following my handy-dandy git cheat sheet, I’ve pulled from 
> github.com/gnucash/gnucash-docs  and 
> pushed to github.com/sunfish62/gnucash-docs 
> . I then entered all my edits to 
> ch_basics.xml and saved. 
> 
> Next, I went to the wiki 
> (https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Validate_Your_Changes
>  
> )
>  and found the instructions to “make check” the guide. So, in Terminal, I cd 
> to my build directory for the guide 
> (/Volumes/Media/Development/Gnucash/gnucash-docs/build/guide) and issue “make 
> clean”
> 
> This is what I get:
> 
> cd .. && /Applications/Xcode.app/Contents/Developer/usr/bin/make  am--refresh
> CDPATH="${ZSH_VERSION+.}:" && cd .. && /bin/sh 
> /Volumes/Media/Development/Gnucash/gnucash-docs/missing aclocal-1.15 
> cd .. && /bin/sh /Volumes/Media/Development/Gnucash/gnucash-docs/missing 
> automake-1.15 --gnu
> configure.ac:6: error: required file './config.guess' not found
> configure.ac:6:   'automake --add-missing' can install 'config.guess'
> configure.ac:6: error: required file './config.sub' not found
> configure.ac:6:   'automake --add-missing' can install 'config.sub'
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/C/Makefile.am:42:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/C/Makefile.am:42:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/de/Makefile.am:40:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/de/Makefile.am:40:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/ja/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/ja/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/pt/Makefile.am:43:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/pt/Makefile.am:43:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/ru/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/ru/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:54: (probably a GNU make extension)
> help/C/Makefile.am:33:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:85: (probably a GNU make extension)
> help/C/Makefile.am:33:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
> variable name
> xmldocs.make:54: (probably a GNU make extension)
> help/de/Makefile.am:20:   'xmldocs.make' included from 

[GNC-dev] Documentation update problems

[David T. via gnucash-devel]

Hello,

If I am working on updating the documentation, it must be time for me to bang 
my head against some command line hiccup!  Yup! Right on time.

Following my handy-dandy git cheat sheet, I’ve pulled from 
github.com/gnucash/gnucash-docs  and 
pushed to github.com/sunfish62/gnucash-docs 
. I then entered all my edits to 
ch_basics.xml and saved. 

Next, I went to the wiki 
(https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Validate_Your_Changes
 
)
 and found the instructions to “make check” the guide. So, in Terminal, I cd to 
my build directory for the guide 
(/Volumes/Media/Development/Gnucash/gnucash-docs/build/guide) and issue “make 
clean”

This is what I get:

cd .. && /Applications/Xcode.app/Contents/Developer/usr/bin/make  am--refresh
CDPATH="${ZSH_VERSION+.}:" && cd .. && /bin/sh 
/Volumes/Media/Development/Gnucash/gnucash-docs/missing aclocal-1.15 
 cd .. && /bin/sh /Volumes/Media/Development/Gnucash/gnucash-docs/missing 
automake-1.15 --gnu
configure.ac:6: error: required file './config.guess' not found
configure.ac:6:   'automake --add-missing' can install 'config.guess'
configure.ac:6: error: required file './config.sub' not found
configure.ac:6:   'automake --add-missing' can install 'config.sub'
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:54: (probably a GNU make extension)
guide/C/Makefile.am:42:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:85: (probably a GNU make extension)
guide/C/Makefile.am:42:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:54: (probably a GNU make extension)
guide/de/Makefile.am:40:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:85: (probably a GNU make extension)
guide/de/Makefile.am:40:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:54: (probably a GNU make extension)
guide/it/Makefile.am:11:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:85: (probably a GNU make extension)
guide/it/Makefile.am:11:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:54: (probably a GNU make extension)
guide/ja/Makefile.am:37:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:85: (probably a GNU make extension)
guide/ja/Makefile.am:37:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:54: (probably a GNU make extension)
guide/pt/Makefile.am:43:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:85: (probably a GNU make extension)
guide/pt/Makefile.am:43:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:54: (probably a GNU make extension)
guide/ru/Makefile.am:37:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:85: (probably a GNU make extension)
guide/ru/Makefile.am:37:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:54: (probably a GNU make extension)
help/C/Makefile.am:33:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:85: (probably a GNU make extension)
help/C/Makefile.am:33:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:54: (probably a GNU make extension)
help/de/Makefile.am:20:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:85: (probably a GNU make extension)
help/de/Makefile.am:20:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:54: (probably a GNU make extension)
help/it/Makefile.am:11:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX 
variable name
xmldocs.make:85: (probably a GNU make extension)
help/it/Makefile.am:11:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls