Some Assistance Please

[Geert Janssens]

On dinsdag 25 april 2017 16:33:37 CEST David T. via gnucash-devel wrote:
> Hello,
> 
> Once again, the documentation bug has bit me, and I am trying to use the
> accepted GnuCash toolset to implement a change to the Guide.
> 
> Most recently, this toolset has been changed to use “make”, and when I
> attempt to refresh my memory by going to the wiki page, I fail to find an
> explanation that makes sense to me.
> 
> My environment is as follows:
> 
> OS: Mac
> Git clone saved in ~/Development/Gnucash/docs
I will refer to the above directory as your source directory later on. And any 
path below this directory is part of what I call your source tree.
> Build directory in ~/Development/GnuCash/build
Similarly here, I'll be referring to a build directory and build tree.

> upstream: github.com/Gnucash/gnucash-docs
> origin: github.com/sunfish62/gnucash-docs
> 
> Specifically, if I have an already-existing installation of the downloaded
> documentation source that I have pushed and pulled into alignment with
> github, and I have finished editing the source files, what are the precise
> commands I need to invoke to get a tested and compiled local documentation
> set?
> 
> Today, I used “make check” from ~/Development/Gnucash/docs/guide/C and all
> seemed to work; I got no errors following the actual xmllint command.

This suggests you have run the configure command from one of the directories 
in your source tree. From the errors you mention this may be in
~/Development/Gnucash/docs/guide/C

By doing so you may have implicitly configured your source directory resulting 
in the errors below. As a rule of thumb, avoid running any "make" command in 
your source tree. The only commands that make sense there are git commands to 
manage your commits (including pushing and pulling from/to upstream) and "./
autogen.sh" in the root level of your source tree.

"configure" on the other hand should always be called from within the root of 
your build directory. From then on "make <whatever>" can be called from any 
directory in your build tree.

And to avoid any confusion "from within the root of your build directory" 
means you cd into your build directory and then invoke configure. As configure 
itself is not in your build directory, but in your source directory, you'll 
need to call it with its full path. This gives:
cd ~/Development/GnuCash/build
~/Development/Gnucash/docs/configure

> When
> I changed over to ~/Development/GnuCash/build/guide/C and entered “make
> html” (per the wiki), I received an error:
> 
> configure: error: source directory already configured; run "make distclean"
> there first
> 
> I went to the docs folder and entered “make distclean” and got some output.
> I then returned to build/guide/C and tried again. I get the same error. No
> combination of make commands seems to move the process along.

You may have to call make distclean directly in
~/Development/GnuCash/build/guide/C
if that is where you accidentally ran configure from before. Note you will 
only be able to run make distclean successfully once in each configured 
directory. That command will throw away all filed that were automatically 
generated by autogen.sh and configure (not your manual changes to the source 
files though, which is good).

If you hesitate which directories you may have run configure in, you can 
search for a file called config.log. Each directory that contains this file 
was at some point in the past "configured" as the error message suggests. With 
the exception of your true build directory in each of these directories you 
can run make distclean once.

That's one approach to clean up, using the tools provided by make and friends 
itself. Another approach would be to use git instead. Git knows which files 
belong in your source tree and which ones are generated.

*** Important *** If you want to use the git way, first make sure *all* your 
current changes are committed at least locally. That is all your changes 
should have been git add'ed and git commit'ed. git status should only show you 
untracked files for which you know you didn't edit/create them manually. 
Anything that's not committed will be deleted.

From there on it's easy.
Cd into your source directory
run "git clean -fx"
rerun "./autogen.sh"
cd into your build directory
run ~/Development/Gnucash/docs/configure
cd to wherever in your build tree you want to run a make command
execute the make command

> 
> Thanks,
> David
> 
> P.S.: I continue to think that the wiki page is poorly-constructed for
> general users. In specific, I object to the high-level structure that
> embeds the initial setup steps with the ongoing editorial process. In my
> situation, I find it impossible to separate the setup commands from those
> that I actually need to proceed.

I sympathize. Unfortunately I'm no longer in a position to be able to estimate 
what works for general users as you call it. It seems this is also a variable 
term. Some users like lots of context, others prefer a short list of commands. 
What structure would you propose ? Are you willing to attempt a restructuring 
of the page to something you see better fit ? Don't worry if some of the info 
your would write there is not completely correct. We can adjust this as we 
continue. I just would love to find a structure that works well for a wide 
audience first.

Regards,

Geert