Re: [GNC-dev] Import Main Matcher
Bob, Any feedback is welcome. John Ralls has suggested that the right place for documentation of how the code works is in Doxygen comments in the code itself and I agree with him there. There is a design document in the code which I may be able to add to. For the user documentmation I will be trying to restrict it to what the code does although I will try and add some info on things like the hard coded limits used for some parts of the search for matching transactions as that can be useful to users. Just crossreferencing information between the help manual and Tutorial guide may also prove useful (e.g. the preference settings for the import matcher crossreferenced from the help manual. Could you use please reply all so that your reply is also copied to the mailing list when replying to messages from the list David ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Import Main Matcher
BTW, in case you want to add also AqBanking Setup, you can find images in https://wiki.gnucash.org/wiki/Setting_up_OFXDirectConnect (en) and https://wiki.gnucash.org/wiki/De/Onlinebanking-Einrichtungsassistent for FinTS/HBCI in german. Am Fr., 16. Aug. 2019 um 09:33 Uhr schrieb David Cousens : : ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Import Main Matcher
Hi David, Am Fr., 16. Aug. 2019 um 09:33 Uhr schrieb David Cousens : > > Hi Frank, > > I created a stripped OFX import file from one of my bank accounts OFX files > and created an version with a few transactions edited and several deleted I > now have a series of screenshots of the import matcher after importing the > shortened file and then importing the full file so I can do a blow by blow > description of importing a file and matching it for the guide . I can do the > OFX and CSV sections and then the import matcher but I only have a small QIF > test file. I have shots of the register before during and after import. It > may be overkill so I'll see what it looks like Good work, but do we really need a full serie of all steps in all import formats? Or can we strip it down one serie with branches only, where significant differences appear? Keep in mind translators would have to redo them, too. > For the help manual I'll just put in a screenshot of each gui and explain > the buttons, check boxes and editing controls. OK > David ~Frank ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Import Main Matcher
Hi Frank, I created a stripped OFX import file from one of my bank accounts OFX files and created an version with a few transactions edited and several deleted I now have a series of screenshots of the import matcher after importing the shortened file and then importing the full file so I can do a blow by blow description of importing a file and matching it for the guide . I can do the OFX and CSV sections and then the import matcher but I only have a small QIF test file. I have shots of the register before during and after import. It may be overkill so I'll see what it looks like For the help manual I'll just put in a screenshot of each gui and explain the buttons, check boxes and editing controls. David - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Import Main Matcher
Hi, from help: >2.1.1. GnuCash Tutorial and Concepts Guide > >This guide is the counterpart to this help. It explains the concepts used in >GnuCash and has a tutorial that takes you through using GnuCash to manage your >accounts. and guide: >1.4.1. Context Help > > The context help provides detailed instructions for using GnuCash's menus, > windows, and controls. The mistake of mixing this happned IMHO in Bug 796855 - Bringing Chapter 3 of Help into Chapter 2 of Guide That mentions a discussion on devel, which is not linked there. IIRC there is a bunch of bugs, where none of use including me obeyed above classification. The duplication of the chapter happened in the following way: While Geert fixed the broken links of David T.s "move chapter", I applied your Bug 796856 - Help Ch6 section added for importing from files. When Geert applied David T.s & his work, your improvement disappered and in a quickfix - we were short before a release.- I reset the chapter to your version. So we got Help: old import chapter + David Cousen patches Guide: old import chapter + David T. patches Am Fr., 16. Aug. 2019 um 05:12 Uhr schrieb David Cousens : > > Frank, > > One difficulty I have is in separating the interface description from the > operational use of it in the case of the import matcher and the import > process generally. IMHO the textual putty between the GUI elements (if you press button A window B will appear...) still belongs into the manual. The Tutorial could go through an example session and the Guide could mention it describing, how to reach higher targets. > Geert did a good job of incorporating the essentials in > the popup help dialog in the interface and making it largely self > documented, that it becomes almost superfluous to describe the interface > separately, Yeah, funny thing to have this separate mini help. In theory one could move the whole help back into the code, but that would have other drawbacks. > but there are always those to whom the help button is invisible. > I will give it a go though. > > David Frank ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Import Main Matcher
Frank, One difficulty I have is in separating the interface description from the operational use of it in the case of the import matcher and the import process generally. Geert did a good job of incorporating the essentials in the popup help dialog in the interface and making it largely self documented, that it becomes almost superfluous to describe the interface separately, but there are always those to whom the help button is invisible. I will give it a go though. David - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Import Main Matcher
Dear Davids, Am Do., 15. Aug. 2019 um 03:07 Uhr schrieb David Cousens : > > David, > > I also agree that the guide is the most logical place to place most of the > detail for the Importing operations. > However the same information is currently largely duplicated in the > transaction operations section of the help manual including some recent > updates re the importer and matcher. This may have resulted from the > rearrangement you had in progress. I have recently updated some information > in the Help manual section not realizing the same section was also in the > guide. > > I would propose that we delete the section on importing in the help manual > transaction operations and simply replace it with a cross reference to the > Ch3 section on importing data in the guide and consolidate the current > information into the guide there. If everyone is happy with that I can > start that process. > > David Cousens IMHO the question is: What would you expect to see, if you press on [Help] in any dialog? That parts obvisious belong in Help, the rest can go to Guide. So your tabel about the import matcher states was long missing in Help. OTOH Sections about "How to migrate between Q* and GC", "Tips to import bank statements", "How to split a years book" for whatever purpose... could fill the data exchange chapter of the Guide. Regards Frank ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Import Main Matcher
David, I also agree that the guide is the most logical place to place most of the detail for the Importing operations. However the same information is currently largely duplicated in the transaction operations section of the help manual including some recent updates re the importer and matcher. This may have resulted from the rearrangement you had in progress. I have recently updated some information in the Help manual section not realizing the same section was also in the guide. I would propose that we delete the section on importing in the help manual transaction operations and simply replace it with a cross reference to the Ch3 section on importing data in the guide and consolidate the current information into the guide there. If everyone is happy with that I can start that process. David Cousens - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Import Main Matcher
Frank, I might also have to look at the recent additions to the Help manual and see if they are not better in the guide rather than the help manual. David T pointed me to the right place in the guide in another post. Agreed on the wiki. In addition to the information which might be useful to users, I have mapped out some the code linkages between the backend and the gui (currently in flow charts in YeD) which may be more useful to those new to the code. As John suggested I wil try and incorporate some of that in Doxygen comments in the code. David - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Import Main Matcher
Hi John, Point taken on the documenting the how in the code and what it does in the docs. I have a slight familiarity with Doxygen but no great expertise but there is one way to change that. I'll ty and keep any Help and Tutorial description as general as I can while trying to provide something that will be useful to a user. David T has suggested Ch3 of the Tutorial and Concepts Guide as a possible home. David - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Import Main Matcher
To echo one part of John's comment, I recommend that any description of this process belongs in the Guide, and not the Help or on the wiki. Since chapter 3 of the Guide is called "Importing into Gnucash," I would probably suggest to put it there. David T. On Wed, Aug 14, 2019 at 8:56, John Ralls wrote: > On Aug 13, 2019, at 6:25 PM, David Cousens wrote: > > At present the transaction importing documentation in the Help manual has no > full description of how the import main matcher goes about the process of > searching for and matching an imported transaction to an existing > transaction or how it assigns a transfer account using the original mapping > process or the more recent Bayesian approach. > > I am in the process of going through the code at present for my own > edification and could create an expanded description of these processes in > their current state either for inclusion in the Help manual or as a Wiki > page. My concern is that a detailed explanantion in the importing > transaction section of the help manual may make that section too long > winded. If that is not a significant issue, that would be my personal > preference. > > Does anyone have any strong preferences as to which is the better option ? I'd rather not document internals in the T&CG. Implementation details aren't something that users need to worry about, so document there what it does, but not how. How belongs in comments in the code. Exported functions should have Doxygen-formatted comments so that they add to the API documentation (https://code.gnucash.org/docs/MAINT), local functions may also have non-Doxygen comments. Beware that a lot of our code follows the Gnome dispatch model where a static function is exported via a hand-written vtable, usually placed near the bottom of the source file. Those functions are really public and rate Doxygen documentation. Bigger-picture documentation of a module's design also belongs in Doxygen-formatted comments. If you're not familiar with Doxygen see http://www.doxygen.nl/. Regards, John Ralls ___ 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: [GNC-dev] Import Main Matcher
> On Aug 13, 2019, at 6:25 PM, David Cousens wrote: > > At present the transaction importing documentation in the Help manual has no > full description of how the import main matcher goes about the process of > searching for and matching an imported transaction to an existing > transaction or how it assigns a transfer account using the original mapping > process or the more recent Bayesian approach. > > I am in the process of going through the code at present for my own > edification and could create an expanded description of these processes in > their current state either for inclusion in the Help manual or as a Wiki > page. My concern is that a detailed explanantion in the importing > transaction section of the help manual may make that section too long > winded. If that is not a significant issue, that would be my personal > preference. > > Does anyone have any strong preferences as to which is the better option ? I'd rather not document internals in the T&CG. Implementation details aren't something that users need to worry about, so document there what it does, but not how. How belongs in comments in the code. Exported functions should have Doxygen-formatted comments so that they add to the API documentation (https://code.gnucash.org/docs/MAINT), local functions may also have non-Doxygen comments. Beware that a lot of our code follows the Gnome dispatch model where a static function is exported via a hand-written vtable, usually placed near the bottom of the source file. Those functions are really public and rate Doxygen documentation. Bigger-picture documentation of a module's design also belongs in Doxygen-formatted comments. If you're not familiar with Doxygen see http://www.doxygen.nl/. Regards, John Ralls ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Import Main Matcher
Hi David, Am Mi., 14. Aug. 2019 um 03:26 Uhr schrieb David Cousens : > > At present the transaction importing documentation in the Help manual has no > full description of how the import main matcher goes about the process of > searching for and matching an imported transaction to an existing > transaction or how it assigns a transfer account using the original mapping > process or the more recent Bayesian approach. > > I am in the process of going through the code at present for my own > edification and could create an expanded description of these processes in > their current state either for inclusion in the Help manual or as a Wiki > page. My concern is that a detailed explanantion in the importing > transaction section of the help manual may make that section too long > winded. If that is not a significant issue, that would be my personal > preference. > > Does anyone have any strong preferences as to which is the better option ? Your Docbook knowledge is sufficient to write directly for the Manual. And you are smart enought to see that "The best way to migrate data from XYZ to Gnucash" would belong into the Guide. I fear if you put it at first in the wiki, it will stay there for years. ~Frank > David Cousens ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
