Design Log
(Historical Decision Record)

Use "hard-coded" addNode operations in StructureNode

• Lists must be factory for nodes to ensure node is initialized with proper parent. By same token, StructureNode must be factory for lists, for same reason. But if StructureNode is a factory for lists, it must either:
  1. Define all possible addNode operations in StructureNode, so the appropriate list can be created (then create the list if it doesn't exist and delegate the node create to the list).
     -- That means the possible list types are fixed, rather than extensible.
     or
  2. Define a generic addNode operation in StructureNode that uses a select statement or if-else processing to determine which list to delegate to.
     --That's inefficient and non-polymorphic.
     or
  3. Define a generic addNode operation that uses reflection to determine the name of the list to check and the class name used to create it.
     
     Note:
     One ContentList is needed under the StructureNode. Other ContentLists are needed under InlineNodes. InlineNode therefore needs a non-generic addNode operation, so that only ContentLists are created. If a generic operation is used for StructureNodes, the APIs are then inconsistent, and therefore less easy to use.
     

     Node	Sublists
     StructureNode	StructureList ContentList CategoryList ???? AttributeList ?????
     InlineNode	ContentList
     LinkNode	CategoryList ??? (restricted to particular categories) --any value?? or does the existing simple LinkType mechanism suffice??

• Decision:
  Make the API consistent. There may be value in adding a generic, reflection-based list-creation mechanism.

Don't Distinguish Original Parent from Other Parents

When a node is created, its parent is set. When a StructureLink is created, a ReferenceList (rather than parent list) could be created.

• Motivation: To distinguish original parent from referenced uses, to identify book or article, for example.
   
• Valid?? What about reuse of a node by the same author in multiple documents? No way to distinguish which document is the "real" document being referenced, in that case. Any one reference is artificial. It may be the first thing it was defined *in*, but when people get used to a system like this, they well undoubtedly design a node for multiple uses (an article, a book, an online document) at the outset. So this reason is insufficient.
   
•   No other good reasons identified.

Every StructureNode is embedded in a StructureLink

• All node references are then treated the same.
• Author can apply relationship categories to newly written nodes, as well as to references, if desired.
• Note:
  It's not totally clear the functionality is needed. There is a performance/space cost, as well. But consistency generally pays off down the road, and the programming of the outer system will be more regular (and therefore easier), so odds are that this a good decision.

No AttributeNodes or AttributeLists defined in the kernel

It seemed to make sense to have them, at first. The idea was to have a (display)LIST type, with attributes to specify it as ORDERED or UNORDERED. The idea would be that "attributes" are context-dependent features (what kind of ordering to use), while nodes are more fundamental, logical entities. Changing one would therefore be an add and a remove, instead of an attribute change. However, it appears to make more sense to define ORDERED_LIST and UNORDERED_LIST, rather than having attributes to do the job.

• Q1: How many attributes are there that make any sense? (Note that HTML has UL and OL, rather than attributes of a list type)
• Q2: Should attributes be handled by the category mechanism?
  • The user system could predefine category groups like System: that were usually not displayed (i.e. invisible). Of course, the choice of categories would have to match the node name, so System:List:Ordered and System:List:Unordered would be attributes-as-categories for lists.
  • ADVANTAGE: If the krnl allowed changing OL to UL as an attribute, then the user system would be unable to store format attributes, since they would not make sense after the underlying structure changed. But does it make sense to store format info, if it is context dependent?
  • ADVANTAGE: Simplifies the KRNL if attribute nodes go away.
• HTML Structure Tags
  • <h1>...<h5>
  • <p>
  • <ul>, <ol>, <li>
  • <table>, <th>, <tr>, <td>
  • <dl>, <dt>, <dd> (not needed. The display mechanism just needs to indent <p> within <p>)
• HTML Content Tags
  • <b>, <i>, <tt> == inline nodes
  • <br> == \n in the text (when authoring, [Enter] starts a new node, [sh+Enter] becomes NL)
  • <font> == addl inline nodes defined by the user system
  • <a name="...">, <a href="..."> == link nodes and node ptrs (node IDs when transmitting