[GNC-dev] Documentation update problems

[David T.]

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 <jralls at ceridwen.us> wrote:
> 
> 
> 
>> On Sep 17, 2018, at 10:49 AM, David T. via gnucash-devel <gnucash-devel at gnucash.org> wrote:
>> 
>> Frank,
>> 
>>> On Sep 17, 2018, at 12:23 PM, Frank H. Ellenberger <frank.h.ellenberger at gmail.com> 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 <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?
>>> 
>>> 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 <https://github.com/Gnucash/gnucash-docs/blob/maint/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 <target>. 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
>