add list of valid context names to findBy docs #1414
Conversation
|
@mojavelinux What do you think? Should we link to the documentation https://docs.asciidoctor.org/asciidoc/latest/blocks/#summary-of-built-in-contexts? It might be confusing since Asciidoctor is using keyword Thoughts? 🤔 |
|
Yes, I think we should link to the official list. As for the type (symbol or string) I think that can be clarified on both ends. I keep thinking to myself that that list should show strings, not symbols. Then we can explain elsewhere (such as in Asciidoctor) when a symbol is required. If you have suggestions for where to make those changes, I'm prepared to apply them. |
@mojavelinux Yes, that's a good idea. The implementation (Ruby) should state that context names should be passed as symbol. We could add a reference here: https://docs.asciidoctor.org/asciidoctor/latest/convert/templates/#backing-data-model Although, this information is also useful when developping an extension, for instance here: https://docs.asciidoctor.org/asciidoctor/latest/extensions/block-processor/ on_context :paragraphOr when using the Anyway, I think the "Backing data model" section is where we could introduce this concept.
|
|
I agree that when we're talking about the Ruby API, it should say there that the context must be passed as a symbol. We could also state on the Convertible Context page that whenever the context is used in the Ruby API, it must be a symbol, but AsciidoctorJ and Asciidoctor.js expect a string. |
There was a problem hiding this comment.
@StarfallProjects I left a comment and we should also update the documentation of findBy for the TypeScript types definition in:
asciidoctor.js/packages/core/types/index.d.ts
Line 2132 in 041e98e
Proposal: add a list of valid context names to the findBy docs. I've added all the names I've found so far. However, if this docs repo PR is accepted (asciidoctor/asciidoc-docs#90), it might be nicer to just add a link to the docs, rather than maintain the list in two places.
ggrossetie
force-pushed
the
StarfallProjects-findby-context
branch
from
2259c61
to
c207e31
Compare
Proposal: add a list of valid context names to the findBy docs. I've added all the names I've found so far. However, if this docs repo PR is accepted (asciidoctor/asciidoc-docs#90), it might be nicer to just add a link to the docs, rather than maintain the list in two places.