Please remove my name as documentation support

[Thomas Bullock]

Hello Developers,

Seven or more years ago I was active in some manner in support of
documentation.  I have been retired for a year now and do not have the time
or resources to devote to documentation support.

Please remove my name and email from all places where I am listed as a
developer and/or documentation support.  If I have to do this myself,
please send me the web page where I can make this happen.

Thank you.

Tom Bullock
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Terminology Clarification requested

[Thomas Bullock]

Hi John,

Thanks for your additional reply and further clarification.  The XML is 
interesting to see.  It clearly adds depth to the programmer's task that the 
accountant takes for granted and does not think about it.

Your terms like 'container' and 'structure' provide additional insight.  And 
Derek's 'object' language provides additional perspective.

Thanks to you both for providing the clarification I was asking for.

Tom

> -Original Message-
> From: John Ralls [mailto:jra...@ceridwen.us]
> Sent: Friday, December 10, 2010 12:13 PM
> To: Thomas Bullock
> Cc: gnucash-devel@gnucash.org
> Subject: Re: Terminology Clarification requested
> 
> 
> On Dec 10, 2010, at 4:34 AM, Thomas Bullock wrote:
> 
> >> -Original Message-
> >> From: John Ralls [mailto:jra...@ceridwen.fremont.ca.us]
> >> Sent: Thursday, December 09, 2010 4:37 PM
> >>
> >> So we have a data structure called a "transaction" that includes a
> >> variable number (but at least 2) of subordinate data structures
> called
> >> "split", along with some date fields, and some "key-value" or KVP
> >> data.
> >
> > I infer then that it does not matter which element of the
> transaction gets labeled 'transaction' with all the parts that it has
> in the code.  You are saying that whichever piece of the 'transaction'
> (as an accountant understands it) becomes the 'transaction' (as a
> programmer understands it) it is treated as the prime element of the
> activity being recorded.  It is prime because it has different coding
> treatment compared to the subordinate parts which have a programming
> status/treatment that identifies them as subordinate.
> 
> A gnucash "transaction" structure is a container for the 2 or more
> splits that make up the accounting transaction, not a special split.
> It has some fields that apply to all of the splits, like the
> description, the date the (accounting) transaction occurred, and the
> date it was posted into Gnucash. In XML it looks like:
> 
> 
>   503db7a77e6b2e228708ace1e45a2748
>   
> ISO4217
> USD
>   
>   
> 2002-03-14 16:00:00 -0800
>   
>   
> 2003-01-04 05:13:42 -0800
>   
>   Received from American Founders
> Life
>   
> 
>type="guid">a81924b4c323bdf92626218cf987b68c
>   y
>   
> 2002-09-29 00:11:00 -0700
>   
>   614311/100
>   614311/100
>type="guid">73cbee4da2acb9183e83ff639d615ffe
> 
> 
>type="guid">49ab4796dc37c852923cf118c6b457ac
>   n
>   -614311/100
>   -614311/100
>type="guid">17b67fb50b4b228f9c2442a6debc271f
> 
>   
> 
> 
> Regards,
> John Ralls

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Terminology Clarification requested

[Thomas Bullock]

Derek,

Thanks for your comments.  Sorry to be delayed in replying.  See my comments 
inserted  below.

Tom 

> -Original Message-
> From: Derek Atkins [mailto:warl...@mit.edu]
> Sent: Friday, December 10, 2010 9:11 AM
> To: Thomas Bullock
> Cc: John Ralls; gnucash-devel@gnucash.org
> Subject: Re: Terminology Clarification requested
> 
> Thomas Bullock  writes:
> 
> >> > My formation long ago as a young accountant contained this
> >> understanding of a transaction: it was the accounting expression of
> an
> >> activity that happened in the physical world, which the accounting
> >> ledgers were tracking in their own notation.  For example, suppose
> the
> >> activity is buying a car using cash and debt on 11/10/2010.  The
> >> accounting transaction is that act of purchase.  The accounting
> >> notation was the language of debits and credits with accompanying
> >> names describing the purpose of the monetary "buckets" or value
> >> holders.
> 
> Yes, and GnuCash (and indeed any other financial program) should model
> real-world transactions.
> 
> >> > Thus, in a journal, the transaction would be recorded similarly
> to
> >> this:
> >> >  Debit
> >> Credit
> >> >  11/10/2010  New car 15,000
> >> >  11/10/2010  New car loan
> >>10,000
> >> >  11/10/2010  Cash in bank
> >> 5,000
> 
> This example is not only contrived, but you're confusing yourself.
> You're writing this as three transactions, where really it's a single
> transaction with multiple Splits.  

We are saying the same thing.  My intent was to indicate what I thought to be a 
transaction from an accountant's point of view (not that of the mechanics 
needed to make a multi-part/account transaction be recorded inside GC).
Comparing what I wrote above an what you listed below,  both are the same from 
a conceptual standpoint, but different within GC, because it can have only one 
date physically listed and the split parts of the transaction by association 
and inclusion in the transaction carry that date.  My using 3 dates was not 
expressing the idea from the perspective of how GC does do its work.  Sorry 
that misled you in understanding what I was saying.

So more accuratately:
> 
>11/10/2010New Car
>  Asset15,000
>  Loan 10,000
>  Cash  5,000
> 
> If you really want to know how GnuCash encodes this, simplisitically
> the
> first line is the "Transaction" object, and the three lines below that
> are the "Split" objects.

So your answer is telling me that the identification of the transaction object 
is strictly a function of which part of the multi-part real-world transaction 
is entered first by the GC user.  By default the other parts are identified 
within GC as splits.

> 
> >> So we have a data structure called a "transaction" that includes a
> >> variable number (but at least 2) of subordinate data structures
> called
> >> "split", along with some date fields, and some "key-value" or KVP
> >> data.
> >
> > I infer then that it does not matter which element of the
> transaction
> > gets labeled 'transaction' with all the parts that it has in the
> code.
> > You are saying that whichever piece of the 'transaction' (as an
> > accountant understands it) becomes the 'transaction' (as a
> programmer
> > understands it) it is treated as the prime element of the activity
> > being recorded.  It is prime because it has different coding
> treatment
> > compared to the subordinate parts which have a programming
> > status/treatment that identifies them as subordinate.
> 
> The transaction, as the accountant understands it, is a combination of
> a
> Transaction object and its associated Split objects.  A balanced
> transaction has at least two Splits.  A basic balanced transaction has
> exactly two Splits (one debit, one credit, of the same value).

We agree.  It is good to have the language you provide to understand the GC 
perspective.

> 
> > If this description is basically correct, then is there anything
> that
> > GC coding uses to identify the 'prime element' and by default
> relegate
> > the remaining elements to subordinate status as 'split' elements for
> > split programming treatment?  What makes one element standout that
> it

RE: Terminology Clarification requested

[Thomas Bullock]

Hi John,

Thanks for your comments.  Data structure is a good term, because it allows you 
to focus from a programming standpoint on just parts of what I have described 
as a transaction.

Please see below.

> -Original Message-
> From: John Ralls [mailto:jra...@ceridwen.fremont.ca.us]
> Sent: Thursday, December 09, 2010 4:37 PM
> To: Thomas Bullock
> Cc: gnucash-devel@gnucash.org
> Subject: Re: Terminology Clarification requested
> 
> 
> On Dec 9, 2010, at 1:10 PM, Thomas Bullock wrote:
> 
> > Hi,
> >
> > Using this excerpt as a context:
> >
> > Message: 1
> > Date: Tue, 7 Dec 2010 09:33:58 -0800
> > From: John Ralls 
> > Subject: Re: close books
> > To: Derek Atkins 
> > Cc: devel gnucash 
> > Message-ID: <2b1f2747-854c-430c-8aaa-05637e30a...@ceridwen.us>
> > Content-Type: text/plain; charset=us-ascii
> >
> >
> > [...]
> >
> > A KVP *is* better, but because it's better architecture: The
> closing-entry mark would apply only to one transaction per year, would
> only be important to one split in that transaction (the income/expense
> split; one wouldn't want to hide the split from equity reports), and
> wouldn't have any applicability to any transactions which don't touch
> income or expense accounts. Something of such limited scope doesn't
> deserve a column.
> >
> > Note that the KVP should be on the split, not the transaction,
> because many income/expense reports don't need to look at the whole
> transaction, they just need to total up the credits and debits shown
> in the splits occurring between two dates.
> >
> > Regards,
> > John Ralls
> >
> >
> >
> > Let me ask your help as I work my way to a new understanding of the
> term "transaction".
> >
> > My formation long ago as a young accountant contained this
> understanding of a transaction: it was the accounting expression of an
> activity that happened in the physical world, which the accounting
> ledgers were tracking in their own notation.  For example, suppose the
> activity is buying a car using cash and debt on 11/10/2010.  The
> accounting transaction is that act of purchase.  The accounting
> notation was the language of debits and credits with accompanying
> names describing the purpose of the monetary "buckets" or value
> holders.
> >
> > Thus, in a journal, the transaction would be recorded similarly to
> this:
> > Debit
> Credit
> > 11/10/2010  New car 15,000
> > 11/10/2010  New car loan
>   10,000
> > 11/10/2010  Cash in bank
> 5,000
> >
> > Above John says "...the KVP should be on the split, not the
> transaction,..." but in a later follow-up
> > Derek says that the KVP should be on the transaction and not on the
> split, noting further that the date is resident in the transaction and
> not the split.
> >
> > Which of the above in GC terminology is the "transaction" and which
> the "split"?  What makes one of the parts of the above the
> "transaction" and the others the splits?  Can any one of the 3 parts
> be named the transaction be different people?  What keeps the
> transaction from being arbitrarily identified?
> >
> > In my mind all three parts are splits and there is no transaction
> unless all three are there with debits and credits in balance. If one
> or two parts are missing, the transaction is said to be incomplete or
> broken, because it would not balance.
> >
> > Clearly, GC has a different sense of naming these elements and it is
> important to include in basic documentation a clear discussion of the
> terminology as used in the GC world and as used in the Accounting
> world.  I am not interested particularly in changing GC usage.  I am
> interested in understanding clearly how developers see things and why
> things are perceived that way.  Once I see that perspective, then the
> documentation as presently written will become clearer, at least to
> this accountant, and I expect others in the Users' List.
> >
> > Thanks to all who can help me with this.
> >
> 
> Tom,
> 
> Sorry, Derek and I were in programmer mode in that exchange, not
> accountant mode. 

That makes sense.  My interest is understanding clearly the concepts used in 
programmer mode because a good portion of the documentation reflects that 
perspective in its use of terminology that accountants are used to using in a 
different manner.

We were talking about two data structures in the

Terminology Clarification requested

[Thomas Bullock]

Hi,

Using this excerpt as a context:

Message: 1
Date: Tue, 7 Dec 2010 09:33:58 -0800
From: John Ralls 
Subject: Re: close books
To: Derek Atkins 
Cc: devel gnucash 
Message-ID: <2b1f2747-854c-430c-8aaa-05637e30a...@ceridwen.us>
Content-Type: text/plain; charset=us-ascii


 [...]

A KVP *is* better, but because it's better architecture: The closing-entry mark 
would apply only to one transaction per year, would only be important to one 
split in that transaction (the income/expense split; one wouldn't want to hide 
the split from equity reports), and wouldn't have any applicability to any 
transactions which don't touch income or expense accounts. Something of such 
limited scope doesn't deserve a column.

Note that the KVP should be on the split, not the transaction, because many 
income/expense reports don't need to look at the whole transaction, they just 
need to total up the credits and debits shown in the splits occurring between 
two dates.

Regards,
John Ralls



Let me ask your help as I work my way to a new understanding of the term 
"transaction".

My formation long ago as a young accountant contained this understanding of a 
transaction: it was the accounting expression of an activity that happened in 
the physical world, which the accounting ledgers were tracking in their own 
notation.  For example, suppose the activity is buying a car using cash and 
debt on 11/10/2010.  The accounting transaction is that act of purchase.  The 
accounting notation was the language of debits and credits with accompanying 
names describing the purpose of the monetary "buckets" or value holders.

Thus, in a journal, the transaction would be recorded similarly to this:
Debit   
  Credit
11/10/2010  New car 15,000
11/10/2010  New car loan
10,000
11/10/2010  Cash in bank
 5,000

Above John says "...the KVP should be on the split, not the transaction,..." 
but in a later follow-up
Derek says that the KVP should be on the transaction and not on the split, 
noting further that the date is resident in the transaction and not the split.

Which of the above in GC terminology is the "transaction" and which the 
"split"?  What makes one of the parts of the above the "transaction" and the 
others the splits?  Can any one of the 3 parts be named the transaction be 
different people?  What keeps the transaction from being arbitrarily identified?

In my mind all three parts are splits and there is no transaction unless all 
three are there with debits and credits in balance. If one or two parts are 
missing, the transaction is said to be incomplete or broken, because it would 
not balance.

Clearly, GC has a different sense of naming these elements and it is important 
to include in basic documentation a clear discussion of the terminology as used 
in the GC world and as used in the Accounting world.  I am not interested 
particularly in changing GC usage.  I am interested in understanding clearly 
how developers see things and why things are perceived that way.  Once I see 
that perspective, then the documentation as presently written will become 
clearer, at least to this accountant, and I expect others in the Users' List.

Thanks to all who can help me with this.

Tom 


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Is this bug list possible

[Thomas Bullock]

Geert,

Thanks.  It worked just as you described.  I now have a "Bugs I Follow" report.

My trouble was that I was entering cc:tbull...@nd.edu.  I misread your original 
email thinking I was supposed to include 'cc:'.

Thanks for persisting in helping me here.

Tom

> -Original Message-
> From: Geert Janssens [mailto:janssens-ge...@telenet.be]
> Sent: Friday, October 29, 2010 5:29 AM
> To: Thomas Bullock
> Cc: gnucash-devel@gnucash.org
> Subject: Re: Is this bug list possible
> 
> On Thursday 28 October 2010, Thomas Bullock wrote:
> > Hi Geert,
> >
> > > Yes, you can do so with a little bugzilla foo.
> > >
> > > To start: type cc: into the search field,
> for
> > > example
> > > cc:peter@paradise-isle.org
> > > (This is by the way a shortcut for going to seach, choose advanced
> > > search,
> > > checking "a CC list member" under "Email addresses and Bug
> numbers"
> > > and enter
> > > your e-mail address in the field just below that checkbox.)
> >
> > Well, I found the advanced search and did as you suggest above.  It
> gave me
> >  this reply: 'Zarro Boogs found', which I know is not true, since I
> am
> >  listed on 26 bugs currently.
> >
> > There must be some required parameters I am not using.  Any further
> >  thoughts?
> Tom,
> 
> What exactly did you enter in the cc field ? I tried to enter
> "tbull...@nd.edu" and I get 26 bugs in return.
> 
> Be sure that "a CC list member" is checked (i.e. has a check-mark)
> above the
> text field you used to enter your e-mail address. For some odd reason
> bugzilla
> has two columns here to enter an e-mail address. You can use either,
> but the
> CC list member box above the field you use is relevant to the query.
> 
> For clarity, I haven't touched anything else so all the other fields
> are empty
> and the list boxes have their defaults selected or nothing selected at
> all.
> 
> Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Is this bug list possible

[Thomas Bullock]

Hi Geert,

> Yes, you can do so with a little bugzilla foo.
> 
> To start: type cc: into the search field, for
> example
> cc:peter@paradise-isle.org
> (This is by the way a shortcut for going to seach, choose advanced
> search,
> checking "a CC list member" under "Email addresses and Bug numbers"
> and enter
> your e-mail address in the field just below that checkbox.)

Well, I found the advanced search and did as you suggest above.  It gave me 
this reply: 
'Zarro Boogs found', which I know is not true, since I am listed on 26 bugs 
currently.

There must be some required parameters I am not using.  Any further thoughts?

> 
> Geert

Thanks.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: [Bug 628745] guide: What's New section is outdated

[Thomas Bullock]

Hi Yawar, Christian, and others,

Responding to the issues raised below:

> -Original Message-
> From: Yawar Amin [mailto:yawar.a...@gmail.com]
> Sent: Monday, October 25, 2010 9:57 PM
> To: Christian Stimming
> Cc: gnucash-devel gnucash; Thomas Bullock
> Subject: Re: [Bug 628745] guide: What's New section is outdated
> 
 
> 
> OK-thanks! This will definitely make it easier for me to track and
> resolve the documentation bugs.

Sounds good to me too.  I have placed myself on all the documentation bugs 
(current list of 25 as of this writing).  Currently, I don't regard myself as 
sufficiently knowledgeable to take an existing bug and run with it.  However, 
by learning about the issues in the bug write-up I gradually get more in tune 
with issues - current or old.

> 
> > in case you would like to add more developers, feel free to insert
> their usernames into "Default QA" or "Default CC List". (Tom isn't
> noted as gnucash developer in gnucash so far, but I can add this if
> asked for.)
> 
> 
> I think Tom is working on getting comfortable with the patch
> creation/submission/review process, and version control. 

Correct.  Having had my first patch processed, I realize there is still much to 
assimilate, but it is happening.


We should ask
> him about joining the team when he feels comfortable. But in the
> meantime:
> 
> Tom, should I add you to the default CC list for documentation bugs,
> meaning you would always get an email whenever someone opened a new
> documentation bug, or made changes to existing ones?

Having added myself already, I have received all changes being made.  E.G. bug 
628745.  I see that once it is marked resolved/fixed it is removed from the 
list of open bugs.  As long as new ones get added there, then the list will 
keep me current with what is happening.

I feel that I would like to be added to the list of developers as a junior 
member.  Since all that I prepare is subject to the review of experienced 
developers and I also have no commit ability, the integrity of trunk and 
branch(es) should be protected from accidentally introducing errors.
Do you all agree?
 
Also, FYI, I am working on ch_basics.xml now that Cristian Marchi has 
relinquished it.  I find it contains statements that need to be rephrased, 
existing treatments expanded, and also some concepts should be added to the 
introduction of the user to basic accounting ideas.  I think they need to be 
added in this section. Later on, if found elsewhere in other chapters, they can 
be removed there and the reader referred to the treatment in this section.  
Doing this provides one place for the user to go to in order to get information 
about basic accounting concepts.  This seems to be consistent with Cristian 
Marchi's idea of removing unnecessary duplications, whether in the same or 
different manuals.

> 
> Regards,
> 
> Yawar

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Is this bug list possible

[Thomas Bullock]

Hi Geert,

> Yes, you can do so with a little bugzilla foo.
> 
> To start: type cc: into the search field, for
> example
> cc:peter@paradise-isle.org
> (This is by the way a shortcut for going to seach, choose advanced
> search,
> checking "a CC list member" under "Email addresses and Bug numbers"
> and enter
> your e-mail address in the field just below that checkbox.)

My Bugzilla account is my userid, not an email address.  I enter that into the 
search field , press Search, and get a page that says Search 
Results.  It says No Page Text matches.  On that page there is a list of check 
boxes with the default being Main.  These are options to search in Name spaces. 
 There is no names space option of selecting a "CC list member", and there is 
no option of "Email addresses and Bug numbers".  Somehow I got to a wrong page.

I get the same results when I use my email address .

Below the name space option check boxes there is a search box to enter 
parameters and also an Advanced Search button to push.  The search box is 
prefilled with the original search argument and pushing the Advanced Search 
button returns to the same page with the same "no page text matches" message.

When I first login, the page presented is this one:  
http://wiki.gnucash.org/wiki/Bugzilla.  It is on this page that I enter the 
search argument.  Is this where I should be?

TIA

Tom

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Is this bug list possible

[Thomas Bullock]

Fantastic!  Thanks so much.   Tom

From: Geert Janssens [janssens-ge...@telenet.be]
Sent: Thursday, October 21, 2010 5:00 PM
To: Thomas Bullock
Cc: gnucash-devel@gnucash.org
Subject: Re: Is this bug list possible

On Thursday 21 October 2010, Thomas Bullock wrote:
> Geert,
>
> I noted in Bugzilla that there is a "MyBugs" tag.  When pressed it lists
>  only those I have authored.
>
> Will it be possible to list all those bugs on which I have placed myself as
>  one to be copied for any change?
>
> Thanks.
>
> Tom
>
Yes, you can do so with a little bugzilla foo.

To start: type cc: into the search field, for example
cc:peter@paradise-isle.org
(This is by the way a shortcut for going to seach, choose advanced search,
checking "a CC list member" under "Email addresses and Bug numbers" and enter
your e-mail address in the field just below that checkbox.)

This will list all the bugs you have chosen to receive updates on.
Then with the list on your screen, you can give the search a name (at the
bottom right of the list), like "Bugs I follow" and click on the "Remember
search" button.
This predefined search will now appear next to "My Bugs". You can click on it
at any time to get a list. Note that this is a dynamic list. If you add
yourself to new bugs or remove yourself from bugs, the list will be updated
accordingly.

Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Is this bug list possible

[Thomas Bullock]

Geert,

I noted in Bugzilla that there is a "MyBugs" tag.  When pressed it lists only 
those I have authored.

Will it be possible to list all those bugs on which I have placed myself as one 
to be copied for any change?

Thanks.

Tom

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Bug 632594 created; review, approval, commit requested

[Thomas Bullock]

Thanks, for the words of support.  It is flattering for you to overstate the 
case about my documentation abilities.  I know otherwise only too well -- 
witness the most recent effort!

Tom

> -Original Message-
> From: Yawar Amin [mailto:yawar.a...@gmail.com]
> Sent: Wednesday, October 20, 2010 2:55 PM
> To: Thomas Bullock
> Cc: Geert Janssens; gnucash-devel@gnucash.org
> Subject: Re: Bug 632594 created; review, approval, commit requested
> 
> Hi Tom,
> 
> On 2010-10-20, at 13:39, Thomas Bullock wrote:
> 
> > [...]
> > When I ran the first svn diff I found many changes needed to
> gnucash-guide.xml.  Cristian Marchi's reply let me find the way to
> correct those.  I ran another xmllint and found still 2 more xml
> errors.  I fixed those and thought they would be in the next diff
> output.  Part of what confused me is that my changes.patch (the one
> attached to the bug) had to have been changed by both Cristian's svn
> updates and my own.
> 
> This is a really tricky svn behaviour if you weren't actively
> expecting it, I never would have thought of it myself. Lesson learned
> for all of us! :-)
> 
> >  In the last instance the ch_basics.xml file now has changes to fix
> line breaks, which is different than the original content of that
> file.   That probably happened either to Yawar or Cristian doing svn
> updates.
> 
> Not sure how the line breaks got into the patch ... anyway, we can set
> the re-wrapping and reformatting commits to a future effort to keep
> all the cosmetic changes together.
> 
> > [...]
> >
> >> The overview will always show continuous numbering even if you
> delete
> >> a chapter. The chapter numbering is dynamic. At best you could see
> >> the last number has gone missing.
> >
> > I did not know that either.  It sounds strange.  I expect if chapter
> 14 is missing, its number would  be skipped.
> > Elsewhere in the documentation you have to refer to each specific
> chapter if you want it mentioned.
> 
> Think about it-we don't have to worry about the chapter numbering-we
> just refer to chapters by their IDs ( linkend="chapter_oth_assets"/>-meaning 'put in a reference here to the
> Other Assets chapter') and let the software worry about the numbering.
> 
> >> You could check in your original xml file if you have still
> linkends
> >> for both chapter_bus_pay and chapter_budgets. The patch suggests
> you
> >> don't.
> >
> >
> > You are exactly right -- chapter_bus_pay was missing there!  This is
> really sneaky, at least for the uninitiated.  Well, I have  been
> burned.  Thanks for explaining how it happened.  I see why you or John
> early on suggested running many small patches rather than few large
> ones.  It is very easy to get tripped up.
> 
> Well, editing mistakes can happen from time to time too. I've made
> plenty of patches where I keep noticing errors and correcting them,
> one after the other.
> 
> > Thank you for the careful review of my issues.  I will try to be
> more careful as I go forward.
> 
> Hang in there, I'd say you're almost a GnuCash docs veteran by now :-)
> 
> Best,
> 
> Yawar

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Bug 632594 created; review, approval, commit requested

[Thomas Bullock]

Hi Cristian,

Thanks for your release of the ch_basics.xml module.  I hope to get to it soon.

Tom

> -Original Message-
> From: Cristian Marchi [mailto:cr...@libero.it]
> Sent: Wednesday, October 20, 2010 2:50 PM
> To: Thomas Bullock
> Subject: Re: Bug 632594 created; review, approval, commit requested
> 
> Don't worry, I can't see any mistake! and thanks for the contribute
> you
> are offering to the project.
> 
> I've finished editing the ch_basics.xml file so now you could make
> changes on it and, if you want,  look for errors.
> 
> Thanks
> Cristian
> 
> 
> Il 20/10/2010 20:36, Thomas Bullock ha scritto:
> > Thanks, Cristian, for your update.  I learned something from the
> mistake I made.  I hope to avoid it in the future.
> >
> > Tom
> >
> >
> >> -Original Message-----
> >> From: Cristian Marchi [mailto:cr...@libero.it]
> >> Sent: Wednesday, October 20, 2010 2:31 PM
> >> To: Thomas Bullock
> >> Cc: Geert Janssens; Yawar Amin; gnucash-devel@gnucash.org
> >> Subject: Re: Bug 632594 created; review, approval, commit requested
> >>
> >> I've commited yesterday some patch to guide:
> >> - updated ch_basics.xml file
> >> - corrected the markup language in gnucash-guide.xml
> >> - new and updated images for GnuCash Preferences in guide
> >>
> >> Il 20/10/2010 19:39, Thomas Bullock ha scritto:
> >>
> >>> Hi Geert and Yawar,
> >>>
> >>>
> >>>
> >>>> On the other hand, your patch as seen in bugzilla doesn't contain
> >>>> modifications to gnucash-guide.xml, so I wonder how you
> interpreted
> >>>> Yarar's
> >>>> reply as if you are not allowed to change that file.
> >>>>
> >>>>
> >>> Looking back on your discussion in this email and my current
> version
> >>>
> >> of changes.patch, I can conclude only that I seem to have lost my
> way.
> >>
> >>> When I ran the first svn diff I found many changes needed to
> >>>
> >> gnucash-guide.xml.  Cristian Marchi's reply let me find the way to
> >> correct those.  I ran another xmllint and found still 2 more xml
> >> errors.  I fixed those and thought they would be in the next diff
> >> output.  Part of what confused me is that my changes.patch (the one
> >> attached to the bug) had to have been changed by both Cristian's
> svn
> >> updates and my own.  In the last instance the ch_basics.xml file
> now
> >> has changes to fix line breaks, which is different than the
> original
> >> content of that file.   That probably happened either to Yawar or
> >> Cristian doing svn updates.  I say that the release number had
> changed
> >> but I did not appreciate the significance of that.  I believe that
> was
> >> a big yellow light for me to stop and examine what had changed from
> my
> >> expectations.  So I learned something from this exercise.
> >>
> >>>
> >> Sorry Thomas for creating confusion on this. I've corrected the
> >> problems
> >> in gnucash-guide.xml minutes after you sent the mail about them. So
> >> when
> >> you have "svn update" your local copy the changes were merged and
> your
> >> diff didn't listed the changes on the file.
> >>
> >> At this link you can see the last changes I've made to the file:
> >> http://svn.gnucash.org/trac/changeset/19678/gnucash-
> >> docs/trunk/guide/C/gnucash-guide.xml
> >>
> >>
> >>>
> >>>> I can only assume this is what happened:
> >>>> 1. you had fixed a number of xmllint errors in your local working
> >>>> copy.
> >>>> 2. at about the same time, Cristian committed his work in r19679,
> >>>> which among
> >>>> others also fixes the same xmllint errors.
> >>>> 3. you dutifully ran svn update before creating your final patch.
> >>>>
> >> This
> >>
> >>>> svn
> >>>> update pulled in the final xmllint fixes that Cristian had just
> >>>> committed.
> >>>> Since your local fixes were the same as in the online svn repo,
> svn
> >>>> update
> >>>> marked these local changes as in sync with the online repo. In
> >>>>
> >> other
> >>
> >>>> words,
> >>>> your local fixes wouldn't appear in the subsequent svn diff,
> >>>>
> >> because
> >>
> >>>> they were
> >>>> already in the online repository.
> >>>> 4. You ran svn diff to create the patch, still assuming there
> would
> >>>>
> >> be
> >>
> >>>> xmllint
> >>>> fixes in it.
> >>>>
> >>>>
> >>> I believe your analysis is correct.
> >>>
> >>>
> >> That's what happened!
> >>
> >>
> >> Regards
> >> Cristian
> >>
> > .
> >
> >
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Bug 632594 created; review, approval, commit requested

[Thomas Bullock]

Hi Geert and Yawar,

> 
> On the other hand, your patch as seen in bugzilla doesn't contain
> modifications to gnucash-guide.xml, so I wonder how you interpreted
> Yarar's
> reply as if you are not allowed to change that file.

Looking back on your discussion in this email and my current version of 
changes.patch, I can conclude only that I seem to have lost my way.

When I ran the first svn diff I found many changes needed to gnucash-guide.xml. 
 Cristian Marchi's reply let me find the way to correct those.  I ran another 
xmllint and found still 2 more xml errors.  I fixed those and thought they 
would be in the next diff output.  Part of what confused me is that my 
changes.patch (the one attached to the bug) had to have been changed by both 
Cristian's svn updates and my own.  In the last instance the ch_basics.xml file 
now has changes to fix line breaks, which is different than the original 
content of that file.   That probably happened either to Yawar or Cristian 
doing svn updates.  I say that the release number had changed but I did not 
appreciate the significance of that.  I believe that was a big yellow light for 
me to stop and examine what had changed from my expectations.  So I learned 
something from this exercise. 

> I can only assume this is what happened:
> 1. you had fixed a number of xmllint errors in your local working
> copy.
> 2. at about the same time, Cristian committed his work in r19679,
> which among
> others also fixes the same xmllint errors.
> 3. you dutifully ran svn update before creating your final patch. This
> svn
> update pulled in the final xmllint fixes that Cristian had just
> committed.
> Since your local fixes were the same as in the online svn repo, svn
> update
> marked these local changes as in sync with the online repo. In other
> words,
> your local fixes wouldn't appear in the subsequent svn diff, because
> they were
> already in the online repository.
> 4. You ran svn diff to create the patch, still assuming there would be
> xmllint
> fixes in it.

I believe your analysis is correct.

> The overview will always show continuous numbering even if you delete
> a
> chapter. The chapter numbering is dynamic. At best you could see the
> last
> number has gone missing.


I did not know that either.  It sounds strange.  I expect if chapter 14 is 
missing, its number would  be skipped.  Elsewhere in the documentation you have 
to refer to each specific chapter if you want it mentioned.


> You could check in your original xml file if you have still linkends
> for both
> chapter_bus_pay and chapter_budgets. The patch suggests you don't.


You are exactly right -- chapter_bus_pay was missing there!  This is really 
sneaky, at least for the uninitiated.  Well, I have  been burned.  Thanks for 
explaining how it happened.  I see why you or John early on suggested running 
many small patches rather than few large ones.  It is very easy to get tripped 
up.


> 
> By the way, if you run svn status, do any of your files have a "C"
> state ?
> Those should always be fixed before making a patch. Read up on
> conflict
> resolution in the subversion book if you need help with that [1].
> 
> Geert
> 
> [1] http://svnbook.red-
> bean.com/en/1.5/svn.tour.cycle.html#svn.tour.cycle.resolve


No,  mine are "?" or "M"

Thank you for the careful review of my issues.  I will try to be more careful 
as I go forward.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Bug 631789 update

[Thomas Bullock]

Thanks.  I have signed up for all the 26 items listed.  A lot seem to be 
connected with scheduled transactions.  I will look to see if it make sense to 
combine as many as possible into one.

Very useful listing.

Tom

> -Original Message-
> From: Geert Janssens [mailto:janssens-ge...@telenet.be]
> Sent: Wednesday, October 20, 2010 10:30 AM
> To: Thomas Bullock
> Cc: gnucash-devel@gnucash.org
> Subject: Re: Bug 631789 update
> 
> On Wednesday 20 October 2010, Thomas Bullock wrote:
> > Geert,
> >
> > Thanks for these remarks.  Since I am interested mainly in
> documentation
> >  and its accuracy, your bringing bugs to the list are useful to me.
> I will
> >  try to follow up on any that are listed, especially those that I
> see as
> >  having a documentation impact.
> >
> > Tom
> 
> Hmm, then this list will probably interest you:
> https://bugzilla.gnome.org/buglist.cgi?product=GnuCash&bug_status=UNCO
> NFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&compone
> nt=Documentation
> 
> It's a list of all currently open bugs for GnuCash Documentation.
> 
> Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Bug 631789 update

[Thomas Bullock]

Geert,

Thanks for these remarks.  Since I am interested mainly in documentation and 
its accuracy, your bringing bugs to the list are useful to me.  I will try to 
follow up on any that are listed, especially those that I see as having a 
documentation impact.

Tom

> -Original Message-
> From: Geert Janssens [mailto:janssens-ge...@telenet.be]
> Sent: Wednesday, October 20, 2010 10:09 AM
> To: Thomas Bullock
> Cc: gnucash-devel@gnucash.org
> Subject: Re: Bug 631789 update
> 
> On Wednesday 20 October 2010, Thomas Bullock wrote:
> > Geert,
> >
> > Thanks for pointing out that my remarks should be part of bug.
> Following
> >  your recommendation, I have added an additional comment to that
> bug.
> >
> Thanks for the comments.
> 
> > How does a  bug update get added automatically to the developer's
> list?  Or
> >  does it?  Do changes to a bug discussion go only to those
> subscribing to
> >  the bug?
> >
> The list is not automatically informed of updates. People interested
> in
> further discussion on this topic should subscribe to the bug. I think
> that is
> ok. If more people on the list had remarks they would have made those
> by now.
> 
> Also by my announcement of the existence of the bug, others still
> interested
> can go over there and subscribe.
> 
> The reason I suggest to follow up on the bug, is that it's better to
> keep
> comments in one place. If there's a bug report that's the preferred
> place as
> it's easier to manage feature requests from there.
> 
> Sometimes I come across a bug report that needs more input than it is
> getting.
> I such cases I sometimes announce the existence of that bug on the
> devel list
> and ask for more input. Usually some of the other devs and list
> followers will
> then add there comments to the bug in bugzilla.
> 
> That's roughly how these two communication channels interact for me.
> 
> Geert
> 
> > Tom
> >
> > > -Original Message-
> > > From: Geert Janssens [mailto:janssens-ge...@telenet.be]
> > > Sent: Wednesday, October 20, 2010 7:16 AM
> > > To: gnucash-devel@gnucash.org; Thomas Bullock
> > > Subject: Re: Summary bar description (was: Patch for guide file
> > > "ch_basics.xml")
> > >
> > > On Saturday 16 October 2010, Tom Bullock wrote:
> > > >   Geert and Juergen,
> > > >
> > > > Earlier exchanges stated:
> > > > > >  "Assets" is the sum of all accounts of types Bank, Cash,
> Asset,
> > >
> > > Stock,
> > >
> > > > > > Mutual Fund, Credit Card, Liability, A/Payable and
> A/Receivable,
> > > > > > obviously taking the proper sign into account. Calling this
> > >
> > > "Assets"
> > >
> > > > > > would indeed be confusing at least.
> > > >
> > > > Just netting (offsetting credits [liabilities] against debits
> > >
> > > [assets]
> > >
> > > > from the balance sheet) these together gives "Net Assets", not
> net
> > > > worth.  Net worth is a duration concept, meaning activity over
> time.
> > >
> > > It
> > >
> > > > refers to the use of assets to generate income while incurring
> > >
> > > expenses
> > >
> > > > to do that.  Net Assets is a point-in-time concept and excludes
> any
> > > > income statement activity.
> > > >
> > > > Given what has been said to this point, the most accurate term I
> > >
> > > have
> > >
> > > > seen is "net assets" for the place where a better name is
> needed.
> > >
> > > This very same issue has recently been reported in a bug:
> > > https://bugzilla.gnome.org/show_bug.cgi?id=631789
> > >
> > > I have added references there to this thread.
> > >
> > > I don't speak English accounting language fluently, so I have to
> > > accept
> > > whatever others agree upon here. I would suggest to continue any
> > > further
> > > discussion on this description on the bug report.
> > >
> > > Geert
> >

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Wiki Page Formatting

[Thomas Bullock]

Geert,

Thanks for pointing out the wiki functional guidelines: separation of structure 
and presentation.  

> This is not completely accurate in my opinion. Just like docbook,
> wiki's are
> designed to separate your document structure from your document
> presentation.
> The idea is that the writer focuses on the structure and content and
> doesn't
> have to worry about what it will look like.
> To finally display the document, a stylesheet is applied (again, this
> is both
> for docbook and wikis). It's the stylesheet writer's responsibility to
> make
> sure the pages look good. So even a wiki has the potential to have
> beautiful
> page design and typography.

Does the wiki foundation have guidelines for style sheet creation?  Or is this 
another application of CSS?

> >
> > [1] http://lab.arc90.com/experiments/readability/
> >
> Even if off-topic, I'm glad you sent it along. I didn't know about
> this one.
> 
> Geert

Thanks,

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Wiki Page Formatting

[Thomas Bullock]

Yawar,

Thanks for the great work-around!!  It fixes not only the specific problem but 
is available for every other similar situation.  Well done!

> That said, and this is probably off-topic, but I find the Readability
> bookmarklet[1] invaluable nowadays when browsing most article-style
> web pages, including wikis.
> 
> Regards,
> 
> Yawar
> 
> [1] http://lab.arc90.com/experiments/readability/

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Bug 631789 update

[Thomas Bullock]

Geert,

Thanks for pointing out that my remarks should be part of bug.  Following your 
recommendation, I have added an additional comment to that bug.

How does a  bug update get added automatically to the developer's list?  Or 
does it?  Do changes to a bug discussion go only to those subscribing to the 
bug?

Tom

> -Original Message-
> From: Geert Janssens [mailto:janssens-ge...@telenet.be]
> Sent: Wednesday, October 20, 2010 7:16 AM
> To: gnucash-devel@gnucash.org; Thomas Bullock
> Subject: Re: Summary bar description (was: Patch for guide file
> "ch_basics.xml")
> 
> On Saturday 16 October 2010, Tom Bullock wrote:
> >   Geert and Juergen,
> >
> > Earlier exchanges stated:
> > > >  "Assets" is the sum of all accounts of types Bank, Cash, Asset,
> Stock,
> > > > Mutual Fund, Credit Card, Liability, A/Payable and A/Receivable,
> > > > obviously taking the proper sign into account. Calling this
> "Assets"
> > > > would indeed be confusing at least.
> >
> > Just netting (offsetting credits [liabilities] against debits
> [assets]
> > from the balance sheet) these together gives "Net Assets", not net
> > worth.  Net worth is a duration concept, meaning activity over time.
> It
> > refers to the use of assets to generate income while incurring
> expenses
> > to do that.  Net Assets is a point-in-time concept and excludes any
> > income statement activity.
> >
> > Given what has been said to this point, the most accurate term I
> have
> > seen is "net assets" for the place where a better name is needed.
> >
> This very same issue has recently been reported in a bug:
> https://bugzilla.gnome.org/show_bug.cgi?id=631789
> 
> I have added references there to this thread.
> 
> I don't speak English accounting language fluently, so I have to
> accept
> whatever others agree upon here. I would suggest to continue any
> further
> discussion on this description on the bug report.
> 
> Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Bug 632594 created; review, approval, commit requested

[Thomas Bullock]

Yawar,

I reviewed your links and have these questions.

1.  Are you saying do not modify gnucash-guide.xml at this time?  If so, is 
that because Cristian is working on this module?  If I don't modify it, then I 
just drop it from what my 'svn diff' found?  I thought I had to correct all of 
'xmllint' and 'svn diff''s findings?  Cristian Marchi told me to fix them when 
I found them.  See his email dated 10/19/2010, listed as the #3 in the digest 
vol 91, Issue 26.  I don't know what you mean by mean fixing line breaks.

2.  Regarding removing payroll chapter 14 by accident, please explain why that 
is?  Before committing the patch I transformed the xml files to html and 
examined chapter 1 for the overview. It showed me chapters 11 thru 16 without 
any chapters missing.  I looked at your changesets 19684 and 19686 and both 
seem to me to be saying that I am not deleting chapter 14,  but am inserting 15 
and 16 after it.  In what way am I reading that incorrectly?

Thanks for your help.

Tom   

> -Original Message-
> From: Yawar Amin [mailto:yawar.a...@gmail.com]
> Sent: Tuesday, October 19, 2010 11:06 PM
> To: Thomas Bullock
> Cc: gnucash-devel gnucash
> Subject: Re: Bug 632594 created; review, approval, commit requested
> 
> Hi Tom,
> 
> On 2010-10-19, at 15:52, Thomas Bullock wrote:
> 
> > Developers,
> >
> > This bug carries only very small tweaks to 3 files.  Please advise
> me of any problems; otherwise, I request approval and install to
> trunk.
> 
> Thanks for the patch! The grammar fix and overview chapter additions
> look good, committed.* The other changes look like simple line breaks,
> can we keep that for a future effort? That way, we can re-wrap and
> commit whole files at a time instead of a few lines here and there.
> 
> Trunk commits are at [1] and [2], and 2.2 commits are at [3] and [4].
> 
> I've also updated the Bugzilla page[5] to reflect this.
> 
> Best Regards,
> 
> Yawar
> 
> * It looked like your original patch inadvertently removed the Payroll
> chapter from the listing, so I kept the Payroll chapter and added the
> Budgets and Other Assets chapters as you intended.
> 
> [1] http://svn.gnucash.org/trac/changeset/19685
> [2] http://svn.gnucash.org/trac/changeset/19686
> [3] http://svn.gnucash.org/trac/changeset/19683
> [4] http://svn.gnucash.org/trac/changeset/19684
> [5] https://bugzilla.gnome.org/show_bug.cgi?id=632594

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Bug 632594 created; review, approval, commit requested

[Thomas Bullock]

Developers,

This bug carries only very small tweaks to 3 files.  Please advise me of any 
problems; otherwise, I request approval and install to trunk.

Thanks.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Wiki Page Formatting

[Thomas Bullock]

Hi Geert,

Maybe this message should not be on this list, since it is not strictly GC 
related.  But it is a tool that GC relies on, so tell me your preference.

Here's the question:  I have looked at Mediawiki 
(http://www.mediawiki.org/wiki/Help:Formatting) for help.  In the process I 
found the reference link which is very helpful and shows where you found your 
tips in your previous email.  However, I have not found instruction how to set 
a column boundary thereby forcing line wrapping.  Another way would be to 
activate a multiple column  feature if there is one.

Either of those would permit shorter lines, making it easier to read the page.  
I can read the same information in 2 or 3 columns more easily than if it is in 
the present form.

Any suggestions?

Thanks.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Unexpected XML errors found

[Thomas Bullock]

Cristian,

Thanks for the explanation.  I used your example and now am able to proceed 
without xml errors.

Thanks.

Tom

> -Original Message-
> From: Cristian Marchi [mailto:cr...@libero.it]
> Sent: Tuesday, October 19, 2010 1:37 PM
> To: Thomas Bullock
> Cc: gnucash-devel gnucash
> Subject: Re: Unexpected XML errors found
> 
> Yes I know this problem. It was introduced when I patched all
> documents
> in order to mark the entity &app; with the markup . I've
> already resolved this problem for ch_basics.xml but I have not yet
> checked other files for the same error.
> 
> Just to explain you where the problem reside, this error is due to the
> fact that in some markup is not allowed as child the 
> markup
> 
> For exmple: &app; Documentation
> Team is not allowed
> The right markup is: &app; Documentation Team
> 
> Feel free to correct this errors when you find them
> 
> Regards
> Cristian
> 

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Unexpected XML errors found

[Thomas Bullock]

Developers,

Working on my next patch (a tweak to what I previously installed) I noted that 
a couple of chapter references had been left out of Chapter 1 - Basics.  So I 
thought I would add the reference to both Budgets and Other Assets.

When I ran the 'xmllint' command, I got 18 xml errors: 14 relating to 
gnucash-guide.xml and the remaining 4 relating to ch-basics.xml

All of the 18 errors are essentially worded in this manner:
"Element (name of element):validity error - element application is not 
declared in (name of element) list of possible children."

Where I say (name of element) a different element is named for the spot in the 
file identified by the line number given for the error.

This sounds to me as an xsl or dtd problem.  Would that be correct?

Any suggestions how I can remove these errors?

Thanks.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Removing duplications between Guide & Help

[Thomas Bullock]

Thanks, Cristian.  I will check back with you when I am ready to install a 
patch.  You may have done yours before I am ready.  I will make sure my files 
have integrated any updates that are made after I have checked out my working 
copy.  Will do this to be sure my patch does not step on anyone.

Tom

> -Original Message-
> From: Cristian Marchi [mailto:cr...@libero.it]
> Sent: Monday, October 18, 2010 3:23 PM
> To: Thomas Bullock
> Cc: gnucash-devel gnucash
> Subject: Re: Removing duplications between Guide & Help
> 
> I've completely removed the preferences section (moved to GC help
> manual) and I'm looking into some small modifications. I hope I can
> commit the changes in a couple of day.
> 
> Il 18/10/2010 21:17, Thomas Bullock ha scritto:
> > Cristian,
> >
> > Do I remember correctly that you have started working on removing
> duplications between the two manuals?
> >
> > If so, have you finished with Chapter 2, the Basics?  I have some
> small changes to make there in order to complete a prior install.
> >
> > If not, can you tell me when you expect to install your changes to
> that chapter?
> >
> > Thanks.
> >
> > Tom
> > .
> >
> >
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Removing duplications between Guide & Help

[Thomas Bullock]

Cristian,

Do I remember correctly that you have started working on removing duplications 
between the two manuals?

If so, have you finished with Chapter 2, the Basics?  I have some small changes 
to make there in order to complete a prior install.

If not, can you tell me when you expect to install your changes to that chapter?

Thanks.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: GC Concept Guide Review and Wiki Pages

[Thomas Bullock]

Hi Geert,

> -Original Message-
> From: Geert Janssens [mailto:janssens-ge...@telenet.be]

> Yes, it's more accurate as it is written now. I have only corrected
> the
> explanation to get help on the svn diff command. "man diff" will give
> you the
> manual page for the standard diff command. However "svn help diff"
> will
> explain how that command works. 

Thanks for making that correction.

> As far as I'm concerned it's ready as it is. A wiki is a living thing
> anyway,
> so at any time new information can be added (as Cristian's po
> conversion
> information), or updated as things change.
> 
> So go ahead and send a notice.

Great!  With the back and forth on this list, I think I will send notification 
only to the users, unless you think the developers list should have a 
(redundant) notification.

> 
> Geert

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: GC Concept Guide Review and Wiki Pages

[Thomas Bullock]

Hi Geert,

> For your reference, here's a very short summary of (most of) what I
> did:
> * titles: surround with ==...==
> * subtitles are created by surrounding them with one additional = per
> sublevel, so for example first subtitles will be ===...===
> * numbered lists: replace "1. ", "2. ",... with "#"
> * Add some bulleted lists by prepending the paragraphs with a "*"
> * The # and * additions can be combined to get recursive lists.
> * Note that lists are pretty picky about newlines. I removed most of
> them
> inside list paragraphs, otherwise numbering wouldn't add up.
> * If you want a newline in a list item, begin the new line with the
> same
> combination of # and * as the previous line and add one ":"
> * literal commands: surround with ... (I also removed the
> quotes,
> they don't add value anymore with the ... formatting)
> * if you wish to indent a paragraph: prepend a colon (":") and make
> sure to
> remove all newlines from that paragraph.
> * I removed the -- separators. The wiki sections and
> subsections
> markup is clear enough IMO.
> * Note that the tables of contents is courtesy of Media wiki. I don't
> have to
> write it.

Thank you again for the summary instructions on how to write a wiki page.  I 
finally got time to see what you had done.  I made only a couple of cosmetic 
tweaks and a few words to clarify something I had missed.  Thanks also for 
making the page editable in sections versus the entire page in one pass.  How 
did you make that happen?

Using the above and the new page will be a very practical wiki tutorial for me 
going forward.  I very much appreciate your setting this up.

> 
> So far I have not made any changes to the text itself (apart from some
> spelling fixes), to make it easier for your to see how it got
> translated from
> plain text to wiki text.
> 
> I do have some remarks on what you have written also though:
> Step 9: you don't have to list yourself as wanting to be notified
> explicitly
> when you reported the bug. In that case you will automatically be
> notified.
> 

Thanks for this.  I have modified the text to reflect that result of setting up 
a bug.


> Notes on step 1: the events you describe here in case subversion is
> not
> installed are very distribution dependent. I think right now it only
> happens
> in very recent distro's (I know for Fedora it will only first appear
> in the
> new Fedora 14). Perhaps it's best to refer the reader to his/her
> distro
> specific application installation tools here to install subversion.

I have modified the document to incorporate this point.


> 
> Notes on step 6: your explanation here is a bit misleading. "svn dif"
> doesn't
> contact the online repository. It uses the local working copy's
> metadata
> (which can be found in the hidden directory .svn) to determine what
> has
> changed since the last time you ran svn update. It is the svn update
> command
> that connect to the online repository to retrieve any new changes. So
> if you
> wish to view the changes you made compared to the status of the online
> repository, you should start with an svn update, and then run svn
> diff.

I have integrated these ideas into Notes for step 6.  Please verify I have 
captured your ideas.  Basically, I have rewritten this entire Notes for step 6 
section.  I hope it flows more logically and smoothly.


> 
> In the same section: you mention "diff -ur". As I mentioned in the
> mailing
> list as well, this won't work in subversion. Instead you should use
> "svn
> diff". ("diff -ur" requires additional parameters to run).

I removed the reference to "diff -ur".


> 
> (Forgive me if my writing is a little compact. I should be in bed by
> now...)

Privately, I wondered how you and a couple others do all you do.  You must have 
a small sleep requirement! :-))


> 
> Geert

When you think this is ready for users, I will send a notice to the user's list 
about the wiki page.  Right now, especially since I rewrote the one section, I 
want to be sure I have not lost something and do have all the essential pieces 
in right order.

Thanks again for your help and support.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

What is the 2.5 branch?

[Thomas Bullock]

Hi Herbert,



You said:

Personally, I have been using the 2.5 branch for my real financial data for at 
least half a year now (with XML backend) and never experienced any problems. 

  Herbert.

Please clarify the branch you are referring to.  If the debate is when to 
declare 2.4 the next official release, 2.5 confuses me.

Thanks for your patience with the uninitiated. :-)

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: GC Concept Guide Review and Wiki Pages

[Thomas Bullock]

Hi Geert,

Thank you very much for your offer.  I too would like the information to be 
available as soon as possible for general use by any interested persons.

Your putting it into a wiki would relieve me of a felt (on my side) pressure to 
get this done.  It is a kind and appreciated offer.  I could send you a copy of 
the file if you do not have one available.  Just tell me.

Part of my pressure is to form documentation for 2.4 as well as to enhance it 
where I think it could use it.  To get more efficient in making patches has 
required me learning several new (to me) tools.  Also, I agree with Cristian 
Marchi that there is duplication between the Guide and Help manuals.  It is 
great that he wants to work on sorting that out.

If I am not mistaken there is also duplication among the wiki pages which 
should be rectified by making them more topical with cross-linking to the main 
place treatment of a topic is given.

Finally, I think we could have a feature that we could think of as a "site 
map".  It would be a way for persons to search all aspects of documentation: 
Guide, Help, FAQs.  Key words and aliases pointing to key words constitute what 
I am thinking about.  Each key word is a link to a page.  On that page are 
references to all places where the key word is discussed, explained, used.  
This certainly would need for all documentation catch-up to be completed before 
it was attempted in earnest fashion.  This last idea really is only a dream at 
this point.  Much, Much more needs to be done before that is a realistic 
project.

On a different topic while focused on documentation, I note that there are no 
page numbers to use as references.  That may be explained by using XML and HTML 
versions of the manuals.  Has anyone ever brought up the idea of using numbered 
sections and segments within the chapters' numbering system as a means of 
cross-referencing to related ideas within the manuals?   To some extent this 
seems present, but not as extensively as I think it might.  This idea, if 
adopted, should  be implemented only after the duplication removal gets 
completed.

Just some ideas to ponder.

Tom

> -Original Message-
> From: Geert Janssens [mailto:janssens-ge...@telenet.be]
> Sent: Friday, October 15, 2010 11:06 AM
> To: Thomas Bullock
> Cc: gnucash-devel@gnucash.org; Cristian Marchi
> Subject: Re: GC Concept Guide Review
> 
> On Friday 15 October 2010, Thomas Bullock wrote:
> > Geert,
> >
> > I agree with your thought and fully intended and intend to do what
> you
> >  advise.  The problem is that I have to learn how to write a wiki
> and
> >  incorporate its features into what I write.
> >
> > Right now that is a time sink and I have other tasks that in my mind
> >  precede that in urgency.  Cristian's mails were posted  before I
> could
> >  learn how to write a wiki and put my stuff in that format.  Thus,
> the
> >  state you find us in.
> >
> > Sorry my slow learning curve is impacting helping others.
> >
> Hmm, don't worry. That's not why I wrote my suggestion. I surely
> wouldn't give
> you the impression you are holding me or anybody else back. On the
> contrary,
> your work so far has helped Cristian already and surely inspired
> others to
> have a look at the documentation.
> 
> About the wiki, the syntax in general really isn't that complicated.
> In fact,
> when I edit wiki pages, I usually look at other sections to learn just
> enough
> to make my changes.
> 
> Do you think it would be helpful if I put your text into wiki ? That
> would
> give you an example of wiki markup on your own work. Perhaps that
> makes it
> easier to understand what to do.
> 
> It's probably clear by now I personally prefer to use the wiki for
> this kind
> of collaborative work, but I don't intend to push you. I intention is
> to offer
> a helping hand, but if this is uncomfortable for you, I'm equally
> happy if you
> continue on the text as you are working now.
> 
> Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: GC Concept Guide Review

[Thomas Bullock]

Geert,

I agree with your thought and fully intended and intend to do what you advise.  
The problem is that I have to learn how to write a wiki and incorporate its 
features into what I write.  

Right now that is a time sink and I have other tasks that in my mind precede 
that in urgency.  Cristian's mails were posted  before I could learn how to 
write a wiki and put my stuff in that format.  Thus, the state you find us in.

Sorry my slow learning curve is impacting helping others.

Tom 

> -Original Message-
> From: Geert Janssens [mailto:janssens-ge...@telenet.be]
> Sent: Friday, October 15, 2010 10:12 AM
> To: gnucash-devel@gnucash.org
> Cc: Thomas Bullock; Cristian Marchi
> Subject: Re: GC Concept Guide Review
> 
> On Friday 15 October 2010, Thomas Bullock wrote:
> > Cristian,
> >
> > Yes, do add your findings about the po file.  I have not learned
> about them
> >  yet.  All I have picked up is that they are involved in
> translations from
> >  English to another language.  When done, I would appreciate your
> sending
> >  back to me the entire file including your information.
> >
> You are free to organize your collaborative improvements to this
> document any
> way you see fit, but at this point I'd like to point out that a wiki
> is meant
> exactly to avoid this kind sending up and down.
> 
> I'd propose you put the text up in the wiki as it is now. It doesn't
> have to
> be complete yet. Both of you can then easily make changes to it and
> the other
> immediately sees them. It doesn't even really matter where you put it.
> If you
> find an existing page that is closely related, you can add your text
> there.
> Otherwise, simply create a new page.
> 
> You can still discuss the text via the mailing list if you prefer
> also.
> 
> But as I started out, feel free to work with it as you like.
> 
> Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: GC Concept Guide Review

[Thomas Bullock]

Cristian,

Yes, do add your findings about the po file.  I have not learned about them 
yet.  All I have picked up is that they are involved in translations from 
English to another language.  When done, I would appreciate your sending back 
to me the entire file including your information.

What the file needs is how to process those and when they are relevant to 
documentation update.  Can you describe the circumstances under which it 
occurred?  From you information, I hope to insert it into the right sequence in 
the existing steps.  I need to understand more fully what you mean by stating

"I've also managed to get a po file where I merged the C locale guide to the 
it_IT locale. In this way I'm able to use a po file to track changes between 
the two in an easy way and the translation process is a lot better."

Thanks much for your input.

Tom


From: Cristian Marchi [mailto:cr...@libero.it]
Sent: Friday, October 15, 2010 8:17 AM
To: Thomas Bullock
Cc: gnucash-devel gnucash
Subject: Re: GC Concept Guide Review

Thanks for the file. Really usefull and complete. It is perfect for a wiki 
page. (I will surely follow the bugzilla section because I'm not familiar with 
it)
I've also managed to get a po file where I merged the C locale guide to the 
it_IT locale. In this way I'm able to use a po file to track changes between 
the two in an easy way and the translation process is a lot better. I think I 
could add something on this topic to your text if you want.

Il 13/10/2010 21:12, Thomas Bullock ha scritto:
Here you are, Cristian.  Other than I you will be the first to see these.  
Please send me anything that is not clear or that does not work for you.  If 
you believe I have said something not correct, then please do point that out 
also.

Good luck.

Tom

From: Cristian Marchi [mailto:cr...@libero.it]
Sent: Wednesday, October 13, 2010 3:01 PM
To: Thomas Bullock
Cc: gnucash-devel gnucash
Subject: Re: GC Concept Guide Review



Il 13/10/2010 20:12, Thomas Bullock ha scritto:

Hi Cristian,

I don't believe what I am working on will be affected by your intended changes, 
but I should mention that I have a patch to Guide chapter 3 in process.  That 
patch also adds Chapter 16 and affects a couple other modules.

I believe these have been committed but not installed into subversion, at least 
as of this past Monday.  So please keep that in mind should you not find my 
changes in the svn checkout that brings the full set of docs to your own 
computer.
Ok, I've read your previous posts on this list about the documentation patch.




I am new to GC documentation and there is a multi-step process that I have to 
follow.  I have been asked to write that up, especially for the benefit of 
persons new to GC.   It is intended for a wiki, but I do not have the wiki 
created - just a text file.  If you think that might be of interest, I could 
send a copy of the notes I created for your use until something more public can 
be installed. ;-)

Sure, i'm also pretty new to documentation writing (I?ve only translated the 
GnuCash manual and help in Italian) so any advice on workflow is good.


Thanks
Cristian


HTH,

Tom Bullock






Date: Wed, 13 Oct 2010 15:27:41 +0200

From: Geert Janssens 
mailto:janssens-ge...@telenet.be>>

Subject: Re: Concept guide review

To: gnucash-devel@gnucash.org<mailto:gnucash-devel@gnucash.org>

Message-ID: 
<201010131527.41506.janssens-ge...@telenet.be<mailto:201010131527.41506.janssens-ge...@telenet.be>>

Content-Type: Text/Plain;  charset="iso-8859-1"



On Wednesday 13 October 2010, Cristian Marchi wrote:

> On the wiki page for GnuCash Concept Guide [1]  there is a section

> "Ready for Review" with a list of chapters. Where could I review them?

> Are they already on svn? I would like to do some modifications but I

> don't want to modify the xml files if someone is already working on them.

>

> Thanks

> Cristian

>

> [1] http://wiki.gnucash.org/wiki/Concept_Guide

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: A Start for 2.4 Documentation

[Thomas Bullock]

Juergen,

Thanks for  clarifying your effort and for answering my questions. 

> > 1.  Does this mean you will translate your German into English?
> >
> No it doesn't, at least at the moment.
> My priority is to produce a complete German version of the guide, since
> it seems to me, that there has never been a complete German translation
> of the existing English text. This is still a lot of work to do.
> I'm also not a native English speaker. But I'm interested in an
> exchange and cooperation with anybody, who writes an English version.
[] 
I am glad to cooperate with you.  It would be disastrous to give different 
messages
In different languages.

> 
> > 2.  Do your revisions support both 2.2.9 and 2.4 or have the methods
> of 2.2.9 been changed so that only 2.4 is shown?
> My goal is to write for version 2.4.  Most of the differences between
> the two versions that I am aware of, are extensions of 2.2.9, rather
> than changes (the SQL backends, CSV import, some new preferences).
> In my understanding the term 'change' could only be applied to the file
> naming issue. I try to explain the differences between 2.2.9 and 2.4.
> Do you have anything specific in mind?

[] 
No,  I do not have anything specific.  I have the general experience of 
encountering in many places statements that specify which version a change 
applies to.  Since the English is 3 years out of date (at least in some 
places), I realize there is a big job to bring it all to a timely description.  
The only trouble is that there are many users who have not upgraded to 2.2.9 as 
far as I know.  So I have to be guided by what the developers think is 
appropriate.  I expect that making the manuals consistent with 2.2.9 would 
leave only the need to upgrade to 2.4.  I am waiting for their input on this.

> 
> > Tom
> Juergen

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: A Start for 2.4 Documentation

[Thomas Bullock]

Hi Juergen,

> getting tired of translating outdated stuff into german, I rewrote
> parts
> of chapters 1 and 2, to address the new databases, the CSV importer,
> filename issue, preferences and others. Even though this is in German
> now, it might be helpful to look at the chapter headings, outline and
> screenshots. I'll be happy to synchronize the german stuff with the
> american version again.
> Juergen

[] 

Great to learn that you are already way ahead of me!  

1.  Does this mean you will translate your German into English?

2.  Do your revisions support both 2.2.9 and 2.4 or have the methods of 2.2.9 
been changed so that only 2.4 is shown?  I assume that users in Germany will be 
changing only gradually to 2.4 and the need for 2.2.9 support continues, at 
least for awhile.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: GC Concept Guide Review

[Thomas Bullock]

Here you are, Cristian.  Other than I you will be the first to see these.  
Please send me anything that is not clear or that does not work for you.  If 
you believe I have said something not correct, then please do point that out 
also.

Good luck.

Tom

From: Cristian Marchi [mailto:cr...@libero.it]
Sent: Wednesday, October 13, 2010 3:01 PM
To: Thomas Bullock
Cc: gnucash-devel gnucash
Subject: Re: GC Concept Guide Review



Il 13/10/2010 20:12, Thomas Bullock ha scritto:

Hi Cristian,

I don't believe what I am working on will be affected by your intended changes, 
but I should mention that I have a patch to Guide chapter 3 in process.  That 
patch also adds Chapter 16 and affects a couple other modules.

I believe these have been committed but not installed into subversion, at least 
as of this past Monday.  So please keep that in mind should you not find my 
changes in the svn checkout that brings the full set of docs to your own 
computer.
Ok, I've read your previous posts on this list about the documentation patch.



I am new to GC documentation and there is a multi-step process that I have to 
follow.  I have been asked to write that up, especially for the benefit of 
persons new to GC.   It is intended for a wiki, but I do not have the wiki 
created - just a text file.  If you think that might be of interest, I could 
send a copy of the notes I created for your use until something more public can 
be installed. ;-)

Sure, i'm also pretty new to documentation writing (I?ve only translated the 
GnuCash manual and help in Italian) so any advice on workflow is good.


Thanks
Cristian

HTH,

Tom Bullock






Date: Wed, 13 Oct 2010 15:27:41 +0200

From: Geert Janssens 
mailto:janssens-ge...@telenet.be>>

Subject: Re: Concept guide review

To: gnucash-devel@gnucash.org<mailto:gnucash-devel@gnucash.org>

Message-ID: 
<201010131527.41506.janssens-ge...@telenet.be<mailto:201010131527.41506.janssens-ge...@telenet.be>>

Content-Type: Text/Plain;  charset="iso-8859-1"



On Wednesday 13 October 2010, Cristian Marchi wrote:

> On the wiki page for GnuCash Concept Guide [1]  there is a section

> "Ready for Review" with a list of chapters. Where could I review them?

> Are they already on svn? I would like to do some modifications but I

> don't want to modify the xml files if someone is already working on them.

>

> Thanks

> Cristian

>

> [1] http://wiki.gnucash.org/wiki/Concept_Guide

GnuCash-Documentation-Update-Instructions.

[These instructions describe the process to change both the GnuCash "Guide" 
and the GnuCash "Help" manuals.]

--- 

PREFACE and INTRODUCTION -- WHAT TO EXPECT!

The recommendation of experienced programmers who work with code and 
related documentation is to obtain a copy of the full set of the 
documentation.  Besides having the modules you think you will need to 
change, you will easily be able to update other files, if you discover 
additional places requiring a modification.

In addition, other persons could be making changes to parts of the 
documentation at the same time you are.  You will need to make sure 
any changes others have made following your acquiring a set of the 
documentation are included in what you will install.

After obtainning your full set of the documentation, you will be 
inserting your modifications into the proper places in the set of 
documents.  Modules in the set are formatted using XML.  Later in 
processing the XML modules are converted to HTML versions for online 
easy viewing.  As a documentation support person your task is to 
shepherd your enhancements thru all stages from start to finish.

At each stage changes must be validated to assure that intended 
changes occur and other unexpected changes found are understood and 
either accepted or rejected after proper analysis.

Since your changes will be carried out by software, there is a 
difference determination process that identifies exactly what and where 
changes will be made.  This process permits you to be sure that only 
what you intend will actually be installed.

For the sake of quality control there is a review process that you 
must use in order to make your change "official".  The above brief 
description when executed results in a file of changes.  These changes 
must be explained as to their purpose.  Accompanying the explanationn 
in words is everything that makes up the substance of the change.  The 
term for this is "patch".  Whether you introduce a major restructuring 
or a small tweak, every thing is a "patch".  Creation of the 
explanation and the content of the change you are making are combined 
in a bugzilla event, otherw

A Start for 2.4 Documentation

[Thomas Bullock]

Developers,

Using the 
http://wiki.gnucash.org/wiki/Release_Schedule#Feature_Checklist_for_2.4.0 I 
have come up with a series of questions for which answers in some way would be 
included in the documentation or in FAQs.  The order and shape of the questions 
are listed just to get the thoughts churning.  The ultimate documentation 
likely will take a different shape.

With the list I am asking all of you (assuming you all were involved in 2.4's 
creation) to give me your answers and from them I will try to shape some 
statements that will be of use to users of the next version.  My answers in 
turn will be submitted for your agreement that they are or are not on target.

Here goes:


1.   What are the differences between the data file of 2.2.9 and how the 
data is saved in 2.4.0?  What can you do in 2.4.0 that was not possible in 
2.2.9?



2.  How is the database the user chooses  built?  What does the user do to 
bring his 2.2.9 data into 2.4 files?  Are there automatic conversion 
programs?



3.  Is it correct that each of the 3 DB choices are relational DB?  Will 
the user be able to see a diagram of the tables and all relationships?



4.  Once their data is in the chosen DB, will GC have a query page/screen 
that will permit the user to obtain results s/he uses to analyze the data in 
the DB?



5.  How are the user's accounts carried in the data base?  Is each a table?



6.  What makes a user pick one data base over the other two?  Do we have a 
list of reasons why each DB is preferred over the others?  What are the 
perceived advantages of each?  Is there a DB that businesses should prefer over 
the others?



7.  If a user selects DB 'A', will there ever be a reason for later 
migration to DB 'B' or 'C'?  How will such migration be accomplished?



8.  Webkit now replaces GtkHTML.  What benefit does the user get for this 
change?  What impact is there on how he accesses GC reports?



9.  What special instructions or changes from the former way does the user 
now need to know in order to be effective in using Webkit?



10.   A CSV importer now exists.  What does it import?  Is this in addition to 
QIF at initial load time?  Is it mainly to import split transactions?  Other 
importing?



11.   What are the instructions for correct use of the CSV importer?



12.   How do you describe the improved US Income Tax Report?The wiki says 
this is documented.  Where would the documentation be found?



13.   What are the updated tax codes?   Is this something the user needs to 
know, or are they tables that are used by program logic without user input?



14.   What are the new features in check printing?  Do these replace existing 
documentation or are they 2.4 only instructions and users of the older versions 
continue with existing documentation?



15.   Eguile reports are listed as a new feature in 2.4.  What does this item 
mean?  New reports?  Improved way of using existing reports?  Additional 
documentation needed?



16.   Explain the "Trading Account".  It is listed as a new account type.  
Explain what being a new type means.  What does the user do in order to use 
this new feature?



17.   Chinese input methods are listed as new features.  Elaborate what this 
consists of and how it works.  Is it restricted only to Chinese users?  Are 
these methods transportable to non-Chinese users?



18.   Some of the  above 17 items were indicated as still needing work.  Will 
this mean that one or more of the above will drop out of version 2.4.0 for 
later implementation?



19.   Is there an item that is new and to be included in 2.4 that is not listed 
above but should be?


Thanks to all for your input.

Tom Bullock








___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

GC Concept Guide Review

[Thomas Bullock]

Hi Cristian,

I don't believe what I am working on will be affected by your intended changes, 
but I should mention that I have a patch to Guide chapter 3 in process.  That 
patch also adds Chapter 16 and affects a couple other modules.

I believe these have been committed but not installed into subversion, at least 
as of this past Monday.  So please keep that in mind should you not find my 
changes in the svn checkout that brings the full set of docs to your own 
computer.

I am new to GC documentation and there is a multi-step process that I have to 
follow.  I have been asked to write that up, especially for the benefit of 
persons new to GC.   It is intended for a wiki, but I do not have the wiki 
created - just a text file.  If you think that might be of interest, I could 
send a copy of the notes I created for your use until something more public can 
be installed. ;-)

HTH,

Tom Bullock






Date: Wed, 13 Oct 2010 15:27:41 +0200

From: Geert Janssens 
mailto:janssens-ge...@telenet.be>>

Subject: Re: Concept guide review

To: gnucash-devel@gnucash.org

Message-ID: 
<201010131527.41506.janssens-ge...@telenet.be>

Content-Type: Text/Plain;  charset="iso-8859-1"



On Wednesday 13 October 2010, Cristian Marchi wrote:

> On the wiki page for GnuCash Concept Guide [1]  there is a section

> "Ready for Review" with a list of chapters. Where could I review them?

> Are they already on svn? I would like to do some modifications but I

> don't want to modify the xml files if someone is already working on them.

>

> Thanks

> Cristian

>

> [1] http://wiki.gnucash.org/wiki/Concept_Guide

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: [Bug 630652] Expanding and adding GnuCash Other Assets

[Thomas Bullock]

No problem about the stages.  We are getting closer! 

Tom

> -Original Message-
> From: Yawar Amin [mailto:yawar.a...@gmail.com]
> Sent: Saturday, October 09, 2010 4:18 PM
> To: Christian Stimming
> Cc: gnucash-devel@gnucash.org; Thomas Bullock
> Subject: Re: [Bug 630652] Expanding and adding GnuCash Other Assets
> 
> Uh, guys:
> 
> On 2010-10-09, at 05:32, Christian Stimming wrote:
> 
> > Am Friday 08 October 2010 schrieb Thomas Bullock:
> >> Thanks, Christian, for installing and committing this bug.
> >
> > Just to clarify: I've only marked the patch in the bug as "accepted-
> > commit_now", but I haven't committed it so far. (If I had, the patch
> > would have been marked "committed".)
> >
> > My change just makes the patch show up in a list of "commit_now"
> > patches, so that some other gnucash developer or myself, when we have
> > SVN access and some time, can even more easily find and commit this
> patch.
> 
> This has been committed in a slightly different way. Please see [1],
> and sorry for the confusion!
> 
> Yawar
> 
> [1] https://bugzilla.gnome.org/show_bug.cgi?id=630652#c10

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Documentation for the 2.4 release

[Thomas Bullock]

Thanks for the features list wiki reference.  It should be a good starting 
point for me to draft something.

Tom 

> -Original Message-
> From: Christian Stimming [mailto:stimm...@tuhh.de]
> Sent: Saturday, October 09, 2010 5:34 AM
> To: gnucash-devel@gnucash.org
> Cc: Thomas Bullock; Geert Janssens
> Subject: Re: Documentation for the 2.4 release
> 
> Am Friday 08 October 2010 schrieb Thomas Bullock:
> > Hi Geert,
> >
> > Sorry to be slow in responding.
> >
> > I have been thinking about your remarks.  I am comfortable making a
> draft
> > of such documentation.  But to do that I do need a list of features
> that
> > are new to 2.4.  I figure once I could put words to the features,
> > developers involved in creating the features could react to the draft
> by
> > pointing out what I got wrong or what was omitted and should be
> included.
> 
> http://wiki.gnucash.org/wiki/Release_Schedule#Feature_Checklist_for_2.4
> .0
> Indeed not very much user-visible new features, but that is correct.
> Sorry for
> that.
> 
> Regards,
> 
> Christian
> 
> > So far I am acquainted only with GC 2.2.9 and have not attempted to
> install
> > 2.3.15.  So you can see I am the least likely person to be writing
> the
> > documentation.  Up to now there seems to be no one else, so I am
> proposing
> > the above just to get something started.  This would be my
> contribution to
> > the idea you propose for a formalized documentation update process.
> >
> > I would also like to suggest that once the 2.4 release is actually
> > released, the developers help focus on at least the initial draft of
> this
> > documentation.  There should be install instructions (if needed) as
> well
> > as the general overview and database specific commentary.
> >
> > Once that would be prepared, user questions would quickly disclose
> what had
> > been omitted.  When that round of development had been completed,
> then
> > there would be time for adding new features beyond 2.4.
> >
> > Do these thoughts resonate as a way to get started?
> >
> > Tom
> >
> > > -Original Message-----
> > > From: Geert Janssens [mailto:janssens-ge...@telenet.be]
> > > Sent: Tuesday, October 05, 2010 10:35 AM
> > > To: gnucash-devel@gnucash.org
> > > Cc: Thomas Bullock
> > > Subject: Re: Documentation for the 2.4 release
> > >
> > > On Monday 4 October 2010, Thomas Bullock wrote:
> > > > Developers,
> > > >
> > > > What plans are you making for the documentation when the 2.4
> release
> > >
> > > become
> > >
> > > >  official?
> > >
> > > Hi Thomas,
> > >
> > > The silence you get as an answer already hints that there is not
> really
> > > a
> > > plan... at least I don't know of a formal one myself.
> > >
> > > I wonder if it would be useful to have some more formalized
> > > documentation
> > > update process, which includes calling on interested writers when
> > > GnuCash is
> > > stabilizing.
> > >
> > > > Due to it having the use of 3 types of databases, it seems to me
> that
> > >
> > > would
> > >
> > > >  entail a significant documentation update involving a general
> > >
> > > description
> > >
> > > >  of how GC would then work and specific sets of instructions for
> > >
> > > using each
> > >
> > > >  of the 3 data bases.  And I suppose there could  be impacts on
> how
> > >
> > > reports
> > >
> > > >  are prepared by GC.
> > > >
> > > > Am I thinking along the right lines?  If so, when would those
> > >
> > > enhancements
> > >
> > > >  be written and incorporated into the current Guide and Help
> manuals?
> > >
> > > All of the above suggestions would be very good additions to the
> > > GnuCash
> > > documentation.
> > >
> > > As to when ? Now would be a good moment. As far as I can tell, most
> > > developers
> > > are focussing right now on squashing the last remaining blocker
> bugs to
> > > get
> > > 2.4 ready. There are no new features planned anymore until the
> stable
> > > release
> > > and I expect no or only very small interface changes until that
> time as
> > > well.
> > >
> > > Which means that GnuCash as you can play with

RE: FW: [Bug 630652] Expanding and adding GnuCash Other Assets

[Thomas Bullock]

Christian,

Thanks for the enlightenment.  I did not appreciate the differences you are 
pointing out.  Since I found an error that slipped thru, I should wait until 
the commit actually happens, before fixing the one error that I am aware of.  I 
will wait for the commit notification.

Tom

> -Original Message-
> From: Christian Stimming [mailto:stimm...@tuhh.de]
> Sent: Saturday, October 09, 2010 5:32 AM
> To: gnucash-devel@gnucash.org
> Cc: Thomas Bullock
> Subject: Re: FW: [Bug 630652] Expanding and adding GnuCash Other Assets
> 
> Am Friday 08 October 2010 schrieb Thomas Bullock:
> > Thanks, Christian, for installing and committing this bug.
> 
> Just to clarify: I've only marked the patch in the bug as "accepted-
> commit_now", but I haven't committed it so far. (If I had, the patch
> would
> have been marked "committed".)
> 
> My change just makes the patch show up in a list of "commit_now"
> patches, so
> that some other gnucash developer or myself, when we have SVN access
> and some
> time, can even more easily find and commit this patch.
> 
> Thanks a lot for your contributions!
> 
> Christian
> 
> 
> >
> > Tom
> >
> > > -Original Message-
> > > From: GnuCash [mailto:bugzi...@gnome.org]
> > > Sent: Thursday, October 07, 2010 2:59 PM
> > > To: Thomas Bullock
> > > Subject: [Bug 630652] Expanding and adding GnuCash Other Assets
> > >
> > > https://bugzilla.gnome.org/show_bug.cgi?id=630652
> > >
> > >   GnuCash | Documentation | SVN
> > >
> > > Christian Stimming  changed:
> > >What|Removed |Added
> > >
> > > ---
> 
> > > -
> > >
> > >  Attachment #171173|none|accepted-
> commit_now
> > >
> > >  status||
> > >
> > > --
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Documentation for the 2.4 release

[Thomas Bullock]

Hi Geert,

Sorry to be slow in responding.

I have been thinking about your remarks.  I am comfortable making a draft of 
such documentation.  But to do that I do need a list of features that are new 
to 2.4.  I figure once I could put words to the features, developers involved 
in creating the features could react to the draft by pointing out what I got 
wrong or what was omitted and should be included.

So far I am acquainted only with GC 2.2.9 and have not attempted to install 
2.3.15.  So you can see I am the least likely person to be writing the 
documentation.  Up to now there seems to be no one else, so I am proposing the 
above just to get something started.  This would be my contribution to the idea 
you propose for a formalized documentation update process.

I would also like to suggest that once the 2.4 release is actually released, 
the developers help focus on at least the initial draft of this documentation.  
There should be install instructions (if needed) as well as the general 
overview and database specific commentary.

Once that would be prepared, user questions would quickly disclose what had 
been omitted.  When that round of development had been completed, then there 
would be time for adding new features beyond 2.4.

Do these thoughts resonate as a way to get started?

Tom

> -Original Message-
> From: Geert Janssens [mailto:janssens-ge...@telenet.be]
> Sent: Tuesday, October 05, 2010 10:35 AM
> To: gnucash-devel@gnucash.org
> Cc: Thomas Bullock
> Subject: Re: Documentation for the 2.4 release
> 
> On Monday 4 October 2010, Thomas Bullock wrote:
> > Developers,
> >
> > What plans are you making for the documentation when the 2.4 release
> become
> >  official?
> >
> Hi Thomas,
> 
> The silence you get as an answer already hints that there is not really
> a
> plan... at least I don't know of a formal one myself.
> 
> I wonder if it would be useful to have some more formalized
> documentation
> update process, which includes calling on interested writers when
> GnuCash is
> stabilizing.
> 
> > Due to it having the use of 3 types of databases, it seems to me that
> would
> >  entail a significant documentation update involving a general
> description
> >  of how GC would then work and specific sets of instructions for
> using each
> >  of the 3 data bases.  And I suppose there could  be impacts on how
> reports
> >  are prepared by GC.
> >
> > Am I thinking along the right lines?  If so, when would those
> enhancements
> >  be written and incorporated into the current Guide and Help manuals?
> >
> All of the above suggestions would be very good additions to the
> GnuCash
> documentation.
> 
> As to when ? Now would be a good moment. As far as I can tell, most
> developers
> are focussing right now on squashing the last remaining blocker bugs to
> get
> 2.4 ready. There are no new features planned anymore until the stable
> release
> and I expect no or only very small interface changes until that time as
> well.
> 
> Which means that GnuCash as you can play with in 2.3.15 minus some
> internal
> bugs will be what you get in 2.4 and hence can be used as a reference
> to
> update the documentation.
> 
> In any casy, I hereby invite everyone with some writing skills and some
> time
> on his hands to join us in updating the documentation with the latest
> and
> greatest new features that have been added in the 2.3.x development
> cycle. ;)
> 
> I'll try to contibute my part if and when I find some time. The next
> couple of
> weeks will be very busy for me outside of GnuCash...
> 
> Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

FW: [Bug 630652] Expanding and adding GnuCash Other Assets

[Thomas Bullock]

Thanks, Christian, for installing and committing this bug.

Tom

> -Original Message-
> From: GnuCash [mailto:bugzi...@gnome.org]
> Sent: Thursday, October 07, 2010 2:59 PM
> To: Thomas Bullock
> Subject: [Bug 630652] Expanding and adding GnuCash Other Assets
> 
> https://bugzilla.gnome.org/show_bug.cgi?id=630652
>   GnuCash | Documentation | SVN
> 
> Christian Stimming  changed:
> 
>What|Removed |Added
> ---
> -
>  Attachment #171173|none|accepted-commit_now
>  status||
> 
> --
> Configure bugmail: https://bugzilla.gnome.org/userprefs.cgi?tab=email
> --- You are receiving this mail because: ---
> You are on the CC list for the bug.
> You reported the bug.
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Documentation for the 2.4 release

[Thomas Bullock]

Developers,

What plans are you making for the documentation when the 2.4 release become 
official?

Due to it having the use of 3 types of databases, it seems to me that would 
entail a significant documentation update involving a general description of 
how GC would then work and specific sets of instructions for using each of the 
3 data bases.  And I suppose there could  be impacts on how reports are 
prepared by GC.

Am I thinking along the right lines?  If so, when would those enhancements be 
written and incorporated into the current Guide and Help manuals?

Thanks for your updates.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Documentation Bug 630652 created to install Guide update for Other Assets

[Thomas Bullock]

Hi Geert,

> 
> Since the target of discussion here is changes to the gnucash
> documentation,
> I'll presume we are making changes in a local subversion working copy
> of the
> gnucash-docs module.
> 
> To make a patch I let subversion do most of the work for me. Since
> we're
> working in a local working copy, subversion already keeps track of
> changes we
> make. It's just a matter of letting subversion output those changes in
> a nice
> patch format. The svn diff command is suitable for that. However, for
> the
> patch to be useful this command should be executed within a larger
> context.
> 
> 1. cd to the top-level directory of the gnucash-docs project
> 
> 2. A patch should always be made against the most recent revision of
> the
> gnucash-docs project in subversion.
> In order to make sure your working copy is based on the most recent
> revision,
> run svn update (or abbreviated, svn up).
> This will pull in all changes and patches that have been committed to
> the
> gnucash-docs module since you checked out your own working copy from
> subversion. If those changes don't conflict with your local changes,
> they will
> be merged automatically into your local working copy. If there are
> conflicting
> changes, you will have to figure out which changes to keep and which
> ones to
> dismiss. Recently svn has some primitive tools to help you with this.
> Upon
> conflicts it will ask you what to do.

After a couple days away from email I am rereading your most recent set of 
instructions.  Truly, these are
Right on the money for me and my write-up for the wiki.  All your comments are 
pertinent to what I am doing
And I intend to incorporate them into the wiki write-up. 

[As an aside and a matter of good form, whenever assembling ideas from emails 
Others have written, is it not 
correct that attribution for the content be given in the wiki write-up? Would 
this be done only in a general 
way, or is it correct and better to provide attribution by each quote?]

Also, thanks much for the references to svnbook.red-bean.com.  I was unfamiliar 
with this website.  It's 
Information is key to working effectively and accurately with svn.

Tom


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Documentation Bug 630652 created to install Guide update for Other Assets

[Thomas Bullock]

Hi Yawar,

> 
> > 3.  What happens in XML or HTML when trailing spaces are not removed?
> It clearly is important or you would not have spent the effort.
> 
> Oh dear. I'm afraid I'm something of a pedant about whitespace :-) As I
> mentioned in the change message, it's cosmetic. Sometimes spurious
> whitespace clutters up a repository's history, so some people don't
> like it. From the perspective of XML/HTML, multiple trailing spaces are
> simply combined into a single space in the output file. So e.g.,
> 
>   He said, I don't believe you.
> 
> would be turned into
> 
>   He said, "I don't believe you."

I get what you are saying here, but that does not answer the question about how 
whitespace is determined and removed.  Is that built in to Trac and 
automatically done?  Or does the updater have to identify these thru some 
laborious process?

> 
> > 6.  I found two errors that I had not caught previously: one is a
> spelling error; the other is a sequence of tenses error.  Since you
> have promoted my modules, when would be the proper time to correct
> those by making another patch.  I assume it would be after you get done
> promoting my changes to 2.2 as well as the trunk.  Is that correct?  If
> so, when will that likely be?  If not correct, what is your
> recommendation?
> 
> By any chance: discesses and damaage? Check out [5]: I've fixed those.
> If my changes in [6] and [7] look OK to you, I can go ahead and commit
> them to the repository. In any case, send a patch to the list, and I'll
> integrate all your further changes. It doesn't matter that you and I
> work in parallel and maybe change some of the same things-the software
> can handle that, that's the beauty of it :-)

Yes, discesses was the spelling mistake I found.  However, the sequence of 
tenses error is still there, since you did not mention it.
Please release changes in references [6] and [7].  I will make the suggested 
patch, a new one, for the sequence of tenses issue.

Thanks again for your attention to all these matters.  It really helps, 
especially as I have much to get used to.

Tom 


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Documentation Bug 630652 created to install Guide update for Other Assets

[Thomas Bullock]

Geert and Yawar,

Thanks to both for your thoughtful replies and instructions.  All your comments 
are relevant for me.  To make my patch I had to check out the most recent 
revision and then insert my changes and then test to see if I had messed up 
anything.  It would have saved me a lot of trouble had I known what you both 
have provided in your two most recent sets of instructions.  

That is not a complaint, because my experience made me able to appreciate and 
understand better what you provided in your messages.  I still have questions 
about parts, so I will send those on when I have worked thru what each of you 
have said.  In the meantime, know that all that you have provided will be 
integrated into my write up for documentation for new developers.  I was at the 
point where I was intending to investigate how to insert my stuff into the 
wiki.  That will be delayed until after I have updated my draft version of the 
notes for the wiki.

Thanks again.  You have provided great stuff!!

Tom 

> -Original Message-
> From: Geert Janssens [mailto:janssens-ge...@telenet.be]
> Sent: Thursday, September 30, 2010 1:52 AM
> To: gnucash-devel@gnucash.org
> Cc: Yawar Amin; Thomas Bullock
> Subject: Re: Documentation Bug 630652 created to install Guide update
> for Other Assets
> 
> On Thursday 30 September 2010, Yawar Amin wrote:
> 
> > > 2.  I suppose in learning how to use Trac I will learn how to
> integrate
> > > several modules into one output file.  If not, how do I do that?
> >
> > A single patch can actually contain all three kinds of changes:
> adding a
> >  new file, modifying an existing file, and deleting an existing file.
> Just
> >  make any and all changes you want, cd to the top-level directory of
> the
> >  gnucash-docs project, and run a ‘diff -ur >changes.patch’ from
> there. That
> >  will look through all subdirectories for changes and integrate
> everything
> >  into a single patch. For details on the diff command, run ‘man diff’
> and
> >  skim through the options there. (You can ignore most of them. Press
> Space
> >  to scroll down by a page, and ‘q’ to exit the manual viewer.)
> 
> The idea is right, but the example you give might be confusing. The
> diff
> command requires file or directory names to compare so the example as
> given
> will result in an error.
> 
> Since the target of discussion here is changes to the gnucash
> documentation,
> I'll presume we are making changes in a local subversion working copy
> of the
> gnucash-docs module.
> 
> To make a patch I let subversion do most of the work for me. Since
> we're
> working in a local working copy, subversion already keeps track of
> changes we
> make. It's just a matter of letting subversion output those changes in
> a nice
> patch format. The svn diff command is suitable for that. However, for
> the
> patch to be useful this command should be executed within a larger
> context.
> 
> 1. cd to the top-level directory of the gnucash-docs project
> 
> 2. A patch should always be made against the most recent revision of
> the
> gnucash-docs project in subversion.
> In order to make sure your working copy is based on the most recent
> revision,
> run svn update (or abbreviated, svn up).
> This will pull in all changes and patches that have been committed to
> the
> gnucash-docs module since you checked out your own working copy from
> subversion. If those changes don't conflict with your local changes,
> they will
> be merged automatically into your local working copy. If there are
> conflicting
> changes, you will have to figure out which changes to keep and which
> ones to
> dismiss. Recently svn has some primitive tools to help you with this.
> Upon
> conflicts it will ask you what to do. See [1] for more information on
> conflict
> resolution.
> 
> As a side-note, [2] is a very good introduction to subversion and how
> to
> perform basic things.
> 
> As another side-note: to avoid merge conflicts as much as possible,
> it's wise
> to run svn up regularly, so repository changes are pulled in frequently
> and in
> smaller chunks.
> 
> 3. Once the conflicts are resolved, run svn status (or abbreviated, svn
> stat)
> This will list all files that are different between your local working
> copy
> and the project in subversion. This can be files that have been
> deleted, new
> files or modified files. Again, see [2] to understand the output of
> this
> command.
> 
> 4. To create a patch, you have to make sure that subversion will
> consider your
> changes for commit. In practice only files that have status "A"
> (Added), "M"
>

RE: Documentation Bug 630652 created to install Guide update for Other Assets

[Thomas Bullock]

> -Original Message-
> From: Yawar Amin [mailto:yawar.a...@gmail.com]
> Sent: Monday, September 27, 2010 11:08 PM
> To: Yawar Amin
> Cc: Thomas Bullock; gnucash-devel (gnucash-devel@gnucash.org)
> Subject: Re: Documentation Bug 630652 created to install Guide update
> for Other Assets
> 
> Hi Tom,
> 
> OK, slight change of plans: I've just gone ahead and committed your
> patch into the docs repository [1], and then made some very simple
> cosmetic changes on top of that [2]. I'm working on some more changes
> that I will post here so you can have a look and see if it seems OK.
> Basically a little tweaking of sentences here and there, and then a few
> markup changes to take advantage of DocBook's features.
> 
> The plan after that is to backport these commits to the 2.2 branch,
> since everything you've written applies there as well.
> 
> For now, you can get a very good view of all changes made by following
> the referenced links. Trac (the software that runs this diff view) is
> especially great in that it shows you changes that have been made
> within a line, like deleting a single Space character.
> 
> Regards,
> 
> Yawar
> 
> [1] http://svn.gnucash.org/trac/changeset/19618
> [2] http://svn.gnucash.org/trac/changeset/19619

[] Yawar,  thanks for all  the attention you have paid to this patch of 
mine.  I just now got caught up with your previous emails connected with my 
patch and also trac changesets 19618 and 19619.  I now have these 
questions/comments:

1.  Where do I learn how to use Trac?  Its output is excellent when showing 
clearing the differences between two items.

2.  I suppose in learning how to use Trac I will learn how to integrate several 
modules into one output file.  If not, how do I do that?

3.  What happens in XML or HTML when trailing spaces are not removed?  It 
clearly is important or you would not have spent the effort.

4.  How does trac detect the presence of spaces in one module and not the 
other?  If you removed the unwanted spaces, how did you disclose them in order 
to remove them?

5.  thanks for calling to my attention these XML proper treatments: ’, 
‐, and ...

6.  I found two errors that I had not caught previously: one is a spelling 
error; the other is a sequence of tenses error.  Since you have promoted my 
modules, when would be the proper time to correct those by making another 
patch.  I assume it would be after you get done promoting my changes to 2.2 as 
well as the trunk.  Is that correct?  If so, when will that likely be?  If not 
correct, what is your recommendation?

Thanks again for your very careful review of my patch.  

Other Issue:  Still working on my description of what is needed in the sequence 
of steps for newcomers participating in the documentation effort.  Per John 
Ralls advice, I will put that in the wiki and let others know when that happens.

Best,

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Documentation Bug 630652 created to install Guide update for Other Assets

[Thomas Bullock]

OK, John, thanks for the tip.  Will do.  Have to clean up my scribbling first 
to make a clear statement on the wiki.

Tom

> -Original Message-
> From: John Ralls [mailto:jra...@ceridwen.us]
> Sent: Monday, September 27, 2010 9:58 AM
> To: Thomas Bullock
> Cc: gnucash-devel (gnucash-devel@gnucash.org)
> Subject: Re: Documentation Bug 630652 created to install Guide update
> for Other Assets
> 
> 
> On Sep 27, 2010, at 4:30 AM, Thomas Bullock wrote:
> 
> > Yawar,
> >
> > Thanks for jumping on this and making the improvements you mention.
> When done, please give me an example of the kind of thing you find so
> that I can know what to do for the next round.
> >
> > For the weekly status statement:  My current task is to complete my
> notes on the process to make documentation changes.  Several weeks ago,
> John or Geert asked me to submit those for inclusion in the wiki.  So I
> will post those next to this list when I have them ready.
> 
> Don't post them to the list, add them to the wiki. That's what wikis
> are for. Feel free to compose right in the wiki page; editing is  very
> easy and it has expressive features that aren't available in a word
> processor (like being able to set off code in a context-colored block).
> You can tell the list where you put it when it's done.
> 
> Regards,
> John Ralls
> 

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Documentation Bug 630652 created to install Guide update for Other Assets

[Thomas Bullock]

Yawar,

Thanks for jumping on this and making the improvements you mention.  When done, 
please give me an example of the kind of thing you find so that I can know what 
to do for the next round.

For the weekly status statement:  My current task is to complete my notes on 
the process to make documentation changes.  Several weeks ago, John or Geert 
asked me to submit those for inclusion in the wiki.  So I will post those next 
to this list when I have them ready.

Tom

> -Original Message-
> From: Yawar Amin [mailto:yawar.a...@gmail.com]
> Sent: Sunday, September 26, 2010 7:43 PM
> To: Thomas Bullock
> Cc: gnucash-devel (gnucash-devel@gnucash.org)
> Subject: Re: Documentation Bug 630652 created to install Guide update
> for Other Assets
> 
> Hi Tom,
> 
> On 2010-09-26, at 16:19, Tom Bullock wrote:
> 
> > Developers,
> >
> > Thanks to all who have supported my efforts to this point.  Due to
> your help I have created documentation bug 630652 and attached to it 5
> files supporting: the differences identified, the changes I made to 3
> existing files, and a new Chapter 16 dealing with Other Assets for
> inclusion in the Guide.
> >
> > These changes have been pushed thru to inclusion in the HTML version
> of the Guide.  I ask any developers to review, suggest improvements,
> changes, or point out corrections needed.  If no change is needed, then
> could these changes be incorporated into truck please?
> 
> I've downloaded the patch and am making some cosmetic changes (mostly
> formatting like replacing straight quotes with curly quotes, getting
> rid of extra spaces, etc.) Will post a revised patch to your bug as
> soon as I am able.
> 
> Regards,
> 
> Yawar

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Was Vol 90, Issue 30 Lost?

[Thomas Bullock]

Thanks!  I guess I don't have to worry now.

Tom

> -Original Message-
> From: Derek Atkins [mailto:warl...@mit.edu]
> Sent: Thursday, September 23, 2010 1:46 PM
> To: Thomas Bullock
> Cc: gnucash-devel (gnucash-devel@gnucash.org)
> Subject: Re: Was Vol 90, Issue 30 Lost?
> 
> Hi,
> 
> Thomas Bullock  writes:
> 
> > I subscribe by digest to this list and have all issues for Vol 90
> except #30.  Was this lost by server breakdown?  If not, can someone
> forward a copy to me?
> 
> It's quite possible it was lost by server breakdown.  I've completely
> disabled the milter that's been eating the email so it shouldn't ever
> happen again.  (it does mean more spam will get through and into the
> mailman administrative queues)
> 
> > Much appreciated.
> >
> > Tom
> 
> -derek
> 
> --
>Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
>Member, MIT Student Information Processing Board  (SIPB)
>URL: http://web.mit.edu/warlord/PP-ASEL-IA N1NWH
>warl...@mit.eduPGP key available
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Was Vol 90, Issue 30 Lost?

[Thomas Bullock]

I subscribe by digest to this list and have all issues for Vol 90 except #30.  
Was this lost by server breakdown?  If not, can someone forward a copy to me?

Much appreciated.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Unexpected results in attempting a patch

[Thomas Bullock]

Yawar,

Thanks for the thoro reply re my 2 questions and the link to pipes and 
redirection.  That definitely helps.  

I will be implementing your commands to get the results we both expect.  Thanks 
for detailing the part of the process that I had not yet seen on the way to the 
patch!

Tom

> -Original Message-
> From: Yawar Amin [mailto:yawar.a...@gmail.com]
> Sent: Monday, September 20, 2010 9:36 PM
> To: Thomas Bullock
> Cc: gnucash-devel (gnucash-devel@gnucash.org)
> Subject: Re: Unexpected results in attempting a patch
> 
> Hi Tom,
> 
> On 2010-09-20, at 20:20, Tom Bullock wrote:
> 
> >> [...]
> >
> > Yawar,
> >
> > I got the " errors when I ran the xmllint command.
> 
> Good stuff. You're almost there.
> 
> > Question 1:
> >
> > When I wanted to view the files in my Firefox browser I got this for
> the chapter named ch_accts.xml:
> >
> > XML Parsing Error: undefined entity
> > Location: file:///home/tbullock/gc-docs-090510/guide/C/ch_accts.xml
> > Line Number 20, Column 19:
> >
> > accounts. Since &app; does not impose any specific account tree
> > layout, --^
> >
> > Why does it view the symbolic parameter as an entity? How have you
> made the browser resolve the parameter making symbolic substitution? Do
> you have a script that does that prior to browser display?
> 
> You're right that there is actually a program that transforms our
> source XML files into browser-friendly HTML. I don't have a script per
> se, I just run the command directly (the following assumes you're in
> the guide/whatever-locale/ directory, e.g. guide/C/):
> 
> xsltproc -o output_html/ ../../xsl/general-customization.xsl gnucash-
> guide.xml
> 
> A little explanation: output_html is a directory that will
> automatically be created and filled with the output HTML. You can
> specify any name that makes sense. ../../xsl/general-customization.xsl
> is a relative path to the XSL stylesheet we are using to turn the raw
> input XML into the HTML we want, and it has to be that exact name.
> 
> At this point, the generated HTML guide will be in the output_html
> directory, and you can open any of the files in there with your
> browser. But the problem is you won't be able to see any images-
> screenshots, icons, etc. If that's OK, you can ignore the next bit. If
> not, a quick fix is to run:
> 
> cd output_html
> ln -s ../figures
> ln -s ../../../stylesheet
> 
> Now if you reload any page where you didn't see any image before, it
> will appear now.
> 
> Note that when you're ready to prepare your patch, you don't want the
> output_html directory to be mentioned anywhere in it, so delete it
> before doing the patch:
> 
> rm -rf output_html
> 
> > Question 2:
> >
> > I ran "svn diff" in a terminal and the result showed what I was
> expecting.  I then wanted to capture the output into a file to attach
> to a bugzilla bug report.  I used this command:
> > "svn diff | patch1" thinking I was going to pipe the output into the
> file called patch1.  Instead I got this response:
> >
> > No command 'patch1' found, did you mean Command 'patch' from package
> > 'patch' (main)
> >
> > obviously, I am misleading ubuntu 10.4 and don't know how to pipe
> output into a new file. What should I be doing?
> 
> As David Jensen said, it's the difference between Unix piping and
> redirection. A bunch of sites explain pipes et al., but a quick Google
> search turns up: http://polishlinux.org/console/unix-pipes-streams-and-
> redirections-explained/ Piping/redirecting is one of those things that
> can be very useful in Windows too from time to time.
> 
> HTH,
> 
> Yawar

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Unexpected results in attempting a patch

[Thomas Bullock]

> -Original Message-
> From: David Jensen [mailto:david.e.jen...@gmail.com]
> Sent: Monday, September 20, 2010 8:41 PM
> To: Thomas Bullock
> Cc: Yawar Amin; gnucash-devel (gnucash-devel@gnucash.org)
> Subject: Re: Unexpected results in attempting a patch
> 
> Tom,
> 
> 
> You don't pipe (|) to an output file, you redirect (>).  Pipes
> 'connect' the output of one program to the input of another, so you
> were trying to run the output from svn diff into a program patch1.
> You want > instead of | ("svn diff > patch1") to that you redirect the
> output to a file and not a program.
> 
> Regards,
> David

[] 
Thanks, David.  I appreciate the linux information.  Still have much to learn.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Questions re Documentation in Bugzilla

[Thomas Bullock]

Christian,

Thanks for making that clear.  I will follow that practice.

Tom

-Original Message-
From: Christian Stimming [mailto:stimm...@tuhh.de] 
Sent: Monday, September 20, 2010 1:48 PM
To: Thomas Bullock
Cc: gnucash-devel (gnucash-devel@gnucash.org)
Subject: Re: Questions re Documentation in Bugzilla

Am Monday 20 September 2010 schrieb Thomas Bullock:
> If someone wants to work on a particular  bug, does that person assign it
> to her/himself?

Theoretically, yes. However in practice I think the re-assignment of a bug can 
only be done by people who are marked as "gnucash developers" in bugzilla (the 
complete list is on the Browse page). Hence, in practice the "assign to"-field 
isn't considered to have a lot of meaning inside the gnucash project (this may 
be significantly different in other projects). Usually the people just comment 
in a suitable way to indicate they are really into this particular bug and 
other people don't need to spend extra time on it.

Regards,

Christian
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Gource Representation

[Thomas Bullock]

Date: Wed, 8 Sep 2010 21:19:25 +0200
From: Geert Janssens 
Subject: Development visualization with gource
To: "gnucash-u...@gnucash.org" 
Cc: gnucash-devel@gnucash.org
Message-ID: <201009082119.26281.janssens-ge...@telenet.be>
Content-Type: Text/Plain;  charset="us-ascii"

Today I felt like doing something else than hunting bugs on the GnuCash code, 
so I made something prettier:

http://www.youtube.com/watch?v=g7jrct45jdE

This video is a visual representation of the development of GnuCash since its 
early beginnings in 1997 up until today.


Above is a 

Beautiful job, Geert!

A couple questions:

a) who is the queen bee at the very start of the demo?  Derek Atkins?  Someone 
no longer on the project?  Very impressive chain of activities.

b) I assume you did this with the changes to code.  Would doing the same to the 
documentation be worth showing?

c) Due to the plethora of branches spinning off in so many directions it is 
confusing to understand what is illustrated.  Are some of the small branches 
now defunct?  Or how are these to be understood and which is the main branch 
from which we take the stable version?  If that can be detected from the info 
in the graphic display, my visual was too small to read the numbers and words.  
The graphic is a great presentation of what is happening or happened.  A 
footnote on at least the main  branches would help appreciate the various 
parts.  Don't know if that would be possible.   

I really like what you created and would like to see that as an ongoing 
component of GC to help newcomers appreciate where we came from and where we 
are now.

Tom


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Status on work toward a patch

[Thomas Bullock]

> -Original Message-
> From: Yawar Amin [mailto:yawar.a...@gmail.com]
> Sent: Wednesday, September 08, 2010 11:03 AM
> To: Thomas Bullock
> Cc: gnucash-devel@gnucash.org
> Subject: Re: Status on work toward a patch
> 
> Hi,
> 
> On 2010-09-08, at 10:48, Thomas Bullock wrote:
> 
> > 4. create a bugzilla patch submitting my work for formal review as a
> > patch
> 
> The first three will probably take some time, but you can do # 4 at any
> time. When you create the issue in Bugzilla, you can set out your goal
> over there and if you want, link to archives of discussions that have
> taken place here. They are all archived at lists.gnucash.org. Then when
> you have the patch ready, simply go to the issue you created and attach
> it there.
> 
> Regards,
> 
> Yawar

Thanks for the instructions.  If I get stuck, I will ask your help to get past 
The sticking point.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Status on work toward a patch

[Thomas Bullock]

Per Derek's request for a weekly status report on documentation update efforts:

The patch has now been restructured according to the suggestions I received 
from Geert.

That means the following are still to do:
1.  validate xml on the new patch structure
2.  do a review of changes from 2.0.0 to current as shown by logs for installed 
code changes and also installed document changes
3.  submit my list of identified changes to developers and see if the list is 
considered complete
4.  create a bugzilla patch submitting my work for formal review as a patch

Tom


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: First look at Guide update

[Thomas Bullock]

Monday, August 16, 2010 5:10 PM: John Ralls [mailto:jra...@ceridwen.us] wrote
 
> 
> [<>: ] that's what I got too, except I did not format for clarity.  What 
> you seem to be saying is that tips and notes always have to be the last 
> things in a section, or at least section2's.
> 
> I accept that you are saying it, but how did you figure that out from the 
> xmllint output?  I have not been able to find any DTD or equivalent that 
> spells out the expected sequence.  I realize that xmllint has access to that 
> in order for it to work.  Where do I find what xmllint is using?
> 
> And thanks very much for clearing up my problem.  I will make the changes and 
> proceed to setting up a bugzilla patch.
> 
> Tom
> 

No, I'm saying that the  and  elements can't be direct children of 
 after the first , < sect2>, or   element.

The first part of the error message shows the types of elements that xmllint 
expects; the second part what it found. Study it and you'll see how I found the 
problem. Here's the decoder ring:
+ means one or more
* means zero or more
? means zero or one
If a symbol isn't followed by one of those, it means exactly one.
( foo | bar | baz) means that one of these elements must appear. If the whole 
group is followed by a numeration symbol, it means that all of the elements in 
the group may appear in any order the number of times indicated, so 
(foo|bar|baz)+ means at least one of them must appear, but there can be as many 
as you like. If the numeration symbol is inside (foo+|bar+|baz+), then only one 
type is allowed -- in that example, one or more foo, one or more bar, or one or 
more baz.

The top-level DTD 's URL is in the header block of gnucash-guide.xml:
 http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
The child DTDs are located in the same directory, along with a readme and a 
handy zip file.

(I find RelaxNG compact schemas to be much easier to read than DTDs. Trang 
(http://code.google.com/p/jing-trang/) will convert the DTDs if you're 
interested in pursuing that. Java required.)

Before you make a patch, build the html and look at the result in a browser to 
make sure that all of the formatting came out the way you want.

Regards,
John Ralls

[<>: ] thanks, John.  I guess your name now is Captain Marvel.  I remember 
the breakfast cereal magic decoder rings from my childhood, something that 
Captain Marvel gave the devoted followers of his radio programs!

I will follow up with Trang and the child DTDs to know what you are explaining. 
 As always, I do appreciate your support.

Tom Bullock
 

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: First look at Guide update

[Thomas Bullock]

John Ralls [mailto:jra...@ceridwen.us] writes:

OK, I've taken your wiki posting and run it through xmllint. The output (after 
reformating it for clarity) is

> (sect1info? , 
>   (title , subtitle? , titleabbrev?) , 
>   (toc | lot | index | glossary | bibliography)* , 
>   (
> (
>   (calloutlist | glosslist | itemizedlist | orderedlist | segmentedlist | 
>  simplelist | variablelist | caution | important | note | tip | 
> warning |
>  literallayout | programlisting | programlistingco | screen | 
> screenco |
>  screenshot | synopsis | cmdsynopsis | funcsynopsis | classsynopsis |
>  fieldsynopsis | constructorsynopsis | destructorsynopsis | 
>  methodsynopsis | formalpara | para | simpara | address | blockquote 
> | 
>  graphic | graphicco | mediaobject | mediaobjectco | informalequation 
> | 
>  informalexample | informalfigure | informaltable | equation | 
> example | 
>  figure | table | msgset | procedure | sidebar | qandaset | anchor | 
>  bridgehead | remark | highlights | abstract | authorblurb | epigraph 
> | 
>  indexterm | beginpage)+,   
>   (refentry* | sect2* | simplesect*)
> ) | 
>   refentry+ | sect2+ | simplesect+), 
>   (toc | lot | index | glossary | bibliography)*
> ), got 
> (title 
>para 
>para 
>para 
>para 
>sect2 <- "BEGIN NEW CONTENT" is in the middle of this section
>sect2 
>sect2 
>sect2 
>sect2 <- "SIGNIFICANT NEW CONTENT ENDS HERE" is at the end of this 
> one. 
>tip 
>sect2 
>tip 
>sect2 
>tip 
>note 
>sect2 
> )


which pretty clearly shows the problem: You promoted those  and  
elements to the top level; they should have remained in the  elements 
that they were in originally. In every case, the  tag needs to be moved 
from just above to just below the offending elements, after which xmllint 
passes.

Regards,
John Ralls
 

[<>: ] that's what I got too, except I did not format for clarity.  What 
you seem to be saying is that tips and notes always have to be the last things 
in a section, or at least section2's.

I accept that you are saying it, but how did you figure that out from the 
xmllint output?  I have not been able to find any DTD or equivalent that spells 
out the expected sequence.  I realize that xmllint has access to that in order 
for it to work.  Where do I find what xmllint is using?

And thanks very much for clearing up my problem.  I will make the changes and 
proceed to setting up a bugzilla patch.

Tom




___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: First look at Guide update

[Thomas Bullock]

John Ralls [mailto:jra...@ceridwen.us] 
writes:


Tom,

What Frank is trying to tell you is that you should use XML comments rather 
than wiki markup in the code block so that others can help you with your 
validation problem. (Wiki markup gets turned off in code blocks anyway, as you 
see from the result.) It looks like a patch because, being a dev, Frank used 
patch notation as shorthand for what you should do differently.
[<>: ] thanks for interpreting.  Nothing against Frank.  I am just too new 
to catch the short-hand.


He also apparently found tab characters in the code block. That might be an 
artifact of the wiki rather than anything you did overtly; if so, no problem. 
It might also be something that your editor does for you when indenting the 
text elements to look pretty. If so, that might create differences from the 
original which are whitespace only, not content, and make your diff larger. 
This is often an avoidable problem in code, but is probably not avoidable in 
text because if you add a sentence to a paragraph and then re-justify the 
paragraph it's going to affect every line after your inserted sentence anyway. 
(A diff program that "normalized" the XML before generating the diff would 
solve that problem. Those typically have their own formats, so everyone working 
with your changes would need to agree on which one.)
[<>: ]  Since you did not mention the name of such a program that 
normalizes XML, I assume that GC developers have not adopted one as the 
standard.  It would be handy for those working with a lot of XML.  Let me know 
if I assume wrong.


Anyway, perhaps you could make a diff from your first attempt and put it in 
bugzilla. Then some of us with more XML experience can apply it in our own 
sandboxes and help you with the errors. Once they're fixed and other comments 
applied, you can replace the attachment to the bug. After everyone is happy, a 
dev will apply the final version of the patch and close the bug, and you start 
the process again with a new edit and a new bug.
[<>: ]   I can work with that plan!


Keep the patches small at first. This helps you track down validation problems 
and makes writing the change memo easier. After you've had some practice at 
writing DocBook markup and change memos, you may want to submit larger patches 
-- or not. In general, lots of small revisions makes for better change history 
than a few large ones, especially if the large ones cover multiple topics.
[<>: ]  Sounds like very good advice.  In fact, maybe the first small 
patch won't have the present xml  validation complaint!


Regards,
John Ralls
[<>: ] I appreciate the extra effort you and Geert are putting in to 
keeping me afloat while my learning curve grows!  Thanks again.


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Draft content now in new location

[Thomas Bullock]

Everyone,

Thanks to all comments and instructions I learned about the GC wiki which is 
not inside wikipedia.  My mistake.  My point in putting the content in the wiki 
was for all to have a chance to look at the proposed change.

So for what now is listed at the new (to me) location is just the content I am 
proposing.  It is in xml formatting, not in patch notation, because all of it 
is intended to be inserted in one place.  When I get to the patch stage, the 
patch will show all the expected changes wherever they appear.

Here is where you can find what I am proposing:

http://wiki.gnucash.org/wiki/Concept_Guide#Ongoing_work

Thanks to Derek, John, and Geert for pulling me into the direction and path 
most are used to.

Tom

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Best location to place interim Guide information

[Thomas Bullock]

Thanks, John.  I appreciate the tip and the note to search.

Tom

-Original Message-
From: John Ralls [mailto:jra...@ceridwen.us] 
Sent: Monday, August 16, 2010 12:23 PM
To: Thomas Bullock
Cc: gnucash
Subject: Re: Best location to place interim Guide information


On Aug 16, 2010, at 8:51 AM, Thomas Bullock wrote:

> Derek Atkins [warl...@mit.edu] writes:
> 
> 
> 
> 
> Why not use http://wiki.gnucash.org/wiki/ ???
> 
> 
> 
> Answer:  I did not know it existed, just one of many I expect that I have not 
> discovered yet.  I just looked at and I see two possible objections: a) it is 
> a protected page and not changeable by just anyone, so who would change this 
> page?, and b) it covers many topics and my hope was to focus on just the 
> Guide updates as they were being pre-viewed.
> 
> Of course these can be gotten around.
> 
> I have copied the developer's list to include them in any discussion of a 
> preferred way to present new information.
> 

The page Derek pointed you at is the wiki's start page, so of course it's 
protected. There are lots of editable pages in the wiki -- otherwise it 
wouldn't be a wiki, would it? Searching for "Guide" brings up 6 pages of 
"Concept Guide draft/Foo" from 2006, probably the last effort like yours, and  
http://wiki.gnucash.org/wiki/Concept_Guide? which is an overview page. I think 
you can probably take those over and do what you will with them.

Regards,
John Ralls

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Best location to place interim Guide information

[Thomas Bullock]

Geert Janssens [mailto:janssens-ge...@telenet.be] writes:

> Answer:  I did not know it existed, just one of many I expect that I have
>  not discovered yet.  I just looked at and I see two possible objections:
>  a) it is a protected page and not changeable by just anyone, so who would
>  change this page?, and b) it covers many topics and my hope was to focus
>  on just the Guide updates as they were being pre-viewed.
> 
I think you misunderstood Derek here.
[<>: ] I can see that I did.  I am very literal, especially with new 
topics for which I have not developed much of a sense of how things work yet.





The link he posts is the front page of the gnucash wiki, and the only one 
protected for editing. You can easily create new pages in this wiki (once you 
have applied for a username and password).

Only if you wish to link these pages to the front page, you'd have to ask a 
dev. This is mainly done to limit spam on the wiki.

Personally I think the gnucash wiki is the preferred location for interim 
guide information. It is *the* wiki where gnucash related information is kept 
both for developers as for users. Just like wikipedia, it uses MediaWiki as 
the wiki engine, so you can use the same syntax rules you used on wikipedia.

[<>: ]   Thanks for this information.  I did not understand that this wiki 
was not part of Wikipedia.  I will move my info to this page shortly and then 
issue a new location to both lists.




I'd suggest you just start a page and publish it's link via the mailing lists. 
I can link it on the front page as well if you like. If there's more 
information than fits one page, feel free to split it up on multiple pages, 
and simply add links between them.

[<>: ]   thanks for this offer.  I will take you up on it once I get 
reorganized.  Unless there is a page size-limit, what I have should fit on a 
scroll-able page.

You and John Ralls have been a great help as I stumble along!  Thanks.

Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: First look at Guide update

[Thomas Bullock]

H. Ellenberger 
[mailto:f.ellenber...@online.de] 
writes:









> Before working on any additional updates to the Guide I intend to

> complete these items:

> a)  correct the xml validation problem in the current patch effort



You should quote your annotations e.g. as comments like

--- ch_accts.xml.tom2010-08-14 14:54:31.0 +0200

+++ ch_accts.xml  2010-08-14 14:35:59.0 +0200

@@ -197,7 +197,7 @@

outstanding debts 
owed to you. It is considered an asset because

you

should be able to 
count on these funds arriving.



-   '''BEGIN NEW CONTENT HERE!!'''

+   



  Other 
Assets No matter how diverse they

are, GnuCash 
handles all the following situations easily.  The

group

@@ -590,7 +590,7 @@



  



-   '''SIGNIFICANT NEW CONTENT ENDS HERE'''

+   





  For all GnuCash asset accounts, 
a debit



There seems to be more, but this is a first step.

[<>: ]  Hi Frank,



I am confused by your comment.  I am glad to try to follow your suggestion.  
But the example you listed above is from a patch that you seem to have run.  I 
was not making a patch.  What I put on the wiki is the xml listing of 
ch_accts.xml.  I inserted the all caps START STOP comments only to show what 
had been added and where it ended.



If this confuses everyone, then what you seem to want is for me to put a patch 
on the wiki?  Is that correct?  If so, I cannot do that because I continue to 
have an xml validation error that I have not resolved yet.



Please tell me the exact process to quote my annotations that you want me to 
follow.  The patch process seems to do that nicely.  What in addition do you 
wish me to do?







[<>: ] 



BTW: The original Author used 2 spaces instead of tab. Can you configure your

editor to show the same behavior? Otherwise it would be really hard, to find

your real work in all the changed whitespace.



[<>: ]  I have not yet used tabs, so I am not sure what you refer to.  
Perhaps it is because you thought I was placing a patch on the wiki?  If not, 
can you make your finding more specific so I can look for it?



Cheers

Frank

[<>: ]

Thanks again for taking the time to look at what I put out for examination.



Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Best location to place interim Guide information

[Thomas Bullock]

Derek Atkins [warl...@mit.edu] writes:




Why not use http://wiki.gnucash.org/wiki/ ???



Answer:  I did not know it existed, just one of many I expect that I have not 
discovered yet.  I just looked at and I see two possible objections: a) it is a 
protected page and not changeable by just anyone, so who would change this 
page?, and b) it covers many topics and my hope was to focus on just the Guide 
updates as they were being pre-viewed.

Of course these can be gotten around.

I have copied the developer's list to include them in any discussion of a 
preferred way to present new information.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Guide Documentation Patch #1 - Update #3

[Thomas Bullock]

Per request from Derek: steps taken to support an effort to bring GC 
documentation up-to-date --


* This past week Mike Alexander fixed the AppendixD xml validation 
errors

* I reached the process involved in xml validation; John Ralls gave me 
a new direction and I hope to correct my xml error soon

* I also have been researching the list of changes shown on the main 
web page (http://www.gnucash.org/) for the purpose of developing a list of 
changes since 2.2.2 thru the present.

* I have received a process to do the same with the SVN Logs for code 
and documents; that has not been started yet

* I have started studying how to make a wiki page with a view to using 
wiki pages as interim staging areas to (a) hold new interim documentation (b) 
track gradual progress against a list of undocumented GC features

That's it for now.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Output from xmllint: your help needed!

[Thomas Bullock]

<>
The DocBook DTDs are indeed large and complex. You're likely to go quite mad 
trying to understand DocBook by reading the DTDs. Try the documentation 
(http://www.docbook.org/tdg5/) instead. It has the advantage of being written 
for humans rather than computers.

Regards,
John Ralls
<>

Thanks, John.  I certainly don't want to go mad!!  It looks like the path to a 
solution!

Tom

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Documentation Processing Ideas

[Thomas Bullock]

Geert, John, and all the others who have been supporting my effort by your 
helpful answers,

Thank you!  You are welcome for your thanks that I am starting on 
documentation.  I will try to live up to your trust that my effort will 
actually result in something that is useful to GC users.  It seems to me that 
there is still much to learn just to put me in position to make a contribution 
that others can use.

Your SVN log instructions are just what I need to access its information, both 
in a terminal and in a gui.

Using a wiki for interim staging of information will also take some time as I 
learn the structure and process of building and modifying wiki pages and 
integrating them into the Gnucash set of pages.

Thanks, all! 

Tom
-Original Message-
From: Geert Janssens [mailto:janssens-ge...@telenet.be] 
Sent: Wednesday, August 04, 2010 2:13 PM
To: gnucash-devel@gnucash.org
Cc: Thomas Bullock; John Ralls
Subject: Re: Documentation Processing Ideas

On Wednesday 4 August 2010, Thomas Bullock wrote:
> [<>: ] Thanks John, for your clear and relevant comments and
>  instructions.  Also, daunting, I must say!!
> 
> First, how do I access the SVN log?  Is that a separate file or part of the
>  download process when I use the SVN CHECKOUT process?  Whether it will be
>  helpful or not won't be known until I read it.  For practical purposes I
>  need to examine the range of changes from 2.0.0 to present.  Since
>  documentation has not been kept up, I assume that I would have to look at
>  the Code log as well as the documentation log.  So I guess that means 2
>  SVN logs.
> 
On the command line, you can call "svn log" in the directory of which you want 
to see the logs. Note that this will cause a very long listing though.

There is also a web interface to these logs. You may find that easier to use:
http://svn.gnucash.org/trac/browser

This page is an online view of the subversion repository. You can navigate up 
and down the source and documentation tree here. On the right side of the page 
you have a link: "Revision Log", which, when clicked, will give you the svn 
revision log for the directory you are in.

Note that the log command and the "Revision Log" link both work recursively. 
So if you use it in a certain directory, it will give you a list of all 
revisions in that directory AND its subdirectories (which is useful in my 
opinion).

> Second, however I get the information, I think the most urgent need is to
>  document installed working features that have not yet been disclosed
>  [meaning in the documentation, even though such features could have been
>  issues of discussion in the user and developers lists] describing first
>  their purpose then how to use them.  That could be a list in itself, only
>  to be brought into focus by research and the contributions of system users
>  and developers.  Later on, once this is caught up, it makes sense to me to
>  systematically test every bell and whistle to find out whether documented
>  and, if so, does it work as described.
> 
That makes sense.

> Third, the idea of a wiki page is good.  The present limitation is that I
>  need to learn how to create and use such a tool.  The wiki allows
>  flexibility for many people to add ideas as the ideas appear to them.
> 
Yes, working with a wiki or xml differs from working with a typical word 
processor. The key difference to remember is that wiki/xml markup focuses on 
the document structure (you define chapters, sections, subsections, 
paragraphs,...) instead of presentation (the layout is defined in completely 
separate files, usually css).

Typical use of a word processor has this blurred a bit. It mixes content and 
presentation with less focus on the document structure. This is good for 
simple, relatively small documents, but less so for big, complex ones. (Note 
that you *can* have a structure focused workflow with a word processor, but 
most people don't do or know how to do this.)

Good directories to run the log command (or click the "Revision Log" link) 
would be
gnucash/trunk: this will give you the logs for all code changes
gnucash-docs/trunk: this will give you the logs for all documentation changes

> Fourth, my thought is to stay focused on the Guide.  Once it is better,
>  then focus could shift to Help.  Is that reasonable?
> 
I agree.

> Fifth, there is a dimension to the documentation process that is time
>  consuming.  I am toying with the idea that some kind of documentation is
>  better than none.  Using a wiki as an INTERIM step to getting missing
>  documentation available quickly may permit covering more ground sooner
>  than going the extra mile to integrate everything into the Guide and Help
>  manuals right at the beginning.  Do you think that idea would be accepted
>  even though not the preferred and fina

RE: Manual and Guide Versions in the documentation

[Thomas Bullock]

<>

> The present pages documents only from version 2.3.7 thru 2.3.14.  I 
> have to review from 2.0.0 to 2.4 (whenever that is released), so I 
> have a much bigger list.  Do you know where I can get changes listed 
> from 2.0.0 thru 2.3.6?
> 
> Thanks.

Try http://gnucash.org/oldnews.phtml (it's listed at the very bottom of the 
main page).

<>

Excellent!!  Thanks, David.

Tom

   
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Manual and Guide Versions in the documentation

[Thomas Bullock]

<>

the main Gnucash page (www.gnucash.org) includes release announcements that 
include substantial lists of changes from version to version. I don't know if 
the lists are exhaustive, but they are sure exhausting to wade through. 

There may be a better way to get this information, since I believe it's culled 
from svn somehow.

David
<>

Hi David,

Thanks for pointing out the lists of changes.  I have scanned the current page 
and see what you mean. 

It looks like among what is there I could get an idea of the kinds of changes 
that occur.  A lot of the present entries mention bug fixes.  I hope to 
identify main software enhancements, the end results of all the individual 
correcting steps.  It is certainly a place not to be overlooked.

The present pages documents only from version 2.3.7 thru 2.3.14.  I have to 
review from 2.0.0 to 2.4 (whenever that is released), so I have a much bigger 
list.  Do you know where I can get changes listed from 2.0.0 thru 2.3.6?

Thanks.

Tom  


-Original Message-
From: David T. [mailto:sunfis...@yahoo.com] 
Sent: Tuesday, August 03, 2010 8:47 PM
To: John Ralls; Thomas Bullock
Cc: gnucash-devel gnucash
Subject: Re: Manual and Guide Versions in the documentation



--- On Tue, 8/3/10, Tom Bullock  wrote:

> From: Tom Bullock 
> Subject: Manual and Guide Versions in the documentation
> To: "John Ralls" 
> Cc: "gnucash-devel gnucash" 
> Date: Tuesday, August 3, 2010, 2:23 PM
> <>
> 
> Message: 8
> 
> Date: Mon, 2 Aug 2010 12:50:20 -0700
> 
> From: John Ralls 
> 
> Subject: Website Links
> 
> Also, the online manual and guide seem to be for 2.0; it
> should be updated to 2.2.
> 
> Regards,
> 
> John Ralls
> 
> <>
> 
> John,
> 
> Your comment raises the question: What is the
> process/method that documentation version reporting should
> follow?
> 
> Looking at the little I have been working on in the Guide,
> the top-level NEWS module shows a history of version changes
> ending at version 2.0.1 dated 10/08/2006. Before that,
> leading up to that point,  there is a trail of version
> changes and implementation dates (I infer) with a brief
> comment about reason for entry.
> 
> Since the documentation seems to be behind installation of
> new features, is there a way to identify the features added
> since the last point at which the documentation did match
> the feature install? If that can be figured out, then that
> provides a "to-do" list for documentation updates (I
> assume). It also would suggest the order that patches should
> be added, if documenting in the order of oldest to newest
> feature first.

the main Gnucash page (www.gnucash.org) includes release announcements that 
include substantial lists of changes from version to version. I don't know if 
the lists are exhaustive, but they are sure exhausting to wade through. 

There may be a better way to get this information, since I believe it's culled 
from svn somehow.

David


> 
> Your thoughts and anyone else's experience would be much
> appreciated to define the scope of what is needed.
> 
> Thanks.
> 
> Tom
> 
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> 


  
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Documentation Processing Ideas

[Thomas Bullock]

<>
Ideally, of course, every change will be described in the Changelog, and 
significant changes will be described in NEWS (significant meaning 
rewrites/additions to reflect changes in the program's operation.) The reality, 
unfortunately, is that the only reliable documentation is the SVN log. This is 
equally true on the code side.
(In that ideal world, developers would at least add comments in the appropriate 
places in the documentation files describing changes to the code that require 
changes to the documentation. That world doesn't exist.)

If you want to be rigorous, you'll have to go through the SVN log for gnucash 
trunk and try to figure out which changes alter the interface or behavior in a 
way than affects the documentation and make a checklist. That's probably much 
more easily said than done, because most of the checkin messages are brief and 
a bit cryptic.

The other approach is to try out everything that is documented and make sure 
that it still works the way the docs say. You may notice menus or buttons that 
aren't documented already; you can write about the ones that you can figure out 
and ask about the others.

Whichever you choose (perhaps a combination), perhaps you could start a wiki 
page showing what you find. Once it's up, perhaps the devs who've added things 
in the last couple of years can mention their work there to help you find the 
undocumented bits.

In fact, it would be worthwhile for all of the devs and the experienced users 
on the user list to actually read the docs (I for one haven't looked at them 
since 1.8 or so, and the program has changed a lot since then) and contribute 
to that wiki page things that they know should be added.

The rest of the wiki is of course another good source of tips, tricks, and 
workarounds that could be added or used to clarify the docs. There's probably a 
bunch of obsolete stuff there that could be pruned, too, but that's a separate 
issue except to note that everything needs to be tested out before it gets 
added to the docs.

Regards,
John Ralls
<>

[<>: ] Thanks John, for your clear and relevant comments and instructions. 
 Also, daunting, I must say!!

First, how do I access the SVN log?  Is that a separate file or part of the 
download process when I use the SVN CHECKOUT process?  Whether it will be 
helpful or not won't be known until I read it.  For practical purposes I need 
to examine the range of changes from 2.0.0 to present.  Since documentation has 
not been kept up, I assume that I would have to look at the Code log as well as 
the documentation log.  So I guess that means 2 SVN logs.

Second, however I get the information, I think the most urgent need is to 
document installed working features that have not yet been disclosed [meaning 
in the documentation, even though such features could have been issues of 
discussion in the user and developers lists] describing first their purpose 
then how to use them.  That could be a list in itself, only to be brought into 
focus by research and the contributions of system users and developers.  Later 
on, once this is caught up, it makes sense to me to systematically test every 
bell and whistle to find out whether documented and, if so, does it work as 
described.

Third, the idea of a wiki page is good.  The present limitation is that I need 
to learn how to create and use such a tool.  The wiki allows flexibility for 
many people to add ideas as the ideas appear to them.

Fourth, my thought is to stay focused on the Guide.  Once it is better, then 
focus could shift to Help.  Is that reasonable?

Fifth, there is a dimension to the documentation process that is time 
consuming.  I am toying with the idea that some kind of documentation is better 
than none.  Using a wiki as an INTERIM step to getting missing documentation 
available quickly may permit covering more ground sooner than going the extra 
mile to integrate everything into the Guide and Help manuals right at the 
beginning.  Do you think that idea would be accepted even though not the 
preferred and final solution?

Tom


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Patch update #2

[Thomas Bullock]

Thanks, Mike.  Your fix cleared up all the appendix D issues.  

Tom

-Original Message-
From: Mike Alexander [mailto:m...@umich.edu] 
Sent: Monday, August 02, 2010 12:10 PM
To: Thomas Bullock; gnucash-devel@gnucash.org
Subject: Re: Patch update #2

--On August 2, 2010 11:18:07 AM -0400 Thomas Bullock  
wrote:

> Per Derek's suggestion that I send a weekly progress report:
>
>
> 1)  Using Christian's instruction about disclosing errors
> (xmllint -valid -noout gnucash-guide.xml), I found several errors.
>
> 2)  Am working on fixing my errors
>
> 3)  Also discovered that AppendixD of the guide has several
> errors.  The errors are in the original before I did anything.
>
> 4)  Errors reference the Data Type Definition (DTD) and I am
> trying to understand the specifics of that.  I may or may not be able
> to fix AppendixD errors.

I checked in a fix for the Appendix D errors a few days ago.  If you 
update your working copy you should get them.

Mike

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Patch update #2

[Thomas Bullock]

Per Derek's suggestion that I send a weekly progress report:


1)  Using Christian's instruction about disclosing errors (xmllint -valid 
-noout gnucash-guide.xml), I found several errors.

2)  Am working on fixing my errors

3)  Also discovered that AppendixD of the guide has several errors.  The 
errors are in the original before I did anything.

4)  Errors reference the Data Type Definition (DTD) and I am trying to 
understand the specifics of that.  I may or may not be able to fix AppendixD 
errors.

More later.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Will text be lost by over extending the right column boundary?

[Thomas Bullock]

Thanks, Christian, for your complete explanation.  Your comments are a great 
relief!  These will be added to my notes for new documentation patch writers.  
Now getting closer to a patch release.

Tom

-Original Message-
From: Christian Stimming [mailto:stimm...@tuhh.de] 
Sent: Thursday, July 29, 2010 3:19 AM
To: Thomas Bullock
Cc: gnucash-devel (gnucash-devel@gnucash.org)
Subject: Re: Will text be lost by over extending the right column boundary?

Zitat von Tom Bullock :
> My question is what latitude is there in paying attention to that  
> right boundary?  Will any characters being listed in columns 81 and  
> after be dropped?

No, none of the characters will be dropped. The line length (right  
column boundary) has effects only when viewing the XML file in the  
text editor, but it has no effects whatsoever on the result.

> If not, how much latitude is there in the system?  What do  
> experienced patch writers use?

The line length is only relevant for the convenience of editing in the  
text editor. Very long lines (i.e. much more than 80 characters) are  
inconvenient in several editors, so we suggest to avoid them. But this  
is only a suggestion and there is no enforcement in whatever direction.

As for patches: Patches are by definition line-based. This means very  
long lines (i.e. with much more than 80 characters) would make it  
inconvenient to spot the actual changes quickly. Say, only one single  
word changed, but the line is very long - then the concerned changes  
in the patch is a very long line in which one needs to look for the  
actual change if you want to proof-read it. This is easier if the  
lines are "not too long".

But again, line length is purely a suggestion and we have no  
hard-limit whatsoever in that area. You don't need to spend any more  
time on this issue. Just write your text in a form that is convenient  
to *you* and that's it. Thanks a lot for your contributions!

Regards,

Christian

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Documentation patching process

[Thomas Bullock]

Thanks for the encouragement.  I will attempt it when I have something that I 
know works.

Tom

-Original Message-
From: Tommy Trussell [mailto:tommy.truss...@gmail.com] 
Sent: Wednesday, July 28, 2010 2:21 PM
To: Thomas Bullock
Cc: gnucash-devel (gnucash-devel@gnucash.org)
Subject: Re: Documentation patching process

On Wed, Jul 28, 2010 at 6:50 AM, Thomas Bullock  wrote:
> <>
> P.S.: Whatever you decide to do I think an explicit procedure should
> go in the wiki and/or the source files so we can point people to it.
> <>
>
> When that is ready, I will need someone to put it on the appropriate wiki, 
> since I don't know anything about creating or modifying same.  If you want to 
> volunteer, I will be glad for your participation, but no pressure from me if 
> you cannot.

I will be happy to help when I can. The wiki is open to editing by
anyone so feel free to log in and make whatever changes you want. Wiki
markup is pretty straightforward. (I hesitate to say the wiki markup
is simpler than XML or vice versa... just different.)
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Documentation patching process

[Thomas Bullock]

Tommy,

Thanks for your thoughtful and researched reply.

Of the 3 options (bugzilla, html, patches-mail-list) you suggest, I have no 
experience with any.  So my reaction favors the bugzilla approach, since it 
seems to provide the most flexibility for reporting, tracking, and obtaining 
interested party comments.  Using that venue also provides the possibility of 
specifying a date for comments to be received by prior to developers having to 
decide to accept, defer, or reject.  If I visualize it properly it should offer 
a reliable, public way to find quickly and easily all pending patches for GC.

It also provides the possibility that those on the user list who don't 
subscribe to the developers' list could also participate in the review.  The 
eyes of newbies have a different perception than that of experienced users.

<>
P.S.: Whatever you decide to do I think an explicit procedure should
go in the wiki and/or the source files so we can point people to it.
<>

This idea has come up before and I want to affirm that as I go thru this 
step-by-step process, whatever ideas I get that clarify the process for me I 
plan to include in my description of how-to create a patch.  Basically, since I 
have never done this and am learning linux, xml, and other things as I proceed, 
it is taking me longer than someone who knows all this already.  For that 
reason my write-up will have both a verbose and a succinct statement; the first 
for a newcomer like me, the later for experienced persons who have already 
learned how to create a patch and need only a check list as a memory aid.

When that is ready, I will need someone to put it on the appropriate wiki, 
since I don't know anything about creating or modifying same.  If you want to 
volunteer, I will be glad for your participation, but no pressure from me if 
you cannot.

Thanks again.

Tom


-Original Message-
From: Tommy Trussell [mailto:tommy.truss...@gmail.com] 
Sent: Tuesday, July 27, 2010 7:40 PM
To: Thomas Bullock
Cc: gnucash-devel (gnucash-devel@gnucash.org)
Subject: Re: Confirming that no one else is working on Guide Documentation, 
Chapter 3

On Mon, Jul 26, 2010 at 11:27 AM, Thomas Bullock  wrote:
> Thanks for your offer to review drafts of documentation changes. What is the 
> customary way of
> Handling that?  I would not want to send a draft to the devel list, lest it 
> be confused as a patch.
> Or should that concern be handled by bold identification that the attached is 
> a draft and not
> A final proposed patch?

As far as customary goes, I am getting the idea that your predecessors
have experimented and improvised as they went along. I'm going to
suggest two options and you can pick and choose or suggest another
option. In a nutshell, I think you can

1) Create a patch and file it in bugzilla
   and/or
2) Publish an html version people can review

I just looked at
http://svn.gnucash.org/trac/browser/gnucash-docs/trunk/HACKING and of
the things it says I think the most careful way would be to create a
patch file (using diff) and file it as a documentation bug in
bugzilla.gnome.org. (Alternatively you could post the entire updated
file but a patch would make it clearer exactly where your changes
are.)

For example, once you revise a section then you could create a patch
against trunk in svn and post the patch as a documentation bug against
gnucash in bugzilla.gnome.org (identifying the particular patch as a
draft you want people to review).

If I want to review your patch I could copy the documentation trunk to
my local machine and download and apply the patch to the local files
and have a look. I can then make my comments to the bug in bugzilla.

I think there are some advantages to this procedure. There haven't
apparently been many documentation patches in bugzilla, but I found a
couple examples so you can see. For example
https://bugzilla.gnome.org/show_bug.cgi?id=568244 Note that you can
view the patch as a diff and see the exact changes in context. To me
that might make it worth the effort of creating the patch and the bug
report.

(The HACKING doc also suggests posting patches to the gnucash-patches
mailing list. I haven't subscribed to that list, however, and it seems
like bugzilla might have some advantages.)

Since you can alternatively output HTML as described in
http://svn.gnucash.org/trac/browser/gnucash-docs/trunk/README you
could post the draft to a public site (a free one such as google sites
or google docs would probably do) and invite comments by posting a
notice on the developer's list and include the url there and in the
bug report. I think the reviewers can most efficiently make their
comments in bugzilla.

P.S.: Whatever you decide to do I think an explicit procedure should
go in the wiki and/or the source files so we can point people to it.
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Confirming that no one else is working on Guide Documentation, Chapter 3

[Thomas Bullock]

Tommy,

No need to apologize.  Perhaps my word-smithing comes across as too abrupt.  If 
so,
I apologize to you.  My general approach is to ask questions when I see an 
opening,
Just to be sure I understand the writer's intention.  I definitely don't mean 
that to be taken
as a criticism!

I am very glad to have your follow-up thoughts and suggestions.  If you can 
find the 
one-way scripts again, it would be valuable to try them out to see how useful 
they would 
prove to be.

As to the wiki, I don't know how to work with them yet, so your experience is 
invaluable from
my perspective.

Thanks for your offer to review drafts of documentation changes. What is the 
customary way of 
Handling that?  I would not want to send a draft to the devel list, lest it be 
confused as a patch. 
Or should that concern be handled by bold identification that the attached is a 
draft and not
A final proposed patch?

Tom


-Original Message-
From: Tommy Trussell [mailto:tommy.truss...@gmail.com] 
Sent: Monday, July 26, 2010 11:55 AM
To: Thomas Bullock
Cc: gnucash-devel (gnucash-devel@gnucash.org)
Subject: Re: Confirming that no one else is working on Guide Documentation, 
Chapter 3

On Sun, Jul 25, 2010 at 3:10 PM, Tom Bullock  wrote:
>
> On 7/23/2010 5:47 PM, Tommy Trussell wrote:
>>
>> I am not working on that section
>
> Should I infer you are working on another part of the documentation?

I apologize for my wording -- so far all the work I have done has been
to several pages in the wiki. For example, after the storm of reports
messages in the past few weeks I have contributed some small things to
one new wiki page http://wiki.gnucash.org/wiki/Using_GnuCash

I hope that ultimately the information people contribute to that page
(like other information in the wiki) might be refined to the point
where it could go into the "canonical" documentation that gets
distributed with the documentation and gets managed in the svn
repository.

>> and I don't know the "official
>> answers,"
>
> Answers from whom can be taken as "official"?  a number of developers have
> stated they are currently on vacation.

Again, I apologize for my wording -- you are now the person in charge
of the documentation (at least the part you're working on) because you
are currently doing the (laudable and much-appreciated) work! Since
the (apparently failed as Derek confirmed) 2006 experiment using the
wiki for edits may not reflect the "canonical" documentation, I
suggest you might use information in the wiki to inform your work and
maybe document your ideas and procedures, but continue updating the
docbook source.

I did a few Google searches and found some scripts that might convert
docbook to wiki, and some OTHER scripts that might convert wiki to
docbook. However, because I know of no bidirectional conversion
utility, I would be leary of trusting either.

Since svn can publish the docbook source directly to the web, but the
wiki cannot reliably update the svn, using the wiki for reviews or
edits may be a mistake anyway. Maybe we should even consider deleting
the wiki pages holding the docbook drafts and instead publish links
directly to the docbook pages in svn. The wiki might continue be used
to collect suggestions or drafts on their way to docbook, but for that
purpose, regular clipboard cut-and-paste might be sufficient.

I have background working with documentation and hope to contribute
more eventually, but am not quite there yet, so I apologize for
muddying the waters. When you have sections you want others to review
I hope I can help you in that way.

Sorry for the noise.
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Confirming that no one else is working on Guide Documentation, Chapter 3

[Thomas Bullock]

Derek and all,

[<>: ]

I do not believe anyone is actively working on documentation.  I think
at this point you have announced your intention to work on documentation
(thank you) so just send email updates periodically (like, weekly?)
on your status.  Or better yet, send in the documentation updates
frequently, too.

[<>: ] 

OK, count this as weekly update #1:

Rather than do a massive overhaul at this point, I believe it important for me 
to get on top of the entire GC system.  So I am starting with what I know most 
about at this point: accounting concepts as they can be applied to current 
features of GC.

The issue that got me started was the user question about handling reimbursed 
expenses.  Trying to find where that fit in existing documentation I found the 
place to be in Chapter 3 where it deals with the catch-all category called 
"assets".  I have added reimbursed expenses and many other common uses of 
accounting with basic descriptions of how to record these items as a small 
business or a personal user.

While the content of the patch is ready for me to put into the patch process, I 
need to learn how to make that process work.  That is where my efforts are 
currently and will remain there until I understand the sequence of steps needed 
to make a proposed patch actually be accepted by the developers.  I mean by 
that: what I send in passes the tests developers need to use to verify that the 
proposed patch does not break the system.

Thanks to all for their patience and support while I climb the learning curve.  
I anticipate that once I have mastered the process for the first patch, 
subsequent ones should not be so time-consuming, at least not for the reasons 
the present one is.

[<>: ] 

>>   I
>> also discovered that in 2006 someone used the wiki to present/edit the
>> parts of the Concept Guide (and presumably started the page above,
>> too). See http://wiki.gnucash.org/wiki/Concept_Guide_draft/Overview
>> and the other linked text.
>>
>> The wiki might be a convenient way to get revision suggestions and
>> feedback,
>

At one point someone wanted to try to use the wiki for document editing,
but there's not a good way to take the wiki pages and turn it into
"real" documentation.  So that project sort-of died.

[<>: ] 

Based on what you disclose about these two pages, it seems like a good idea to 
take their 
Information and integrate it appropriately into future releases, that is, they 
are added to a
Documentation "to-do" list.



[<>: ] 
>> especially if you use an automated tool to convert the
>> sources between Docbook and wiki. I gather there are several
>

That's the problem -- there are not really good tools to do
bi-directional conversion.

[<>: ] 
Are there any separate tools that convert one-way:  wiki to DocBook?  And 
DocBook to wiki?


[<>: ] 
I believe the actual docbook docs are canonical (except for the FAQ).

[<>: ] By "canonical" do you mean the documentation that is downloaded 
from Subversion
Is the official documentation?
If so, are FAQs only kept on wikis?  If true, is that due to ease of access and 
adding answers to user questions on a timely basis?
Has it ever been the case that FAQs were tried in DocBook and failed for some 
reason?

> Tom

-derek

-- 
   Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
   Member, MIT Student Information Processing Board  (SIPB)
   URL: http://web.mit.edu/warlord/PP-ASEL-IA N1NWH
   warl...@mit.eduPGP key available
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: xml changed file validation

[Thomas Bullock]

John,

Thanks for the clarification.  I see the file now.  I will have to play with 
the process for awhile to be sure I have a clear sense of how it operates.  So 
I will be silent for a little until I can bring my concerns into focus.

Tom

-Original Message-
From: John Ralls [mailto:jra...@ceridwen.us] 
Sent: Monday, July 26, 2010 2:40 AM
To: Thomas Bullock
Cc: gnucash-devel Devel
Subject: Re: xml changed file validation


On Jul 25, 2010, at 10:30 PM, Tom Bullock wrote:

> John,
> 
> What you say makes sense.  Thanks for answering my question.  Now for another.
> 
> You answer assumes I know how to generate the file gnucash-guide.xml.  I 
> likely have read past it in the various documents available, but, sad to say, 
> as of now I don't recognize the command, script or process that generates 
> that file.
> 
> Can you point me to it?

You don't need to generate it: It's in the SVN repository, so you'll get it 
when you check out gnucash-docs. (It's at guide/C/gnucash-guide.xml). You 
needn't modify it unless you add a new chapter or appendix, though you may want 
to add yourself to the authors list and add a description of your revisions.

Regards,
John Ralls


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Version references in documentation

[Thomas Bullock]

Geert and others,

The discussion about version references in code for soon to be reached 2.4 
makes me realize I need to find out the conventional wisdom regarding version 
references in documentation.

Recent emails mentioned that the existing documentation is last current for 
version 1.8.  Current stable is 2.2.9 and soon to be 2.4 in the not distant 
future, it seems to me it would be useful to indicate the version number on at 
least the "how-to-use-feature" instructions.  Some present features are not 
even documented yet from remarks made in the user and developer's lists.

Has this idea been considered and rejected?  If so, can anyone share the 
reasoning behind that position?

Thanks.

Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Working on building a patch

[Thomas Bullock]

Thanks, Christian.  That additional information is good for me to know.

Since I last wrote I found that the errors are still present in the same 
modules.  Not surprising based on what you wrote below.  

Using your advice from a previous memo, I expect either (a) to fix the errors, 
or (b) to advise the developers of action taken to get around an unfixed 
problem.  This would be when I submit a patch for consideration.

I appreciate your support.

Tom

-Original Message-
From: Christian Stimming [mailto:stimm...@tuhh.de] 
Sent: Tuesday, July 13, 2010 3:34 AM
To: Thomas Bullock
Cc: gnucash-devel@gnucash.org; Derek Atkins
Subject: Re: Working on building a patch

Am Tuesday 13 July 2010 schrieb Tom Bullock:
> In the meantime, before seeing your advice, I did another svn checkout
> thinking that maybe something was corrupted in the interim and that a
> later checkout would not have the problem.  The only message I got is
> that I now have revision 19360.  Apparently, that revision overlaid
> revision 19355, which I was working with previously.  I have not had a
> chance to see if the error carried forward into 19360.
> 
> Do you agree that 19360 overlaid 19355 and I did not harm?  Or should I
> delete the entire folder and start over with whatever version is current
> when I get the old folder removed?

In SVN, the revision numbers are always strictly monotonically increasing, but 
they might have "gaps". That is, in the gnucash-docs/trunk directory there 
haven't been any changes between 19355 and 19360 (but elsewhere in the 
repository there have been changes). This means in terms of the gnucash-docs 
directory, the content corresponding to these two revision numbers is 
completely identical.

Also, when switching between different revision numbers, usually you don't 
accidentally "do any harm" in SVN. If the unlikely event of a source file 
conflict occurs, you will clearly get some messages about "Conflict". If those 
don't occur, no problem whatsoever occurred.

Regards,

Christian
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Working on building a patch

[Thomas Bullock]

I will try the text file route for the SAMPLE file.

To my knowledge I pulled everything.  The command I used was:

"svn checkout http://svn.gnucash.org/repo/gnucash-docs/trunk GC-docs"

I did not use the quotes shown above.

Do you think that revision 19355 was the proper one to use?  I am expecting 
that it was the most recent at least at the time I pulled the docs.  Would that 
be a correct expectation?

Tom 



-Original Message-
From: Derek Atkins [mailto:warl...@mit.edu] 
Sent: Monday, July 12, 2010 10:11 AM
To: Thomas Bullock
Cc: gnucash-devel (gnucash-devel@gnucash.org)
Subject: Re: Working on building a patch

Tom Bullock  writes:

> Hi,
>
> I am sending this to the developer's list because in building a patch,
> that when successful will be sent here, I encountered some problems
> that raised some questions for me.
>
> I was successful in using "svn" to copy gnucash-docs to my computer.
>
> Following your advice,  I focused on these two directories: GUIDE/C
> and HELP/C.
>
> 1.  In guide/C I found only this problem:
> Could not display
> "/home/tbullock/GC-docs/guide/C/gnc_Sample_QIF.qif".
> There is no application installed for Quicken Document Files.
>
> This really is not a problem with the Sample file, but a lack
> of appropriate software to access its content.
>
> Can you point me to the software needed to use the file?   I am
> concerned that without access to its content, I will likely miss or
> misunderstand something in the present documentation.

QIF is just a text file, so you can open it in any text file editor
(emacs, vi, etc).

> 2.  In help/C I found 3 XML parsing errors, though the specifics of
> the errors are unique to each file in which they appear.
>
> Example 1 for help/C:
> XML Parsing Error: undefined entity
> Location:
> file:///home/tbullock/GC-docs/help/C/Help_ch_Account-Actions.xml
> Line Number 219, Column 2: &chartacctseg;
> ^
>
> Example 2 for help/C:
> XML Parsing Error: undefined entity
> Location:
> file:///home/tbullock/GC-docs/help/C/Help_ch_Customize.xml
> Line Number 1416, Column 2: &txf-categories;
>^
>
> Example 3 for help/C:
> XML Parsing Error: junk after document element
> Location:
> file:///home/tbullock/GC-docs/help/C/Help_ch_GettingStarted.xml
> Line Number 139, Column 1:
>^
> The other files seem free of such errors.
>
> Not knowing XML, how do I get these corrected/removed?
> Should they be removed before proceeding with my patch?
> When I used SVN to place these files on my computer on Friday, July 9,
> I got no error messages.  The only message I got was that I had
> checked out "revision 19355".  Is that the version I should have
> checked out?
>
> Your guidance much appreciated.  If these are to be fixed and I do
> have the correct revision, then I could incorporate the fixes for
> those errors if someone tells me how to do it.

I'm afraid I don't know how to solve this, but I'd ask if you pulled out
ALL of gnucash-docs, or if you only pulled out pieces of it?  If you
only pulled out pieces then you might not have all the docbook
stylesheets required to build it.

> Tom

-derek

-- 
   Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
   Member, MIT Student Information Processing Board  (SIPB)
   URL: http://web.mit.edu/warlord/PP-ASEL-IA N1NWH
   warl...@mit.eduPGP key available
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Recommended C Compiler

[Thomas Bullock]

Thanks, Tom.  I appreciate your recommendation.  I guess I was anticipating 
some non-problems.  Your suggestion Helps

> >-Original Message-
> >From: Tom Browder [mailto:tom.brow...@gmail.com]
> >Sent: Sunday, August 09, 2009 6:05 PM
> >To: Thomas Bullock
> >Cc: gnucash-devel@gnucash.org
> >Subjct: Re: Recommended C Compiler
> >
> >On Sun, Aug 9, 2009 at 13:51, Tom Bullock wrote:
> >...
> >> If you agree, tell me the compiler and version web source you use,
> >so I can
> >> download from there.
> >
> >I can't speak for anyone else, but I suspect most folks who develop on
> >non-Windows use, as I do,  gcc (current release is version 4.4.1):
> >
> >  <http://gcc.gnu.org>
> >
> >Regards,
> >
> >-Tom
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: C Compiler Question

[Thomas Bullock]

Thanks, Christian!  Just what I was hoping to find out.  Much appreciated!

Tom

> >-Original Message-
> >From: Christian Stimming [mailto:stimm...@tuhh.de]
> >Sent: Sunday, May 24, 2009 9:00 AM
> >To: gnucash-devel@gnucash.org; Thomas Bullock
> >Subject: Re: C Compiler Question
> >
> >Am Sonntag, 24. Mai 2009 14:38 schrieb Tom Bullock:
> >> I don't have access to a C compiler at work.  So I want to download a
> >> free compiler at home.  Since currently all I run at home is Windows
> >XP,
> >> would I still be able to use the gcc compiler in that operating system,
> >
> >Yes. Gnucash on Windows compiles with gcc and there is a gcc on
> >Windows
> >available (in the "MinGW" package). Just follow the instructions on
> >http://wiki.gnucash.org/wiki/Windows and after the script there has
> >finished
> >you will have the free gcc compiler installed on your Windows XP as
> >well.
> >
> >Christian
> >
> >> or would I first have to set up a linux environment in order to use
> >that?
> >>
> >> If I had to use linux for gcc, what compiler should I use as long as I
> >> am using Windows XP?
> >>
> >> TIA.
> >>
> >> Tom
> >> ___
> >> gnucash-devel mailing list
> >> gnucash-devel@gnucash.org
> >> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel