Document Update Instructions have been revised

Frank H. Ellenberger frank.h.ellenberger at
Mon Jan 23 03:09:13 EST 2017

Hi all,

just a few ideas:
I found by accident the 10 years old ff., which is
an example for using subpages in a template .

Don't confuse it with the more recent which is more a todo list and
ancestor of the Document Update Instructions

Recently I was asking myself and Gert, if we should move the nice
written sections about
in the basic existing page
or a new page Autotools and linking it from Building_Gnucash and
Translation, too.
That would have the benefit there would be only one page to maintain
almost everything about the autotools components. OTOH some users could
be distracted by the jumping between the pages.

Your opinion?

I understand that the pull request is the adequate way for a longtime
contributor on the mailing list like  you, David. But it would be too
much overhead to create an github account, a ssh key, ... to send a
patch for a typo by a random reader.


Am 22.01.2017 um 01:35 schrieb Chris Good:
>> -----Original Message-----
>> From: David T. [mailto:sunfish62 at]
>> Sent: Saturday, 21 January 2017 6:38 PM
>> To: Chris Good <chris.good at>
>> Cc: GnuCash Developers <gnucash-devel at>
>> Subject: Re: Document Update Instructions have been revised
>> Chris, Geert,
>> I have to admit that I have put off reading through the changes that you’ve
>> collectively put in on this wiki page, in part because I am *that* contributor—
>> you know, the one who barely understands what he is doing, and is wary of
>> changing the way he does something for fear that it will break and never
>> work again.
>> I have begun to work through this page one more time, and I will no doubt
>> have changes and suggestions later on. I will refer to my sentence above,
>> however, and note that my editorial inclinations are limited by my limited
>> understanding of the technologies and expectations for this process
>> generally.
>> I have a few top level comments:
>> A - This page has gotten quite large. Should it be broken into smaller pieces?
>> B - I would like to see this page separate out the different aspects of the
>> process more cleanly. Currently, it seems that the set up of the technologies,
>> the application of the technologies, and the practices we use are all
>> intermingled. This makes it harder to focus on one aspect. For example,
>> Steps 2-5 should be separated out into a separate page on setting up Git for
>> use with documentation.
>> C - I think the Preface should outline as simply as possible the overall process,
>> which I understand to be:
>> 1) Contributors propose changes using Bugzilla.
>> 2) Contributors use a VCS (git), to make these changes locally.
>> 3) Changes are validated locally.
>> 4) Contributors submit these changes for approval.
>> 5) Changes are approved and incorporated into the doc set.
>> This overview could then be used to structure the remaining sections.
>> I think that the information that currently resides in the Preface is useful,
>> however, and I’d like to see it moved into other areas as appropriate.
>> D - Upon initial examination, I see that all reference to how it used to be
>> done (i.e., the individual xslt and xmllint commands) has been removed from
>> the page. While I understand that you two believe that this is the right way to
>> move forward, it leaves me in a quandary. I already have a local copy, and I
>> know that I can issue some commands to check and compile my local copy,
>> but I always refer back to the wiki for the exact commands, which you’ve
>> removed. I would prefer that some inclusion of these other methods be
>> mentioned in some way.
>> I began to make some of these changes myself, but given my limited abilities
>> with these processes, I thought it better to discuss the changes here before
>> unilaterally (and ill-informedly) making the changes directly.
>> David
>>> On Jan 17, 2017, at 5:16 AM, Chris Good <chris.good at>
>> wrote:
>>> Hi,
>>> I've finished updating the wiki Document Update Instructions [1] to
>>> include instructions for using 'make' rather than xmllint and xsltproc
>> directly.
>>> Thank you very much Geert for all the info.
>>> [1]
>>> Regards, Chris Good
> Hi David,
> A - IMHO I don't think this page is too large. It is quite easy to navigate using the index at the top. It would be annoying to have to jump to multiple pages.
> B - I agree it could be better structured. I don't think it needs a new page. If you're going to put 3.2 to 3.5 into a separate git set up section, it would be good if you could include some instructions on how to start a new modification (including rebasing) having already set up git and your build directory structure previously.
> I previously created Git_For_Newbies with the idea that new users should really be using that for all the git stuff (using Pull Requests instead of Patches if possible). Git_For_Newbies applies equally to the documentation as to the programs. I haven't gotten around to fixing Documentation_Update_Instructions yet. If you can, Great! :-) It may be that much of Git_For_Newbies needs to be brought into Documentation_Update_Instructions but changed to specifically refer to the documentation. But that seems like a lot of duplication...
> C - Having an additional outline as you suggest may be helpful, although the index already gives a 1 page summary - on my new 27" monitor anyway :-). I'm not sure I agree with moving the stuff already in the Preface into other areas. I think it is useful to get some detail of what is involved before reading everything.
> D - Why do you need the original xmllint + xsltproc commands? Don't the 'make' commands work for you? In my experience, 'make' is installed by default in all the Linux distros I've used (not many I admit). Is that not the case in Mac OSX? You can create a build directory structure within your existing local repo. I thought about leaving the original commands in the documentation but couldn't think of any reason they should be needed. They would just confuse new documenters.
> Regards, Chris Good

More information about the gnucash-devel mailing list