Using make with docs

[David T.]

Geert,

> On Feb 6, 2017, at 10:10 PM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
> 
> 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.
> 

No doubt this has something to do with earlier setup issues (steps 3 & 4). Or it has to do with the fact that the earlier method (calling xmllint and xsltproc directly) was invoked in the working directory, with output directed to a different folder directly, and I learned that way and kept doing it (like the proverbial lemming of Arthur Clarke’s short story).

<aside>I reiterate my wish to see documentation that covers *setting up a build system* separated from information *directly related to the documentation update process*. Having a separate setup page would allow those of us who struggle with every aspect of this process to be able to get set up, and then focus on screwing up only the actual steps for updating, rather than the whole shebang.</aside>


> 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


Thank you for clearly outlining to me (once more!) how to handle these issues. I will look into better ways of wording things to make it clearer to others.

Cheers,
David