add list of valid context names to findBy docs

[StarfallProjects]

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]

@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 :paragraph whereas Asciidoctor.js is using string...

Thoughts? 🤔

[mojavelinux]

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.

[ggrossetie]

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 :paragraph

Or when using the find_by method.

Anyway, I think the "Backing data model" section is where we could introduce this concept.
If we want to expand on that concept, we could talk about the following (related) methods:

• https://www.rubydoc.info/gems/asciidoctor/2.0.16/Asciidoctor/AbstractNode#context-instance_method
• https://www.rubydoc.info/gems/asciidoctor/2.0.16/Asciidoctor/AbstractBlock#find_by-instance_method
• https://www.rubydoc.info/gems/asciidoctor/2.0.16/Asciidoctor/Extensions/BlockProcessor (:contexts option)

[mojavelinux]

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.

[ggrossetie]

@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

findBy(selector: Selector | ((block: AbstractBlock) => boolean | string)): AbstractBlock[];