[GNC-dev] Documentation update problems

John Ralls jralls at ceridwen.us
Mon Sep 17 15:04:09 EDT 2018



> 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



More information about the gnucash-devel mailing list