search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
322 stars 805 forks source link

Add block macro extension example to user manual #167

Open graphitefriction opened 10 years ago

graphitefriction commented 10 years ago

Add the example and explanations provided in Issue #734 to the extensions part of the user manual.

Also include path resolution utilities per @mojavelinux.

jaredmorgs commented 8 years ago

This goes into the http://asciidoctor.org/docs/user-manual/#extensions section as a new sub-section

At the end of this section, there is reference to https://github.com/asciidoctor/asciidoctor-extensions-lab

I wonder if the example extension should be added there instead of the guide? Or should we really be documenting the "best" example out of each extension lab group and then directing users to other examples in the extension lab?

mojavelinux commented 8 years ago

should we really be documenting the "best" example out of each extension lab group and then directing users to other examples in the extension lab?

Exactly. I like that strategy. And we can even use a remote include to pull in the source code from the extension lab so that we don't duplicate it. However, we will want to document that in the source file so that someone editing it knows it is being used. We could also link to a specific version of the file.

mojavelinux commented 8 years ago

The user manual does have a block macro processor example. See http://asciidoctor.org/docs/user-manual/#block-macro-processor-example. However, it doesn't explain how to insert a new block and specify which substitutions should be applied. So the focus should be on creating new AST nodes in an extension and inserting them into the tree. We should reference the API http://www.rubydoc.info/gems/asciidoctor/Asciidoctor/Block#initialize-instance_method