"Macros" Content Discussion

[jaredmorgs]

http://asciidoctor.org/docs/user-manual/#macros is currently available to create content for.

Use this issue as a tracker for content suggestions, or feel free to provide PRs referencing this ticket to keep track of contributions.

This content is contained in https://github.com/asciidoctor/asciidoctor.org/blob/master/docs/user-manual.adoc

[jaredmorgs]

What content should be put into this section? Are we talking about stuff like the button Macros? Or is it something a little different?

[mojavelinux]

This section is merely meant to explain what a macro is, it's anatomy and a few illustrative examples for context. The button macro fits, but I think the examples should be more common macros like image. Image is a good example because it allows us to draw attention to block vs inline.

[jaredmorgs]

In #161 the link http://en.wikipedia.org/wiki/Macro_(computer_science) was cited as a good thing to include. I've suggested that this issue be closed and development continue in this tracker bug.

[mojavelinux]

I like that explanation. To a programmer audience, I tend to describe them as functions. Perhaps they are macros with a function-like syntax?

[mojavelinux]

Agreed that #161 can be closed since this issue covers the original request. This one needs to remain open.

[tortoise74]

I just posted a question on stackoverflow (http://stackoverflow.com/questions/40469032/use-of-roles-in-asciidoctor-macros) asking how to add colour to some text in a macro which is something that the manual entry for macros ought to explain

[mojavelinux]

I posted an answer.

[mkobit]

In a similar fashion, I have found myself wanting to define inline my own macros for use in a document to avoid repition, but not knowing how to (related question at https://stackoverflow.com/questions/37330192/how-to-define-own-asciidoc-macro)

[ecki]

I think it would help if we at least mention that in Asciidoc the macros are not defined in Asciidoc but the renderer programming. And perhaps provide a list of the standard ones. If we then note that for substitutions attributes or includes are used it would be a good start. (Does the general syntax with the [] parameters fall under element or is it macro specific?

[ecki]

A philosophical question, is Include a macro. Is image: a macro and is one vs. two colons a property of a block/inline macro or is it not related to macro syntax?

[mojavelinux]

include::<path>[<attrlist>] is a preprocessor directive, not a macro. The difference is that a preprocessor directive is processed when the lines are read, before the structure of the document is analyzed. A preprocessor directive feeds lines to the reader (or takes them away).

image::<path>[<attrlist>] and image:<path>[<attrlist>] are (built-in) macros.

If a macro has two colons, it is a block macro (a sibling of paragraphs). If a macro has one colon, it is an inline macro (a sibling of words and phrases).

[kavaliro]

Is it possible to define macros in the document itself, rather than a config file?

All I'm really trying to do is do substitution within an svg. Which I can do if I use an include. But since github doesn't allow includes, that doesn't work for my purposes. I tried assigning the svg content to an attribute. That works for placing the svg, but not resolving its internal attributes. (Is there a syntax for doing that?)

Which leaves me wanting to pass parameters into a macro which generates the svg. So far, I've not been able to find any documentation on creating a macro inside the document. Is it possible?

[opoudjis]

The DSL is not documented anywhere. I'd suggest at least the following, having wasted several hours trying to figure it out:

Inline macros consist of a name (the component before the single colon), a target (the component after the single colon), and attributes (the component in square brackets; for example name:target[attributes].

Unlike other macros, inline macros currently do not add to the Asciidoctor AST (they do not create nodes), but instead they output raw HTML. For example:

    class AltTermInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
      use_dsl
      named :alt
      parse_content_as :text
              using_format :short

      def process parent, target, attrs
            %{<alt>#{Asciidoctor::Inline.new(parent, :quoted, attrs['text']).convert}</alt>}
      end

Block and Inline macros have a DSL. The following components are of relevance:

use_dsl_:: use the DSL. named :name:: define the name of the macro parse_content_as :text (or :attributes): define the content model of the attributes component. If it is :attributes, the attribute component is broken up into individual attributes in the third argument of process for the macro (attrs above). If it is :text, the content included in the brackets is passed as the single element attrs["text"] using_format :short:: allows the target to be omitted. If this is not present, the target is mandatory, and a macro instance with the target missing will be ignored. (So alt[xyz] would not be recognised.)

The content of inline macros can itself contain formatting; to ensure it is processed, create a new Asciidoctor::Inline element with :quoted context to process the text, as above, and .convert its output. (create_inline also should do this.)

[mojavelinux]

If you'd be willing to proposal an initial draft, I'd be happy to review it. Don't worry too much about where it goes in the user manual. I can help with that. What's important is the content.

For now, just write it in the file docs/_includes/extension-inline-macro.adoc

[mojavelinux]

and .convert its output.

This is no longer necessary. You can return the Inline node and Asciidoctor will automatically convert it.

[mojavelinux]

Is it possible to define macros in the document itself, rather than a config file?

No. This goes against the philosophy of Asciidoctor to keep the content and configuration/behavior separate. (and to allow you to write powerful extensions)

But since github doesn't allow includes

GitHub doesn't support extensions either, so this approach isn't going to get you any further.

What I recommend is preprocessing the file that you push to git so that GitHub renders an intermediary state instead of the raw source. GitHub makes it very clear they don't want to be a full document processor, so we have to come at it from a different angle.