You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Petar Tahchiev <pa...@gmail.com> on 2017/06/13 12:34:51 UTC
Doxia Macros
Hey guys,
reading at this: https://maven.apache.org/doxia/macros/
==========
Macros are currently only supported for APT, Xdoc and FML formats. Starting
with Doxia 1.7 (maven-site-plugin 3.5), macros are also supported for XHTML
and Markdown.
==========
As I'm writing my documentation on Asciidoc and I'm using the
https://github.com/asciidoctor/asciidoctor-maven-plugin
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?
--
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
Re: Doxia Macros
Posted by Petar Tahchiev <pa...@gmail.com>.
Hi Plamen,
thank you for your feedback. Indeed I had a look at the XHTMLParser last
night and it seems that the macro calls are called inside it, during the
parsing of the template. And yes, that makes it impossible for the asciidoc
plugin to use these macros, because, as you said the asciidoctor plugin is
"cheating" by delegating the parsing to Asciidoctor itself.
To answer your question, I think the AsciidocParser extends the XHTMLParser
because this way it can only overwrite a single method - the `parse` method.
Thanks, Petar.
2017-06-13 23:54 GMT+03:00 Plamen Totev <pl...@gmail.com>:
> 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 <pl...@gmail.com>
> 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 <
> plamen.iv.totev@gmail.com>
> > 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
> >>
> >
> >
>
--
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
Re: Doxia Macros
Posted by Plamen Totev <pl...@gmail.com>.
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 <pl...@gmail.com>
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 <pl...@gmail.com>
> 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
>>
>
>
Re: Doxia Macros
Posted by Plamen Totev <pl...@gmail.com>.
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 <pl...@gmail.com>
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-
> modules/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-
> core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java?view=
> markup#l129
> [3] http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-
> core/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
>
Re: Doxia Macros
Posted by Plamen Totev <pl...@gmail.com>.
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-modules/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-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java?view=markup#l129
[3] http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/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
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org