Asciidoctor :: Discussion

Inline Conditional Inclusion Macros

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

7 messages Options

craigshoemaker

Inline Conditional Inclusion Macros

Is there a way to do inline conditional inclusion macros?

I would like to be able to do something like:

The control’s data source property is ifdef::wpf[`DataContext`] ifdef::web[`dataSource`] and accepts a collection of view model objects.

Is there any syntax variation that would make something like this possible?

mojavelinux

Re: Inline Conditional Inclusion Macros

Administrator

Craig,

There is currently no built-in way of doing conditional include macros for inline content. However, you could do something like this by writing a custom inline macro. I could imagine a more concise syntax, something like:

----
The control’s data source property is `select:[wpf=DataContext, web=dataSource]` and accepts a collection of view model objects.

----

It would be a good opportunity to design the ideal syntax (much like API design) so that it's pleasing for writers to write.

There are several examples of inline macros in the extensions-lab repository (I apologize for the lack of tutorial...it's a high priority for us to create one).

https://github.com/asciidoctor/asciidoctor-extensions-lab/tree/master/lib

-Dan

On Tue, Apr 21, 2015 at 10:51 AM, craigshoemaker [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Is there a way to do inline conditional inclusion macros?

I would like to be able to do something like:

The control’s data source property is ifdef::wpf[`DataContext`] ifdef::web[`dataSource`] and accepts a collection of view model objects.

Is there any syntax variation that would make something like this possible?

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Inline-Conditional-Inclusion-Macros-tp3007.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

craigshoemaker

Re: Inline Conditional Inclusion Macros

Dan:

I love the syntax you are suggesting and I think this feature would be useful to a lot of people.

I looked at the a few of the inline macros and have a pretty good idea of how it should be set up, but since I don't know Ruby I get stuck at how to do the actual conditional replacement depending on what build variables exist. Perhaps we could arrange a trade?

If finding availability for someone to write the tutorial is an issue, I would be delighted to help write it if you would help me with the macro :)

While I don't have experience with Ruby, I do have a lot of experience writing and creating guidance of all types: http://craigshoemaker.net/publications

Let me know what you think.

Best,

Craig

mojavelinux

Re: Inline Conditional Inclusion Macros

Administrator

Craig,

Here's a first cut at this.

https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/pick-inline-macro.rb

You can load it using the `-r` option of the `asciidoctor` command.

Here's the sample it is designed to handle:

----

The control’s data source property is `pick:[target-wpf=DataContext,target-web=dataSource]` and accepts a collection of view model objects.

----

The next step is to think about the various ways that we want to express conditional selection of text and then refine the macro to accommodate those scenarios.

For instance, I was thinking about a fallback.

----

This document is currently being rendered pick:[env-github="on GitHub",fallback="somewhere other than GitHub"].

----

We might also want to be able to check the value of an attribute.

----

You are ifdef:source-highlighter@coderay[using, not using] the CodeRay source highlighter.

----

This is essentially API design in the context of documentation. If we come up with the list of APIs for the macro, then we can update it to accommodate these scenarios.

Cheers,

-Dan

On Wed, Apr 29, 2015 at 7:08 AM, craigshoemaker [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Dan:

I love the syntax you are suggesting and I think this feature would be useful to a lot of people.

I looked at the a few of the inline macros and have a pretty good idea of how it should be set up, but since I don't know Ruby I get stuck at how to do the actual conditional replacement depending on what build variables exist. Perhaps we could arrange a trade?

If finding availability for someone to write the tutorial is an issue, I would be delighted to help write it if you would help me with the macro :)

While I don't have experience with Ruby, I do have a lot of experience writing and creating guidance of all types: http://craigshoemaker.net/publications

Let me know what you think.

Best,

Craig

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Inline-Conditional-Inclusion-Macros-tp3007p3058.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

craigshoemaker

Re: Inline Conditional Inclusion Macros

Dan:

Thanks!!

I really like the fallback and attribute checking you have added in there :)

I see two other things we need to add in as well. The first would be the ability to chain conditionals together. For instance:

---

The control's data source property is `pick:[target-wpf|target-sliverlight=DataContext, target-web=dataSource]` and accepts a collection of view model objects.

---

Notice how DataContext is returned for both the wpf and sliverlight targets.

The behavior here seems reminiscent of a switch statement where you can allow cases to drop to subsequent cases and also have a default case (your fallback).

The second thing is that it should work with individual words as well as multi-word strings (phrases), which you are are already showing with your in-line ifdef: example.

What do you think?

Best,

Craig

mojavelinux

Re: Inline Conditional Inclusion Macros

Administrator

Craig,

I implemented something crude to support multiple key options. Unfortunately, if we use the AttributeList parser, we are limited to word characters, hyphens or periods. So I had to use a period.

----

pick:[target-web.target-mobile=Web,target-desktop=Desktop]

----

Of course, we could simply parse the attributes using a different strategy to allow for a different character.

> The second thing is that it should work with individual words as well as multi-word strings (phrases),

This already works. Just quote the value.

----
pick:[target-web.target-mobile="Web and *mobile* are both strong contenders",target-desktop=Desktop]
----

You can even use attribute references in the value :)

Keep in mind this is just a proof of concept. You can make almost any syntax you want if you spend a bit more time on it. But hopefully this gets you somewhere.

As I look at it more, I think putting the keys in the target and putting the values in the attribute list makes more sense (and gives us more parsing flexibility).

----

pick2:target-web,target-mobile@target-desktop[Web and mobile, Desktop]

----

I implemented both options.

Thecomma separates each acceptable key for a value. @ falls to the next condition (like a switch statement). We could even implement + to require all keys to be set for a value to be selected (much like with ifdef).

Cheers,

-Dan

On Mon, May 4, 2015 at 4:09 PM, craigshoemaker [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Dan:

Thanks!!

I really like the fallback and attribute checking you have added in there :)

I see two other things we need to add in as well. The first would be the ability to chain conditionals together. For instance:

---
The control's data source property is `pick:[target-wpf|target-sliverlight=DataContext, target-web=dataSource]` and accepts a collection of view model objects.
---

Notice how DataContext is returned for both the wpf and sliverlight targets.

The behavior here seems reminiscent of a switch statement where you can allow cases to drop to subsequent cases and also have a default case (your fallback).

The second thing is that it should work with individual words as well as multi-word strings (phrases), which you are are already showing with your in-line ifdef: example.

What do you think?

Best,

Craig

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Inline-Conditional-Inclusion-Macros-tp3007p3120.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

craigshoemaker

Re: Inline Conditional Inclusion Macros

Dan:

Thank you so much! This is certainly helping point me in the right direction. I truly appreciate your help :)

Best,

Craig