Document what contexts and content_model are available #57
Comments
|
Here's the current list of content_model values:
Here's the current list of built-in structural containers (aka delimited blocks) that can support block extensions, named by their default context:
Keep in mind that context names are unbounded. They merely instruct the processor which convert handler method to call. |
|
|
|
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. |
|
Added two PRs for this: 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 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) |
|
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. |
|
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. |
|
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. |
- thoroughly document content models, contexts, structural containers, block masquerading, and nesting delimited blocks
|
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. |
|
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). |
- thoroughly document content models, contexts, structural containers, block masquerading, and nesting delimited blocks
- thoroughly document content models, contexts, structural containers, block masquerading, and nesting delimited blocks - also resovles asciidoctor#7 move delimited blocks section to its own page - also resolves asciidoctor#94 pdate terminology for blocks
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.
The text was updated successfully, but these errors were encountered: