Explorer's log: Entering the maze

[Hendrik Boom]

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.

-- hendrik