[GNC-dev] Documentation update problems

[David T.]

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.


> 
> You might also counter check the recent changes in
> Documentation_Update_Instructions:
> https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions&type=revision&diff=14469&oldid=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. <sunfish62 at yahoo.com> 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 <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
>