Using make with docs

Geert Janssens geert.gnucash at kobaltwit.be
Mon Feb 6 12:10:53 EST 2017


Op maandag 6 februari 2017 21:28:24 CET schreef David T. via gnucash-devel:
> Hello,
> 
> The recently-updated Documentation Update Instructions page on the wiki—as
> detailed as they are—nonetheless leave something to be desired when one
> reaches step 10. You see, up until this point, a great deal of energy is
> put into showing how one can use “make check” in different ways to test
> either the Guide, or the Help, or the different translations.
> 
> Once you get to actually compiling these docs, though, the directions dry up
> and just tell the user to "make html” in "the appropriate directory within
> the build directory structure.” (ADWTBDS)
> 
> Two points:
> 
> 1) when I issue “make check”, I am in the working directory, and if you’re
> stupid or inattentive (both of which apparently apply to me), you issue the
> “make html” command without first changing to the ADWTBDS.
Acutally, make check is also meant to be run in the build directory. *All* 
make commands are intended to be executed in the build directory or one if its 
subdirectories. I'm not sure this is very clearly specified in the wiki page.

The fact you can run "make check" in your working directory implies you have 
in the past run configure in your working directory. By that action you have 
configured your working directory to double as a build directory. It would 
simplify your life if you remove these configure actions from the working 
directory again. By doing so, running "make <whatever>" there would give an 
error like this:
make: *** No rule to make target 'check'.  Stop.

That should solve your problem of accidentally building the html docs in your 
git working directory.

The easiest way to remove the files set up by configure would be:
- cd into to root of your local git repository (the level where you see guide 
and help as subdirectories)
- run: "make distclean" (without the quotes)
- and finally rerun "./autogen.sh" (again without the quotes)

> This results in
> the docs being built right there in the working directory. Not horrible,
> but potentially messy (especially if you forget to remove the folder before
> going back to git).
> 
> 2) If I change to my build directory, “make html” builds all the docs, which
> is a collossal waste of time when all I want to do is compile the Guide in
> (say) English—which is all I worked on in the first place. I personally
> don’t plan on ever editing the Portugese, German, Italian, or Japanese
> translations.
> 
> So, two questions:
> 
> 1) Is there a way to configure the make command to use my build directory as
> its destination, while running from the working directory?
Not that I know of.
> 2) Is there a
> way to make just the html of one portion of the docs, without making all
> docs in all languages?
Yes. You can do so by invoking "make html" in the exact build subdirectory 
that matches the subdirectory in your git repository. For example to build the 
English guide as html, you would starting from your build directory
cd guide/C
make html

"The appropriate directory in the build directory structure" was meant to 
suggest exactly that. I see the way it's formulated is still too developer-
mind oriented. Sorry about that. Perhaps "the equivalent subdirectory under 
the build directory" is more clear ? How would you propose to better describe 
this ?

Geert


More information about the gnucash-devel mailing list