XML Parse error on Local Build

[Chris Good]

> Message: 2
> Date: Wed, 07 Dec 2016 20:36:30 +0100
> From: Geert Janssens <geert.gnucash at kobaltwit.be>
> To: gnucash-devel at gnucash.org, "David T." <sunfish62 at yahoo.com>
> Subject: Re: XML Parse error on Local Build
> Message-ID: <1942799.LyrSZbBnvp at legolas.kobaltwit.lan>
> Content-Type: text/plain; charset="us-ascii"
>
> Op dinsdag 6 december 2016 17:05:37 CET schreef David T. via
gnucash-devel:
> > Hi,
> >
> > I am trying to finish a first pass at a new Glossary for the Guide. My
> > changes are focused in a new file (gnc-glossary.xml) and in
> > gnucash-guide.xml. In the latter, I have added two lines to
> > incorporate the new file into the guide.
> >
> > I have reached the point of running the commands:
> >
> > xmllint --valid --noout gnucash-guide.xml xsltproc -o
> > ../../../output_html/guide/ ../../xsl/general-customization.xsl
> > gnucash-guide.xml
> >
> > These are prescribed by the Wiki page.
>
> A side note, more targeted at Chris who's done an excellent job so far to
> keep the Documentation Update wiki page up to date:
> I haven't fully read that page in a long time, so this never struck me 
> before:
>
> I wonder why you explicitly explain to use xmllint and xsltproc ?
> Both commands are incorporated in the makefile system for the
> documentation.
>
> So my typical flow (after a git clone/checkout/pull whatever) is
> - in the gnucash-docs directory run "./autogen.sh"
> - then make a build directory to keep the build documentation out of the
> source tree for cleanliness. Let's call that directory "build" for this 
> example.
> Typically this can be done using "mkdir build"
> - Then from within the build directory call configure. Assuming build is a

> direct
> subdirectory of gnucash-docs, do
>   cd build
>   ../configure
> - This will recreate the gnucash-docs directory structure under build. But

> not
> the files. Instead you will find a Makefile in most directories. From now
on
> you can choose at which level you wish to run commands. Either for all of 
> the
> documentation, or only for the guide or only for one specific language of 
> the
> guide. Just cd into the proper directory. For the options above these
would
> be
> respectively: build, build/guide and build/guide/<lang>.
> - The command to run xmllint is
> make check
> - The command to generate the html documentation is make html
>
> Did you have a particular reason not to use these ? The documentation will
> let you use these anyway in a later step  to "test on linux", so I figure 
> you
> might as well just stick with them for the earlier steps as well. That way
> there's only one set of commands to remember.
>
> Regards,
>
> Geert

Hi Geert,

I've always used the xmllint and xsltproc commands for several reasons.
1) That's what was in the wiki Documentation_Update_Instructions and until
John Ralls mentioned recently that you could use the make commands instead I
had no idea this was possible.
2) I didn't understand enough about what the autogen.sh, configure & make
commands actually did. I did have a look but decided not to spend too much
time on that as I had a workable system (without using a separate build
system). Thanks for you explanations. I learn all the time. 
The instructions for creating a system where you could build gnucash-docs
are spread all over the place, refer mostly building gnucash itself, and use
different directory names (install, build, release, distrelease etc). I
understand that we are free to name some directories whatever we like, but
the lack of consistent guidance makes it hard to know exactly what the
documentation is 
referring to.

BTW, What does autogen.sh do? Does it examine the system to determine if &
where required software is installed and save that information for later use
of configure?

3) I wanted to use an IDE, netbeans being what I am most familiar with. I
wanted to use the netbeans xml editor and integrated git/github support. I
haven't tried to use netbeans to do any of the making. Maybe that is
possible, but the GnuCash make system seems very easy to use.
I found that I could:
 a. Clone  gnucash-docs to ~/github/gnucash-docs
 b. Rename gnucash-docs to gnucash-docs-save (as a netbeans project must be
created in an empty folder)
 c. Create a netbeans project in ~/github/gnucash-docs
 d. copy/move all files and directories ((including hidden folders like
.git) in ~/github/gnucash-docs-save to ~/github/gnucash-docs and I would
have a working netbeans project with working git/github integration in the
repository directory.

4) Using a separate 'build' directory seemed as though it would cause
problems with my system and be more work. Should I edit the files in my
repository or the build directory? I would need to be very careful which
files I edit if I decided to only edit files in the build directories. Will
I need to manually copy files between the build and repository directories?

5) From memory I think the documentation on installing the dependencies
needed to use 'make' etc could use some work. That could discourage
non-technical people from doing documentation, whereas the instructions for
using xmllint and xsltproc are pretty easy to follow IMHO. Those commands
are always in my bash history so I don't have to remember them.

With your information, I can see now that after building the 'build' system,
I can just use netbeans to edit the repository files, run the appropriate
make command in the appropriate build directory in a terminal, then use
netbeans git/github integration when ready. I assume the netbeans project
files will not break the autogen.sh, configure or make commands.
I'll test and update the 'documentation update' documentation.

Did you fix your build problem David?

I'd be interested in hearing what IDE's other people use for GnuCash and/or
GnuCash documentation.

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/20161209/c363125f/attachment.p7s>