Support for Velocity Macros

[ptahchiev]

Hey guys,

I have a feature-request, which I totally understand is a very long shot, but still it's nice to keep track of it. I'm building my documentation with asciidoctor maven plugin and I am also able to name my files with .vm extension to have custom velocity code inside of them. This way I can have foreach loops, variables, if statements, etc - it is really powerful. What would be a killer-feature would be to support velocity macros - something that doxia API already supports: https://maven.apache.org/doxia/macros/

The Parser implementations that come from doxia parse the content tag by tag, and basically every time the APTParser reaches a statement like this:

%{macro_name|param1=value1|param2=value2|...}

or the XhtmlParser reaches a statement like this:

<!-- MACRO{macro_name|param1=value1|param2=value2|...} -->

then they treat it as velocity macro and try to such a macro in the velocity template. I would really love to see this implemented for the AsciidoctorParser as well, because I have a lot of modules, and for each module I have common sections, like Configuration (a table with configuration properties), like RestTester (a widget that constructs request/response queries to show you how to use the REST API), etc. Unfrotunately I don't think this is possible at the moment, the way the AsciidocParser is designed. The parser basically calls the asciidoctor to transform the source into html, and then calls the doxia: sink.rawText(convertAsciiDoc(source, options));

Anyway, I would be really interested to see a what you guys think.

[abelsromero]

I am really glad to have this kind of conversations to expand the plugin beyond pure Asciidoctor. But you'll have to help me here because I have some doubts.

1. You mention Velocity macros, but I haven't been able any reference to it on the doxia documentation, also the velocity dependency is not in the classpath (org.apache.velocity:velocity:1.7). So, I am not sure we are talking about the same velocity stuff, i mean thishttp://velocity.apache.org/engine/1.7/vtl-reference.html, is that what you are talking about?
2. Checking the doxia macros, the only one not supported using Asciidoctor are ECHO and SWF. Are there any other that don't appear or I am missing something here also?

[ptahchiev]

Hi Abel, yes, http://velocity.apache.org/engine/1.7/vtl-reference.html is what I am talking about. Have a look at the Filtering section of the maven-site-plugin:

https://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html#filtering

Basically it says that when you name your documentation files like this index.adoc.vm (like I have done in my project) then you can have snippets like these:

#if ($FileUtils.fileExists("$project.getBasedir()/target/classes/META-INF/additional-spring-configuration-metadata.json"))
#set($jo = $class.inspect("org.json.JSONObject").getType().getConstructor($class.inspect("java.lang.String").getType()).newInstance($FileUtils.fileRead("$project.getBasedir()/target/classes/META-INF/additional-spring-configuration-metadata.json")))

[cols="<,<,<"]
|===
|Name|Type|Description

#foreach($prop in $jo.properties)
|$prop.name|$prop.type|#if($prop.has("description"))$prop.description#end
#end
|===
#end

This is a velocity code which checks if there's a spring-boot configuration metadata file:

http://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html

and if there is one, I parse it and produce the following table:

https://docs.nemesis.io/current-snapshot/platform/modules/nemesis-module-restservices/#configuration

Now, in my project I have more than 60 modules, and each one has this table, so I need to copy/paste the snippet from above in each of the 60 modules. I noticed that I can create a velocity macro in my site.vm file and then just reference this macro from the documentation:

https://maven.apache.org/doxia/macros/

Unfortunately the AsciidocParser does not respect the XHTML macro syntax:

<!-- MACRO{macro_name|param1=value1|param2=value2|...} -->

So hence this is what the issue is for :)

[abelsromero]

Ooook...the thing is being able to run velocity macros using the doxia syntax.

[mojavelinux]

Interesting. These would be preprocessor templates (which differ from our support for using output templates like Slim and Haml). We could tap into the existing Maven ecosystem to run this preprocessor. That seems reasonable to me. Dynamic AsciiDoc!

[michael-o]

Maven committer and Velocity committer here. While we do such a thing with Doxia, I'd be against doing this in this plugin manually because you mix concerns. This plugin is solely for converting Asciidoctor to X. You need to preprocess and supply fully working adoc files. Keep the codebase small and simple.

[sbordes]

Hi, Is there any progress on this topic ? Could we call some macro from adoc files like we can do with other format using one of these syntax:

• <!-- MACRO{macro_name|param1=value1|param2=value2|...} -->

• %{macro_name|param1=value1|param2=value2|...}

• xml

  <macro name="macro_name">
    <param name="param1" value="value1"/>
    <param name="param2" value="value2"/>
  </macro>

You can find below two samples using adoc and md, only the markdown version is able to interperet macros.

AsciiDoctor Version: https://raw.githubusercontent.com/JRebirth/JRebirth/8.x-dev/org.jrebirth.af/src/site/asciidoc/doc/Compone.adoc

Markdown Version: https://raw.githubusercontent.com/JRebirth/JRebirth/8.x-dev/org.jrebirth.af/src/site/markdown/doc/_Component.md

Thanks

[abelsromero]

Being completely honest here, no progress done and based on the last conversation, not in immediate roadmap. I am wondering is could be achieved running another plugin previous to the asciidoctor one.

[sbordes]

Thanks for the quick reply Keep up the good work

[mojavelinux]

Another option is to use an Asciidoctor extension.

I don't believe this plugin should be preprocessing the AsciiDoc source. The focus of this plugin is to convert AsciiDoc files using the normal, portable mechanisms. So I agree with Abel that it should be a separate step (or, as I proposed, an Asciidoctor extension).