Document what contexts and content_model are available

[lordofthejars]

Document what contexts and content_model are available because when you are writing extensions (mostly block extensions) and you are creating new blocks, you need to set which context and content_model will be assigned to that block. In extensions example it is only explained the paragraph one with simple, but there are others like pass, verbatim, raw, ... so it would be great that at extensions chapter would be an explanation of all of them.

Currently I am developing some blocks that differs from the standard one, so I can help providing examples.

Alex.

[mojavelinux]

Here's the current list of content_model values:

• :compound - zero or more child blocks
• :simple - paragraph content
• :verbatim - literal content
• :raw - unprocessed content
• :skip - drop the content
• :empty - don't expect content (mostly relevant for macros)
• :attributes - parse as attributes (only relevant for macros)

Here's the current list of built-in structural containers (aka delimited blocks) that can support block extensions, named by their default context:

• :open - --
• :example - ====
• :sidebar - ****
• :literal - ....
• :listing - ----
• :quote - ____
• :pass - ++++
• :paragraph

Keep in mind that context names are unbounded. They merely instruct the processor which convert handler method to call.

[mojavelinux]

I'm going to create a tracking issue in the asciidoctor.org repository since currently that's where most of the documentation issues are filed.

[mojavelinux]

While the context and content model is part of the DOM, it also gets mirrored in Asciidoctor. So we may find that the list itself needs to be in the AsciiDoc docs component, but information how to access this information from the code (Ruby, Java, JavaScript) needs to be in the docs for the core processor.

[StarfallProjects]

Added two PRs for this:
#90
asciidoctor/asciidoctor.js#1414

I found this issue at the start of a frustrating afternoon trying to correctly retrieve all description lists, so in case my PRs are rejected and anyone else facing the same problem stumbles on this issue, here are the context names I found so far:

document
section
paragraph
dlist
ulist
olist
list_item
literal (a literal block)
listing (a listing block)
admonition
sidebar
example
open (open block)
pass (passthrough block)
table
thematic_break (horizontal rule)
page_break
image

Note that links have the context paragraph. To get all links in a document, use document.getLinks() with catalog_assets: true (you can also do this for images)

[mojavelinux]

You're absolutely right that these contexts need to be documented, which is why this issue exists. There are several layers here to unwind, though, so it's not quite as simple as providing a list of names. The docs will need to explain where these names come into the picture and how they relate to structural containers and content models. Given that I understand how it all related, I really need to prioritize writing this up.

[StarfallProjects]

In that case, I'd suggest regecting the PR to the docs. But perhaps the PR to the JS docs is ok - it's in enough context ('scuse the pun) to make sense (the findBy() function). And it would be a stop-gap for anyone else looking for the info before you can do more detailed docs.

[mojavelinux]

I will prioritize this, so I'd prefer if the PR to the Asciidoctor.js docs is held until I have completed the draft. At that time, I would like to ask you to volunteer to be a reviewer of the new information.

While I know it's important, we've gone 8 years without this information, so we can afford to be patient for a few more days/weeks.

[mojavelinux]

I have completely rewritten the documentation for blocks, carefully breaking it down into content models, contexts, styles, structural containers, delimited blocks, block masquerading, and nesting delimited blocks.

You can find the table of built-in contexts under the new Contexts section on the main blocks page.

[mojavelinux]

As a follow-up to this change, we need a page in the Asciidoctor documentation that lists all the built-in contexts that get mapped to handlers in the converter. This should be included on the page that documents how to write a converter. We should also consider all the built-in inline contexts here in the AsciiDoc Language documentation. (Although these things all seem the same, they are subtly different).