uh oh. Thought some more.
In order to muddy the waters even further:
1) If one were to build a single ebook out of a single-file source, and doing it all the really hard way (hand-coding xhtml in notepad), the notion of having the ebook generation software create the table of contents for you is a handy thing - notepad don't do that.
If suggestions are ok, may I suggest that your built-in parsing routines simply indent the differing layers of headline calls:
This "should" make your built-in routines for creating a toc build something more reader-friendly, than
<h1>
<h1>
<h2>
<h1>
<h2>
and "shouldn't" be too far out of whack from the outline of the book.
Because I haven't done it this way, if I have multiple documents I intend to be combined into the book - what order do they appear in? The sort order they are in my source directory? Then each subdocument would have the same routine leveled against it, and again, the outline of the book "should" be presented in the toc.
I'm assuming you've seen this part of MobiCreator, where i can specify certain page-types (attached photo). This grants me a layer of control in mobi that I would want in Calibre - so I can use one app to create both outputs pretty much the same way.
Personally, outside of the toc (in mobi) I haven't had much need for those other book-document-types, but "real" pro might....
-bjc