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 <jra...@ceridwen.us> wrote:
>
>
>
>> On Sep 17, 2018, at 10:49 AM, David T. via gnucash-devel
>> <gnucash-devel@gnucash.org> wrote:
>>
>> Frank,
>>
>>> On Sep 17, 2018, at 12:23 PM, Frank H. Ellenberger
>>> <frank.h.ellenber...@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
>
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
