Explorer's log: Entering the maze

[John Ralls]

On Dec 3, 2011, at 12:08 PM, Hendrik Boom wrote:

> Thanks for all the help so far.  I now generate the users and doxygen 
> documentation, and have started exploring it.
> 
> The internal system documentation is a maze.  And unlike mazes printed in 
> puzzle books, there aren't clearly identified start and finish points :)
> Or, at least, I haven't found them yet. 
> 
> I'm going to try and keep a log of my adventures getting into the maze; 
> it may help later when I or someone else is writing or rewriting 
> documentation.  Should I send the log entries here?  Most will not be 
> cries for help, but they may serve as a guide for an author of a  
> StartReadingHere page or some such.  I hope my style here will be light 
> and engaging, but if it doesn't turn out that way, I can only apologize.
> 
> So far I've found gnucash/src/doc/html/index.html, which looks like a 
> start  page.  It contains lots of links, but has no notion of which links 
> are more or less important.  The first Doxygen overviews I went to were 
> Engine Framework and Engine Architecture.
> 
> Engine Framework is minimal, and doesn't seem to have anything to say 
> about an engine framework.  It does have an API link, and that's perhaps 
> the important part of that page.  Other than that, there's a mention of 
> additional API documentatino in src/doc/design/engine.texinfo, which , 
> rather helpfully, advises me not to read it as being hopeless obsolete.
> 
> The companion page, Engine Architecture, merely tells me it is becoming 
> obsolete, and, rather helpfully, recommends I "refer to the design 
> documentation in src/doc/design for a complete description of the Engine 
> architecture src/doc/design for a complete description of the Engine 
> architecture".  I do so, and discover that every file with content in 
> that directory is marked as hopelessly obsolete.
> 
> No, don't rush to delete them right away -- I think the history is 
> valuable.  They are plainly enough marked that they won't confuse anybody 
> as too the current state of affairs.
> 
> Now the API link I mentioned above (to file:///home/hendrik/dv/gnucash/
> workspace/gnucash/src/doc/html/group__Engine.html) *is* important, and 
> links to that kind of stuff is what should be on an API intro page, 
> together with short descriptions of what one can expect to find at the 
> end of each link. The group__*.html pages seem to organize the meat of 
> the API.
> 
> I'll start on such a page.  I'll leave it to later to decide whether it 
> should be assembled out of pieces by doxygen or written as a single 
> coherent piece of prose.  I'll have to have some content before 
> determining the form.

This should be interesting. ;-)

How about a wiki page on http://wiki.gnucash.org/wiki? Link it to the GnuCash page under Development.

If you haven't already, you might find it helpful to take a few minutes to skim over the Doxygen documentation. That will help you understand why the docs are structured the way they are.

Regards,
John Ralls