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 _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
