New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

"Macros" Content Discussion #443

Open
jaredmorgs opened this Issue Dec 22, 2015 · 16 comments

Comments

Projects
None yet
7 participants
@jaredmorgs
Member

jaredmorgs commented Dec 22, 2015

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

This comment has been minimized.

Show comment
Hide comment
@jaredmorgs

jaredmorgs Dec 31, 2015

Member

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

Member

jaredmorgs commented Dec 31, 2015

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 comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jan 1, 2016

Member
Member

mojavelinux commented Jan 1, 2016

@jaredmorgs

This comment has been minimized.

Show comment
Hide comment
@jaredmorgs

jaredmorgs Jan 23, 2016

Member

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.

Member

jaredmorgs commented Jan 23, 2016

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

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jan 26, 2016

Member

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

Member

mojavelinux commented Jan 26, 2016

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

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Mar 11, 2016

Member

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

Member

mojavelinux commented Mar 11, 2016

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

@tortoise74

This comment has been minimized.

Show comment
Hide comment
@tortoise74

tortoise74 Nov 7, 2016

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

tortoise74 commented Nov 7, 2016

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

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Dec 14, 2016

Member

I posted an answer.

Member

mojavelinux commented Dec 14, 2016

I posted an answer.

@mkobit

This comment has been minimized.

Show comment
Hide comment
@mkobit

mkobit Feb 15, 2017

Member

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)

Member

mkobit commented Feb 15, 2017

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

This comment has been minimized.

Show comment
Hide comment
@ecki

ecki Jul 20, 2017

Contributor

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?

Contributor

ecki commented Jul 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@ecki

ecki Jul 20, 2017

Contributor

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?

Contributor

ecki commented Jul 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jul 20, 2017

Member

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).

Member

mojavelinux commented Jul 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kavaliro

kavaliro Dec 18, 2017

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?

kavaliro commented Dec 18, 2017

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

This comment has been minimized.

Show comment
Hide comment
@opoudjis

opoudjis Feb 15, 2018

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.)

opoudjis commented Feb 15, 2018

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

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Feb 15, 2018

Member

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

Member

mojavelinux commented Feb 15, 2018

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

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Feb 15, 2018

Member

and .convert its output.

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

Member

mojavelinux commented Feb 15, 2018

and .convert its output.

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

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Feb 15, 2018

Member

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.

Member

mojavelinux commented Feb 15, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment