Using make with docs

[Chris Good]

> Message: 3
> Date: Mon, 6 Feb 2017 22:29:51 +0500
> From: "David T." <sunfish62 at yahoo.com>
> To: Geert Janssens <geert.gnucash at kobaltwit.be>
> Cc: gnucash-devel at gnucash.org
> Subject: Re: Using make with docs
> Message-ID: <DE38B2C5-32BD-4481-BD22-EE0F4D956A77 at yahoo.com>
> Content-Type: text/plain; charset=utf-8
> 
> 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

Hi David T,

I had made some changes to the Documentation Update Instructions sections
dealing with "make check" + "make html" to make it clearer that these
commands should be run from within the build directory structure.
Feel free to improve further if you think necessary.

I'll say again, IMHO I think the instructions re setting up the build system
belong in this page. Maybe grouping them under a new heading, something like
"Build System One-Time Setup", would be a slight be an improvement.

Regards, Chris Good
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4817 bytes
Desc: not available
URL: <http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20170207/51109951/attachment.p7s>