Please remove my name as documentation support
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
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 tbull...@nd.edu 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 is or should be the element that is accorded 'transaction' programming treatment? Is it strictly an accident of user perception, that is, whatever the GC user types in first? I'm not sure what you mean by prime element here. Could you explain what you mean? Within the application both Transaction and Split objects are first-class objects, but in reality you cannot have a Split without a Transaction. Basically, a Split encodes a single debit or credit into/outof an Account. A Transaction is a binding of a set of Splits into a single, umm, transaction. In a balanced transaction, the Splits sum to zero. My use of the term 'prime element' was my way of getting
RE: Terminology Clarification requested
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: gnc:transaction version=2.0.0 trn:id type=guid503db7a77e6b2e228708ace1e45a2748/trn:id trn:currency cmdty:spaceISO4217/cmdty:space cmdty:idUSD/cmdty:id /trn:currency trn:date-posted ts:date2002-03-14 16:00:00 -0800/ts:date /trn:date-posted trn:date-entered ts:date2003-01-04 05:13:42 -0800/ts:date /trn:date-entered trn:descriptionReceived from American Founders Life/trn:description trn:splits trn:split split:id type=guida81924b4c323bdf92626218cf987b68c/split:id split:reconciled-statey/split:reconciled-state split:reconcile-date ts:date2002-09-29 00:11:00 -0700/ts:date /split:reconcile-date split:value614311/100/split:value split:quantity614311/100/split:quantity split:account type=guid73cbee4da2acb9183e83ff639d615ffe/split:account /trn:split trn:split split:id type=guid49ab4796dc37c852923cf118c6b457ac/split:id split:reconciled-staten/split:reconciled-state split:value-614311/100/split:value split:quantity-614311/100/split:quantity split:account type=guid17b67fb50b4b228f9c2442a6debc271f/split:account /trn:split /trn:splits /gnc:transaction Regards, John Ralls ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
RE: Terminology Clarification requested
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 jra...@ceridwen.us Subject: Re: close books To: Derek Atkins warl...@mit.edu Cc: devel gnucash gnucash-devel@gnucash.org 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 program, which are mostly equivalent to the accounting terminology. Yes, I understood exactly that you were talking as programmers but had not incorporated the data structure concept. 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
Terminology Clarification requested
Hi, Using this excerpt as a context: Message: 1 Date: Tue, 7 Dec 2010 09:33:58 -0800 From: John Ralls jra...@ceridwen.us Subject: Re: close books To: Derek Atkins warl...@mit.edu Cc: devel gnucash gnucash-devel@gnucash.org 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
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:your-bugzilla-account 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
Hi Geert, Yes, you can do so with a little bugzilla foo. To start: type cc:your-bugzilla-account 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
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
Hi Geert, Yes, you can do so with a little bugzilla foo. To start: type cc:your-bugzilla-account 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 cc:tbullock, 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 cc:tbull...@nd.edu. 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
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:your-bugzilla-account 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
RE: Bug 632594 created; review, approval, commit requested
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
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 (xref 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
Is this bug list possible
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
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 631789 update
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: Wiki Page Formatting
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
RE: Wiki Page Formatting
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: Bug 631789 update
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: Bug 631789 update
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=GnuCashbug_status=UNCO NFIRMEDbug_status=NEWbug_status=ASSIGNEDbug_status=REOPENEDcompone 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 632594 created; review, approval, commit requested
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: Removing duplications between Guide Help
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
Unexpected XML errors found
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: Unexpected XML errors found
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 application. 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 application markup For exmple: orgnameapplicationapp;/application Documentation Team/orgname is not allowed The right markup is: orgnameapp; Documentation Team/orgname 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
Wiki Page Formatting
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
Bug 632594 created; review, approval, commit requested
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
What is the 2.5 branch?
Hi Herbert, snip 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
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 pre.../pre (I also removed the quotes, they don't add value anymore with the pre.../pre 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
RE: GC Concept Guide Review and Wiki Pages
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
Removing duplications between Guide Help
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
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 janssens-ge...@telenet.bemailto:janssens-ge...@telenet.be Subject: Re: Concept guide review To: gnucash-devel@gnucash.orgmailto:gnucash-devel@gnucash.org Message-ID: 201010131527.41506.janssens-ge...@telenet.bemailto: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: GC Concept Guide Review
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 and Wiki Pages
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: A Start for 2.4 Documentation
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 [Tom:] 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: A Start for 2.4 Documentation
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. [Tom:] 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? [Tom:] 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
GC Concept Guide Review
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 janssens-ge...@telenet.bemailto:janssens-ge...@telenet.be Subject: Re: Concept guide review To: gnucash-devel@gnucash.orgmailto:gnucash-devel@gnucash.org Message-ID: 201010131527.41506.janssens-ge...@telenet.bemailto: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
A Start for 2.4 Documentation
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
RE: GC Concept Guide Review
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 janssens-ge...@telenet.bemailto:janssens-ge...@telenet.be Subject: Re: Concept guide review To: gnucash-devel@gnucash.orgmailto:gnucash-devel@gnucash.org Message-ID: 201010131527.41506.janssens-ge...@telenet.bemailto: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, otherwise called a bug. In this usage bug means a statement of what is changing and why along with the content that will be the change when
RE: FW: [Bug 630652] Expanding and adding GnuCash Other Assets
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 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
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 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 ___ 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
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
FW: [Bug 630652] Expanding and adding GnuCash Other Assets
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 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
RE: Documentation for the 2.4 release
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
Documentation for the 2.4 release
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
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, quoteI don't believe you./quote 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
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
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: snip 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 (Modified) or D (Deleted) will be taken into account. If you see files in the list that you know have changes you want to include, but that are not in this state, you should deal with this first. - Newly created files (the ones in state ?) you wish to include in the patch should first be added via svn add - Files you removed with a plain rm command (the ones in state !) should be properly removed via svn rm 5. Now to create your patch, simply run svn diff changes.patch Note that the svn diff
RE: Documentation Bug 630652 created to install Guide update for Other Assets
-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 [Tom:] 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: rsquo;, dash;, and quote.../quote 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: Questions re Documentation in Bugzilla
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
RE: Unexpected results in attempting a patch
-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 [Tom:] 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: Unexpected results in attempting a patch
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 xref linkend tag to work! Proof was that there were no 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
Gource Representation
Date: Wed, 8 Sep 2010 21:19:25 +0200 From: Geert Janssens janssens-ge...@telenet.be Subject: Development visualization with gource To: gnucash-u...@gnucash.org 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 SNIP 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
Status on work toward a patch
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
Monday, August 16, 2010 5:10 PM: John Ralls [mailto:jra...@ceridwen.us] wrote [Tom: ] 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 tip and note elements can't be direct children of sect1 after the first refentry, sect2, or simplesect 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 [Tom: ] 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
Best location to place interim Guide information
Derek Atkins [warl...@mit.edu] writes: snip Why not use http://wiki.gnucash.org/wiki/ ??? /snip 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
RE: First look at Guide update
H. Ellenberger [mailto:f.ellenber...@online.de]mailto:[mailto:f.ellenber...@online.de] writes: snip 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./para /listitem - '''BEGIN NEW CONTENT HERE!!''' + !-- '''BEGIN NEW CONTENT HERE!!''' -- listitem paraguilabelOther Assets/guilabel No matter how diverse they are, GnuCash handles all the following situations easily. The group @@ -590,7 +590,7 @@ /listitem /orderedlist /sect2 - '''SIGNIFICANT NEW CONTENT ENDS HERE''' + !-- '''SIGNIFICANT NEW CONTENT ENDS HERE'''-- tip paraFor all GnuCash asset accounts, a emphasisdebit/emphasis There seems to be more, but this is a first step. [Tom: ] 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? [Tom: ] snip 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. [Tom: ] 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 [Tom: ] 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
RE: Best location to place interim Guide information
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. [Tom: ] 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. [Tom: ] 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. [Tom: ] 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: Best location to place interim Guide information
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: snip Why not use http://wiki.gnucash.org/wiki/ ??? /snip 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
Draft content now in new location
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: First look at Guide update
John Ralls [mailto:jra...@ceridwen.us]mailto:[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. [Tom: ] 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.) [Tom: ] 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. [Tom: ] 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. [Tom: ] Sounds like very good advice. In fact, maybe the first small patch won't have the present xml validation complaint! Regards, John Ralls [Tom: ] 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
RE: First look at Guide update
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 tip and note elements to the top level; they should have remained in the sect2 elements that they were in originally. In every case, the /sect2 tag needs to be moved from just above to just below the offending elements, after which xmllint passes. Regards, John Ralls [Tom: ] 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: Output from xmllint: your help needed!
snip 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 /snip 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
Guide Documentation Patch #1 - Update #3
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: Manual and Guide Versions in the documentation
snip 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). /snip Excellent!! Thanks, David. Tom ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
RE: Documentation Processing Ideas
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: [Tom: ] 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 final solution? I would agree. Let me put it this way: GnuCash is a volunteer project. I think any positive contribution is welcomed. From my point of view, any documentation that gets added is a positive
RE: Documentation Processing Ideas
Snip 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 /Snip [Tom: ] 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: Manual and Guide Versions in the documentation
snip 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 /snip 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 tbull...@nd.edu wrote: From: Tom Bullock tbull...@nd.edu Subject: Manual and Guide Versions in the documentation To: John Ralls jra...@ceridwen.us Cc: gnucash-devel gnucash gnucash-devel@gnucash.org Date: Tuesday, August 3, 2010, 2:23 PM snip Message: 8 Date: Mon, 2 Aug 2010 12:50:20 -0700 From: John Ralls jra...@ceridwen.us 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 /snip 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
Patch update #2
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: Patch update #2
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 tbull...@nd.edu 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
RE: Will text be lost by over extending the right column boundary?
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 tbull...@nd.edu: 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
Documentation patching process
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. snip 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. /snip 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 tbull...@nd.edu 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: Documentation patching process
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 tbull...@nd.edu wrote: snip 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. /snip 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
RE: xml changed file validation
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
RE: Confirming that no one else is working on Guide Documentation, Chapter 3
Derek and all, [snip: ] 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. [Tom: ] 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. [snip: ] 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. [Tom: ] 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. [snip: ] 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. [Tom: ] Are there any separate tools that convert one-way: wiki to DocBook? And DocBook to wiki? [snip: ] I believe the actual docbook docs are canonical (except for the FAQ). [Tom: ] 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: Confirming that no one else is working on Guide Documentation, Chapter 3
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 tbull...@nd.edu 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
Version references in documentation
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
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
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 tbull...@nd.edu 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:chapter id=getting-started ^ 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
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 Bullocktbull...@nd.edu 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
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
