[GNC-dev] Documentation update problems

David T. sunfish62 at yahoo.com
Mon Sep 17 13:49:36 EDT 2018


> 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].
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.

More information about the gnucash-devel mailing list