resolves #35 document paragraph in specification

This MR serves two purposes:

• provides the initial content for the paragraph element in the specification document
• shows the element structure and content guidelines proposed in #34

Comments regarding both the actual content regarding the paragraph as well as about the structure and language used in relation to the writing guidelines can be made on this MR or the related issues.

mentioned in issue #35 (closed)

mentioned in issue #34

Just an idea for terminology. When we're talking about the content model, I think we can say "simple". However, the adjective for the block should be either "leaf" or "terminal". I'm leaning more towards "terminal" since that is pretty universal understand to mean nothing else, in other words, no more child blocks. However, it does have child inlines, which is a characteristic of it being a block.

A verbatim block and a paragraph are both terminal/leaf blocks. However, they have different content models. A verbatim block doesn't run the inline parser to create the inlines children, whereas a paragraph does. That's just something to be aware of when selecting terminology.

One thing I might be getting hung up on here is "simple". I feel like if we called it "basic", it might be more understandable. After all, we describe a paragraph as a foundational building block of AsciiDoc, so "basic" seems to imply that it is the "base" of something. And I like that.

added 1 commit

• d866a034 - edit description section and clarify empty scenario

Compare with previous version

I haven't updated the content regarding the name of the content model/block yet, because I'm still thinking about it.

mentioned in issue #37 (closed)

I discovered something about interrupting lines while working on the grammar prototype. A list item (and specifically its list marker) cannot interrupt a paragraph, even if that paragraph is attached to a list item. Asciidoctor actually gets this wrong in that it allows the next list item to interrupt a paragraph attached to the previous list item. I think this is due to a parsing error.

A list item can, however, interrupt the list item principal.

Here's an example of when the next list item interrupts the list item principal:

* list
item
* another list item

Here's an example of when a paragraph should not be interrupted by a list item, even though the paragraph is inside a list:

* item
+
supporting text
* not the next list item

In the latter case, an empty line is required above the next list item. Otherwise, it gets consumed as the next line in the attache paragraph.

The reason for this clarification is that we don't want to make the parsing of a paragraph contextual. If a list item cannot interrupt a paragraph outside of a list, it should not be able to interrupt one inside of a list (i.e., a paragraph attached to a list item). If we allowed the latter case, then we'd also have to define which list items could interrupt an attached paragraph, and in which scenarios...and that just makes the syntax harder to describe.