Re: Doxia Macros

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Doxia Macros

Plamen Totev-2
And one last thing - `AsciidoctorParser` actually extends
`org.apache.maven.doxia.module.xhtml.XhtmlParser` but I don't think it
delegates the parsing to it in any way. It's strange why it extends it
then. Maybe I'm missing something.

On Tue, Jun 13, 2017 at 11:49 PM, Plamen Totev <[hidden email]>
wrote:

> Hmm, now that I took a quick look at the `AsciidoctorParser` it looks like
> what I've said does not apply for the Asciidoctor Maven Plugin.
>
> `AsciidoctorParser` is actually cheating a bit - it does not use the
> `Sink` API. It just parses the AsciiDoc content and dumps it as raw text
> [1]. One way to enable the macros is to use the same strategy as the
> `MarkdownParser` [2]. it just converts the Markdown to HTML and then uses
> modified version of the Doxia `XhtmlParser` [3] to actually parse the
> content. This way you'll get the macros for free given the output from the
> AsciiDoc could contain HTML comments like this one:
>
> ```
> <!-- MACRO{macro_name|param1=value1|param2=value2|...} -->
> ```
>
> [1] https://github.com/asciidoctor/asciidoctor-maven-
> plugin/blob/master/src/main/java/org/asciidoctor/maven/
> site/AsciidoctorParser.java#L84
> [2] http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-
> modules/doxia-module-markdown/src/main/java/org/apache/
> maven/doxia/module/markdown/MarkdownParser.java?view=markup#l109
> [3] http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-
> modules/doxia-module-markdown/src/main/java/org/apache/
> maven/doxia/module/markdown/MarkdownParser.java?view=markup#l250
>
> On Tue, Jun 13, 2017 at 11:26 PM, Plamen Totev <[hidden email]>
> wrote:
>
>> Hi,
>>
>> I have limited understanding on the matter and what I going to say may
>> not be 100% correct, but I hope it will help you to get started.
>>
>> > I'd like to work on supporting macros for the asciidoctor-maven-plugin.
>> Any
>> > idea on what to look at? What defines whether a macro is supported or
>> not?
>> `
>> The ATP parser is good location to start looking at.
>> AptParser.MacroBlock[1] handles the macros for the APT format. I don't
>> think there is a flag that indicates if given `Parser` supports macros
>> or not. It's up to the `Parser` implementation to parse the macro
>> parameters and to execute the macro. So it's up to you to extract the
>> macro id (name) and the params for it from the Asciidoc text.
>>
>> `AbstractParser#executeMacro(String macroId, MacroRequest request,
>> Sink sink)` [2]  will execute the macro on the given sink. So
>> essentially you only need to create a  MacroRequest instance and pass
>> it to the `executeMacro` method together with the macro id and the
>> sink. The MacroRequest constructor [3] takes four parameters:
>>
>> * String sourceContent - this is the original content
>> * AbstractParser parser - a parser that could parse the sourceContent
>> * Map<String, Object> param - params for the macro
>> * File base - the current base directory
>>
>> Some of the macros (such as Table of content for example) need to
>> parse the content again. That is why you have to pass `sourceContent`
>> and `parser`. Just be careful to avoid infinite recursion. There is
>> `AbstractParser#isSecondParsing` flag that can help you with that.
>> Make sure you're not executing any macros on the second parsing (or at
>> least that is what the APT parser is doing, Maybe there is a better
>> way to avoid infinite recursion or similar problems, but this should
>> do I think).
>>
>> Hope this helps you.
>>
>> Regards,
>> Plamen Totev
>>
>> [1] http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-m
>> odules/doxia-module-apt/src/main/java/org/apache/maven/doxia
>> /module/apt/AptParser.java?view=markup#l2871
>> [2] http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-c
>> ore/src/main/java/org/apache/maven/doxia/parser/AbstractPars
>> er.java?view=markup#l129
>> [3] http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-c
>> ore/src/main/java/org/apache/maven/doxia/macro/MacroRequest.
>> java?view=markup#l60
>>
>>
>> >
>> > --
>> > Regards, Petar!
>> > Karlovo, Bulgaria.
>> > ---
>> > Public PGP Key at:
>> > http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x19658550C3110611
>> > Key Fingerprint: A369 A7EE 61BC 93A3 CDFF  55A5 1965 8550 C311 0611
>>
>
>
Loading...