[GNC-dev] Documentation update problems

[John Ralls]

> On Sep 17, 2018, at 8:24 AM, David T. via gnucash-devel <gnucash-devel at gnucash.org> wrote:
> 
> Frank,
> 
>> On Sep 17, 2018, at 10:47 AM, Frank H. Ellenberger <frank.h.ellenberger at gmail.com> 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 <target>, 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