Re: [GNC-dev] Import Main Matcher

2019-09-02 Thread David Cousens
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

2019-08-16 Thread Frank H. Ellenberger
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

2019-08-16 Thread Frank H. Ellenberger
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

2019-08-16 Thread 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

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

2019-08-16 Thread Frank H. Ellenberger
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

2019-08-15 Thread 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. 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

2019-08-14 Thread Frank H. Ellenberger
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

2019-08-14 Thread 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



-
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

2019-08-14 Thread David Cousens
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

2019-08-14 Thread David Cousens
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

2019-08-13 Thread David T. via gnucash-devel
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 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

2019-08-13 Thread John Ralls



> 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 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

2019-08-13 Thread Frank H. Ellenberger
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