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.
Don't forget Johns answer.
Frank
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
