Custom tags definition

[Arteneko]

Is there a way to integrate custom tag definitions inside the parser?

[xcoulon]

@IvanDelsinne Could you elaborate on what you mean by custom tags, exactly?
FYI, the parser is generated after this grammar: https://github.com/bytesparadise/libasciidoc/blob/master/pkg/parser/asciidoc-grammar.peg and as you can see, all supported tags are defined in there.

[Arteneko]

For example, if I wanted to add a certain tag that'd render in a specific HTML output

…

On Wednesday, 17 April 2019, Xavier Coulon wrote: @IvanDelsinne Could you elaborate on what you mean by custom tags, exactly? FYI, the parser is generated after this grammar: https://github.com/bytesparadise/libasciidoc/blob/master/pkg/parser/asciidoc-grammar.peg and as you can see, all supported tags are defined in there. -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #334 (comment)

[xcoulon]

For example, if I wanted to add a certain tag that'd render in a specific HTML output
…
On Wednesday, 17 April 2019, Xavier Coulon wrote: @IvanDelsinne Could you elaborate on what you mean by custom tags, exactly? FYI, the parser is generated after this grammar: https://github.com/bytesparadise/libasciidoc/blob/master/pkg/parser/asciidoc-grammar.peg and as you can see, all supported tags are defined in there. -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #334 (comment)

@IvanDelsinne would you have a more specific example, please?

[Arteneko]

Okay, for example: I have images hosted on a CDN, and instead of putting the full tag, I'd want to have a custom image renderer that'd prefix the URL. This provides a need for a custom render function for a standard tag. I have git* projects and I'd like to embed a git* card inside the document, from a basic tag (e.g. only providing the repository URL). This provides a need for a custom render function for a custom tag.

…

On Wednesday, 17 April 2019, Xavier Coulon wrote: > For example, if I wanted to add a certain tag that'd render in a specific HTML output > […](#) > On Wednesday, 17 April 2019, Xavier Coulon wrote: @IvanDelsinne Could you elaborate on what you mean by custom tags, exactly? FYI, the parser is generated after this grammar: https://github.com/bytesparadise/libasciidoc/blob/master/pkg/parser/asciidoc-grammar.peg and as you can see, all supported tags are defined in there. -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: [#334 (comment)](#334 (comment)) @IvanDelsinne would you have a more specific example, please? -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #334 (comment)

[xcoulon]

Okay, for example: I have images hosted on a CDN, and instead of putting the full tag, I'd want to have a custom image renderer that'd prefix the URL. This provides a need for a custom render function for a standard tag.

I believe that you could use the standard image:: macro for that. Possibly with an attribute for the CDN prefix if you don't want to write it as-is in your document

I have git* projects and I'd like to embed a git* card inside the document, from a basic tag (e.g. only providing the repository URL). This provides a need for a custom render function for a custom tag.

I'm not sure what kind of card you want to render, but that looks actually like a custom need, indeed. Or we could add a new type of macro, such as gitcard::<some_url> but that would not be compliant with the "standard" Asciidoc spec, so I'm a bit reluctant to do that now, honestly.

Ideally, we should have an extension/plugin API for this kind of need, but I'm not there yet :/

[Arteneko]

Ideally, we should have an extension/plugin API for this kind of need, but I'm not there yet :/

I think I wrongly worded my request, as this is exactly what I was talking about.

Overall, I tried to express that I was searching for, "basically", a system like map[token]function on which we could plug our own methods.

[xcoulon]

Ideally, we should have an extension/plugin API for this kind of need, but I'm not there yet :/

I think I wrongly worded my request, as this is exactly what I was talking about.

Overall, I tried to express that I was searching for, "basically", a system like map[token]function on which we could plug our own methods.

yes, that's what I also figured out later in the evening yesterday ;) We could actually have a kind of generic macro rule which a user would associate with a template definition, and the library would use it.

[Arteneko]

What would be needed to implement that?

I'd like to convert a project of mine to AsciiDoc, but I'd need this feature, so maybe I could give a hand.

[xcoulon]

What would be needed to implement that?

I'd like to convert a project of mine to AsciiDoc, but I'd need this feature, so maybe I could give a hand.

hello @IvanDelsinne and thanks for proposing your help on this topic!

My initial thoughts are that we would need:

• a rule in the grammar to handle such custom block tags in a generic manner. Eg: git::some/url.git[key1=value1,key2=value2]. They would probably have to be added in the DocumentElement rule.
• a way to register a go template that would be associated with the tag. We could use a config file to bind the tags to the path of their associated template, for example.

Let me know if you need more input on this. In any case, feel free to start a draft PR and I'll review it ;)

[Arteneko]

Instead of passing paths, why not pass a Template instance?

Not a named template, but a generic template that'd be used using template.Execute.

This allows to support both string-based and file-based templates.

Another question I'm asking myself is if the "custom" format should be normalized or if there should be a fully free formatting.

I'm thinking about something like :\?<name>(:params)*:, basically a tag that signifies that it's a tag that should be handled post-parsing.

[xcoulon]

@IvanDelsinne We have 2 use cases here to support:

• users who embed the libasciidoc library in their project. In this case, they could actually pass the template
• users who want to run the CLI

In the latter case, we need to have a way to configure the templates (location and binding to a "macro tag").

Have you seen #347 yet? In 7332870#diff-538557cca0b726466057ac8e585b54ccR42, @odknt defines a function to configure the templates in the rendering context, and I believe that this should provide you with the expected level of abstraction that you mentioned above.

Another question I'm asking myself is if the "custom" format should be normalized or if there should be a fully free formatting. I'm thinking about something like :?(:params)*:, basically a tag that signifies that it's a tag that should be handled post-parsing.

No, I believe that we should stick to the regular format for macros: macro_name: (inline macro) or macro_name:: (block macro) and be able to associated it with a custom, registered macro during the rendering.

[Arteneko]

I missed the PR indeed, and I haven't yet taken a serious look, but that's what I'll do now.

[xcoulon]

I missed the PR indeed, and I haven't yet taken a serious look, but that's what I'll do now.

no problem and thanks for your feedback. Also, feed free to join the discussion on the PR, your input is valuable!

[Arteneko]

By looking at the new code, the only question I have is how one can define custom tags from the CLI?

I think that it's the only missing thing here; apart from that, I'd be happy to be able to use this new version.

[xcoulon]

By looking at the new code, the only question I have is how one can define custom tags from the CLI?

I think that it's the only missing thing here; apart from that, I'd be happy to be able to use this new version.

yes, we need to address this, as I mentioned in #347 (review)

I believe that we should have a new flag to specify the path to a config file (with some default) and this config file (in YAML?) could define the user templates (cc: @odknt)

[xcoulon]

By looking at the new code, the only question I have is how one can define custom tags from the CLI?
I think that it's the only missing thing here; apart from that, I'd be happy to be able to use this new version.

yes, we need to address this, as I mentioned in #347 (review)

I believe that we should have a new flag to specify the path to a config file (with some default) and this config file (in YAML?) could define the user templates (cc: @odknt)

I'm going to open a new issue for this, since #347 is already quite a large PR.