> On Sep 17, 2018, at 11:56 AM, Frank H. Ellenberger
> <frank.h.ellenber...@gmail.com> wrote:
>
> David,
>
> Am 17.09.18 um 19:49 schrieb David T.:
>> 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.
>
> If I can not right-click->copy the link of the section, it is a waste of
> my time. Guess wich one is cheaper.
>
>>> 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?
>
> Coming soon! ;-)
> No I don't know if we ever will need it. But I feel, the CMake section
> might probably need more extension. And I believe, the main audience of
> the page might be documenters, because coders will more often already
> know the content.
>
>>>> 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?
>
> Before you checked out a git repo and optionally created a build
> directory. (So let's move buil dir section up.) Then run the typical 3
> steps of autotools Autogen flavour.
>
>> <— 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?
>
> yes
>
>> 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”?
>
> updated at least
> autogen.sh is the file in which the tools are mentioned.
>
> Hypothetical example: we want support gettext translations, then
> autogen.sh gets a line "intltoolize" added, because intltool is the
> library for which the project needs some initialization.
>
>> 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)?
> move it before the 3 steps. (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”?
>
> If your system got a new version of autotools, restart with autogen.sh,
> if you got a new version of libxml, restart with configure. libxml is
> not mentioned in autogen.sh.
>
>> 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.
>
There's no need to rerun autogen.sh because you've updated one of the autotools
components. Once configure is generated it's independent of autoconf, automake,
and the rest. The only external change that might get one to rerun autogen.sh
would be a libtool update because it would insert the newer ltmain.sh... but
that only applies to building code, not documentation. Intltool isn't actively
maintained so intltoolize isn't going to change.
Regards,
John Ralls
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
