Asciidoctor :: Discussion

How to migrate asciidoc macros in .conf file to asciidoctor?

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

5 messages Options

oddhack

How to migrate asciidoc macros in .conf file to asciidoctor?

I understand that asciidoc .conf files are not supported by asciidoctor. However, it appears that asciidoc [macros] are intended to be supported, although the documentation is very sparse and I can find no examples.

When I try to directly include my asciidoc <project>.conf file in the root document, either using 'include::<project.conf>[]' or by actually pasting the contents into <project>.txt, and run it through asciidoctor, I get errors like "WARNING: <project.txt>: line 19: invalid style for paragraph: macros".

So I'm stuck - is it in fact possible to use asciidoc [macros] in asciidoctor? If so, how do I get the command-line tool to recognize them? For reference, the usage is pretty simple - just adding semantic tagging to inline text so that things like flink:funcname expand properly in the generated HTML or Docbook output, like this:

[macros]
(?u)^(?P<name>):(?P<subslist>\S*?)(\[(?P<passtext>.*?)\])$=vkkeyword
(?su)(?P<name>flink):(?P<target>\w+)=

[vkkeyword-inlinemacro]
{passtext}

[flink-inlinemacro]
ifdef::basebackend-docbook[]
<code><link linkend="{target}">{target}</link></code>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<code><a href="#{target}">{target}</code>
endif::basebackend-html[]

Thanks,
Jon

mojavelinux

Re: How to migrate asciidoc macros in .conf file to asciidoctor?

Administrator

Jon,

Asciidoctor supports the definition of custom macros (inline and block) with the same syntax as AsciiDoc Python. However, Asciidoctor does not use the same mechanism as AsciiDoc Python to define them. In other words, .conf files don't work with Asciidoctor.

The decision to not support .conf files in Asciidoctor is a conscious one. I don't think it's the right approach for defining customizations. It relies on an obscure syntax and lacks the control necessary to meet many common requirements (conditional text, for instance).

That's why in Asciidoctor we have a top-level API for defining extensions and a Ruby DSL to reduce the amount of coding for common requirements. Unfortunately, I haven't had the time to document it fully, though there are many examples:

https://github.com/asciidoctor/asciidoctor-extensions-lab

and some assistance in the user manual.

http://asciidoctor.org/docs/user-manual/#extensions

If you are coming from AsciiDoc Python, you're going to have to rewrite custom macros using the Asciidoctor extensions API in order to use them in Asciidoctor. However, I assure you that it bends your brain a lot less.

I hope that clears things up for you.

Cheers,

-Dan

On Thu, Sep 3, 2015 at 4:05 AM, oddhack [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I understand that asciidoc .conf files are not supported by asciidoctor. However, it appears that asciidoc [macros] are intended to be supported, although the documentation is very sparse and I can find no examples.

When I try to directly include my asciidoc <project>.conf file in the root document, either using 'include::<project.conf>[]' or by actually pasting the contents into <project>.txt, and run it through asciidoctor, I get errors like "WARNING: <project.txt>: line 19: invalid style for paragraph: macros".

So I'm stuck - is it in fact possible to use asciidoc [macros] in asciidoctor? If so, how do I get the command-line tool to recognize them? For reference, the usage is pretty simple - just adding semantic tagging to inline text so that things like flink:funcname expand properly in the generated HTML or Docbook output, like this:

[macros]
(?u)^(?P<name>):(?P<subslist>\S*?)(\[(?P<passtext>.*?)\])$=vkkeyword
(?su)(?P<name>flink):(?P<target>\w+)=

[vkkeyword-inlinemacro]
{passtext}

[flink-inlinemacro]
ifdef::basebackend-docbook[]
<code><link linkend="{target}">{target}</link></code>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<code><a href="#{target}">{target}</code>
endif::basebackend-html[]

Thanks,
Jon

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-to-migrate-asciidoc-macros-in-conf-file-to-asciidoctor-tp3717.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | http://google.com/profiles/dan.j.allen

oddhack

Re: How to migrate asciidoc macros in .conf file to asciidoctor?

Thanks. So is it correct that in order to reproduce the effect of asciidoc regexp-based macros, I'd have to write some Ruby code to implement each macro?

mojavelinux

Re: How to migrate asciidoc macros in .conf file to asciidoctor?

Administrator

That is correct, you need to write code. If you are using Asciidoctor Ruby, then you'll write it in Ruby. If you are using AsciidoctorJ, you can write in Java, Groovy or another JVM language. We're still working on getting extensions working nicely in JavaScript with Asciidoctor.js, but we have some hurdles to get past still.

Cheers,

-Dan

On Sat, Sep 5, 2015 at 3:56 AM, oddhack [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Thanks. So is it correct that in order to reproduce the effect of asciidoc regexp-based macros, I'd have to write some Ruby code to implement each macro?

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-to-migrate-asciidoc-macros-in-conf-file-to-asciidoctor-tp3717p3719.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | http://google.com/profiles/dan.j.allen

oddhack

Re: How to migrate asciidoc macros in .conf file to asciidoctor?

mojavelinux wrote

That is correct, you need to write code. If you are using Asciidoctor Ruby,
then you'll write it in Ruby.

Has anyone looked at automatic translation of asciidoc macros into Ruby, or other target language? The situation I'm in is a large multi-author project; there are some potential benefits for us in moving to the asciidoctor toolchain, but I had hoped for it to be a less intrusive conversion, since any disruption of our tight schedule would be taken extremely poorly by most authors at present.