[GNC-dev] Documentation update problems

Frank H. Ellenberger frank.h.ellenberger at gmail.com
Mon Sep 17 14:56:22 EDT 2018


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

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



More information about the gnucash-devel mailing list