The design goal behind this text object is that the html should be entirely editable as normal text. This means that anchors and other entities should not be placed into the text as a real hyperlink object, because the user cannot then edit the link text in the same way as the body text. Instead, everything should go into the text normally, but use style wrappers to signify entities. We did try inserting iconview/text object pairs into the text at anchors, to allow the user to edit the variables, but the object within the text becomes too much of a barrier to normal editing: backspacing over the end of the link would trigger the "Really delete inset?" question, etc.
During a read, all text is compiled up into chunks, delimited by tags. This is done within ReadSubString which reads in lumps from the input stream and FindEntity which breaks into the previously mention chunks. Whenever an entity is noticed, it is pushed onto a stack. The stack thus holds the current set of environments during parsing. The push also creates an ATK text style to wrap around the environment at some point. When the end of the entity is found, closeEntity should be called which does the placing of the style into the text, followed by popEntity.
Lists are gross. The problem is that the list environments all imply inserted text whenever a list-item is found. For example, being inside an enumerated list implies that "li" should insert some text representing the current number'd paragraph. However, when writing the text back out to a file, these numbers should be again collapsed to mere assumptions. i.e. infile: <ol><li>hello<li>there</ol> should translate to:
while on screen, but should be written out in the same way as infile. What if user wants a particular ordering to their numbers? Have to use description list. Ick.
This is implemented by wrapping the "tag" of the paragraph (the number or bullet or whatever) in a style which has the "htmladornment" attribute attached to it. In the WriteSubString mess, whenever one of these is found, it goes into mute mode and streams along until it finds the end of the style.
The routine html_TagItem does the work of the tag style and suchlike. When the user hilights a region and requests it to be a list, this is called on each paragraph in turn. When a list is found during parsing, then hackery happens: closeEntity notices that it's a listItem which should be closed and then calls TagItem instead of just wrapping a style there.