Oddbean

Find it a bit confusing that the indices are sections and the sections are blocks, and the nodes can be indices or sections, which means that they can be sections or blocks, and the commentary and function "zettel", but they aren't called zettel in the function. Clashes too much with the domain, as described in NKBIP-1 and in my Uploader. Can we maybe agree on one naming convention and write it into the spec? Also problematic because only 30041 are zettel, so adding more kinds would make it even more confusing because you'd be referring to wiki pages as "zettel".

Okay, it's all a bit fuzzy. The spec assumes 30040 is always an article and each linked element is a section of the article. But we also allowed for 30040 to be a book and each linked element is then a chapter. And we allowed for 30040 to be a collection and each linked element is then an article, in it's own right. I made a 30040 that was an audiobook list and each 30041 contained an audiobook episode. I actually prefer 30040 index and 30041 section, as we don't presume to know the content of the events, we're just describing what the "do": one contains a list of events, the other contains a portion of the content.

Yeah, bit fuzzy but that's why in some earlier conversations i made analogues to 30040s being some type of container event. They also got inspiration from lists and how you can have a top level note with other comments chained under it. Containers can hold other containers, but collectively the pairing of 30040s with a sequence of various events constructs a modular article, not that 30040s are the modular article event.

Recording here what we discussed in Slack: - 'Zettel' is the term we're using specifically for kind 30041 events. They are intended to be bite-sized notes. - 'Index' is the term we're using for kind 30040 events. - 'Event' is the generic term. Wiki entries, long-form articles, indices, and zettels are all 'events.' If we don't have a specific term for an event kind in a given instance, we'll call it an 'event.' Terms like 'node,' 'block,' and 'section' are specific to Asciidoctor. I can add details in the code comments explaining how we are using different terms throughout the parser logic.

I'm having a hard time figuring out by the question. Are you asking what happens if the first index event doesn't have any child events? In general, each paragraph will become its own kind 30041 zettel, so if there are no subsections, the document will be turned into a single index with a bunch of one-paragraph zettels. Does that answer your question, or did I just misunderstand it?

What if it's only "Document metadata === This is a header" And then it ends. Maybe because someone copy-pasted wrong or pushed the button too early. Or maybe they just want to create an index and update it later, with the relevant e tags. Then it would only generate a 30040, right? Or would it return an error? Or would they need to confirm that it should only generate a 30040?

It will parse the document down to 5 levels of nested sections (`===== Section`). Currently, any sections deeper than that will be lumped into the content of the kind 30041 events generated from fifth-level blocks. In theory, we can go arbitrarily deep, but at a certain point, we don't need that much depth in an editor workflow that is driven by direct user input (versus a programmatic upload of something large and complex, like the Bible). Setting a cutoff makes things a bit easier for both us and, IMO, for the end user.