gnucash-docs

Chris Lyttle chris@wilddev.net
26 Nov 2002 21:21:13 -0800


On Tue, 2002-11-26 at 20:05, Linas Vepstas wrote:
> Hi Chris,
> 
> On Tue, Nov 26, 2002 at 04:35:56PM -0800, Chris Lyttle was heard to remark:
> > Hi,
> > I have been
> > busy writing a new set of documentation for GnuCash 1.8. As part of this
> > I disabled the old documentation from being made as part of GnuCash and
> > moved the new documents into a separate CVS module called gnucash-docs.
> 
> I just noticed that the docs on the gnucash website, which are normally
> just copies of stuff in the gnucash package, haven't been updated in 
> well, an embarassingly long time.
> 
> So I went to build the docs, and realized that I did not know how,
> I couldn't build the english docs, I couldn't build the portuguese docs.
> How the heck does one build the docs?
> 
> And then it occurs to me: which docs will be in gnucasah-docs?
> The new help files? The old manual? a new manual?  what about 
> the spanish, portuguese, french, german translations (which are 
> of varying quality, and are based on older sources).  What do we do
> with those, until a new translation arrives (e.g. the french translation
> is so old, its not even based on the sgml source?)
> 
> 
> Let me know; I don't want to loose the translations, even if they are
> old; I also want to update what's available on the website, which is old
> 
> As you answer the above questions, can I ask you to write them into
> a README file in the gnucash-docs home dir, explaining the policy, the
> locations, the contents, etc?  So that the next confused dork doesn't 
> suffer the same ingominities?
> 

Well basically the docs in general haven't been updated in an
embarassingly long time. The docs carol wrote for 1.6 never made it into
that release so really all that exists is what you currently have on the
website. When I first started working on this I attempted to just get
what carol had written into good enough shape that they could go in to
1.6 (by that time I think we had gotten up to like 1.6.3 or so). I
realized very quickly that it would need a significant amount of work on
my part. The work involved in just getting the docs that now exist in
doc/manual into xml took me a while with jobs and other stuff I had
going on.
Then we started about july discussing a release before years end. I knew
I'd never complete carol's guide by then but that also the docs that did
exist we a mismash of stuff that was just added in bits and pieces. I
set out to write a completely new coherent help that people using 1.8
could use not for all the background account concepts of GnuCash but
just to answer 'how do I do this task?' which is what most of us use
help for. I was out of work at the end of august so had a lot of free
time to work on this, and now its almost done.
So forward to the 1.7.2 release. I decided then as I would get the new
help done I wanted to disable to old help from the build. This also had
the advantage of reducing the tarball size by 10MB. I basically edited
the makefiles to remove all the sgml docs from the build apart from 2,
guide.sgml and help.sgml which are just placeholder pages.
Now we have a choice moving forward, to cut the translated docs so that
perhaps someone using GnuCash will be encouraged to write new ones or
translate my new help to their language or to include the old docs in
the hope that someone will see the english docs are better and proceed
to translate. Either way its going to be a lot of work for whoever does
the translation. I lean towards just removing them to encourage someone
to come forward and work on the translation. This is because I know the
docs can still be gotten out of the CVS if someone wanted to have a
translation and with a few quick makefile edits they'd have them in
their source again. Having said that, I dont have an objection if people
prefer to keep old crappy translations around in the hope someone will
notice and do something. I know none of the translations will happen
before 1.8. One last thing, as 1.8 is a _new_ release, I dont see the
problem in not having translations available at first. People can still
get translations from a 1.6 installation and copy them to the right
place.

Chris

PS I'd intended to write a readme to do just what you asked sometime
soon :)
-- 
RedHat Certified Engineer #807302549405490.
--------------------------------------------
	|^|
	| |   |^|
	| |^| | |  Life out here is raw 
	| | |^| |  But we will never stop
	| |_|_| |  We will never quit 
	| / __> |  cause we are Metallica
	|/ /    |
	\       /
	 |     |
--------------------------------------------