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

Introduce an inline macro to represent an icon #529

Closed
mojavelinux opened this Issue Jul 31, 2013 · 10 comments

Comments

Projects
None yet
5 participants
@mojavelinux
Member

mojavelinux commented Jul 31, 2013

We can no longer assume that an icon is represented by an image file. Instead, we want to abstract away the concept of an icon to be an intent to make a visual representation of a concept.

That visual representation may be an image file, but more likely it will be a character from a icon-font set. In other words, icon-based fonts [1] are on the rise and we need a way to represent them in the document, while still preserving the separation of content and presentation.

Currently, it's possible to force HTML to be created that results in the display of a font-based icon as follows:

[icon-star]_{empty}_

However, this markup is way too specialized and all but meaningless in other backends.

Instead, we want to be able to state the intent to draw and icon as follows and allow the backend to translate in a way appropriate to the medium:

icon:star[]

Another possibility is to reserve the "icon-" prefix for the target of an image to mean that the processor should treat it as an icon:

image:icon-star[]

We could, of course, support both approaches.

[1] http://fortawesome.github.io/Font-Awesome/

@ghost ghost assigned mojavelinux Jul 31, 2013

@lordofthejars

This comment has been minimized.

Show comment
Hide comment
@lordofthejars

lordofthejars Jul 31, 2013

Member

In my opinion the first approach is better, because using:
image::icon-star[]

seems like you are accepting that the icon would be an image, but as you pointed out, font icons are rising in the web, so an icon is an icon (font or image), so the first syntax includes both possibilities.

Member

lordofthejars commented Jul 31, 2013

In my opinion the first approach is better, because using:
image::icon-star[]

seems like you are accepting that the icon would be an image, but as you pointed out, font icons are rising in the web, so an icon is an icon (font or image), so the first syntax includes both possibilities.

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jul 31, 2013

Member

Excellent point! That certainly clarifies the choice in my mind.

Member

mojavelinux commented Jul 31, 2013

Excellent point! That certainly clarifies the choice in my mind.

@LightGuard

This comment has been minimized.

Show comment
Hide comment
@LightGuard

LightGuard Jul 31, 2013

Member

I'm in favor of

icon:star[]

That tells you exactly what it is without giving you any misconceptions about implementation.

Member

LightGuard commented Jul 31, 2013

I'm in favor of

icon:star[]

That tells you exactly what it is without giving you any misconceptions about implementation.

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Aug 2, 2013

Member

Turns out AsciiDoc already has icon references elsewhere (in admonitions), so adding icon:star[] was quite simple. When font-based icons are disabled, or the backed in DocBook, it will just revert to looking for an image file in the iconsdir. Degrades nicely!

Member

mojavelinux commented Aug 2, 2013

Turns out AsciiDoc already has icon references elsewhere (in admonitions), so adding icon:star[] was quite simple. When font-based icons are disabled, or the backed in DocBook, it will just revert to looking for an image file in the iconsdir. Degrades nicely!

@graphitefriction

This comment has been minimized.

Show comment
Hide comment
@graphitefriction

graphitefriction Aug 3, 2013

Member

When you pull this feature into core, could you add:

  • some example code using the inline macro
  • maybe include an option in the example, if any apply
  • list any additional options/styles that apply
  • list related attributes that need to be/can be set
  • list exceptions (ex. this doesn't work in DocBook)

This will really help me update the documentation quickly and accurately. \o/

BTW: will the new image positioning (left, right) work for icons as well?

Member

graphitefriction commented Aug 3, 2013

When you pull this feature into core, could you add:

  • some example code using the inline macro
  • maybe include an option in the example, if any apply
  • list any additional options/styles that apply
  • list related attributes that need to be/can be set
  • list exceptions (ex. this doesn't work in DocBook)

This will really help me update the documentation quickly and accurately. \o/

BTW: will the new image positioning (left, right) work for icons as well?

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Aug 7, 2013

Member

Since we don't yet have docs in the project, I'm going to leave a snippet here so it can be copied to the appropriate place.

Icon macro

Asciidoctor 0.1.4 introduces a new inline macro for inserting an icon at an arbitrary place in paragraph content.

Here's an example that inserts a tags icon in front of a list of tag names:

icon:tags[] ruby, docs

Here's how this example renders in the HTML backed when the icons=font attribute is set:

<div class="paragraph">
<p><i class="icon-tags"></i> ruby, docs</p>
</div>

Here's how it renders in the HTML backend when the icons attribute is not set or empty:

<div class="paragraph">
<p><span class="image"><img src="./images/icons/tags.png" alt="tags"></span> ruby, docs</p>
</div>

Here's how it renders in the DocBook backend, regardless of the icons attribute value:

<inlinemediaobject>
  <imageobject>
    <imagedata fileref="./images/icons/tags.png"/>
  </imageobject>
  <textobject><phrase>tags</phrase></textobject>
</inlinemediaobject> ruby, docs

Relationship to the inline image macro

The inline icon macro is similar to the inline image macro with a few exceptions:

  • If the icons attribute has the value font, the macro will translate to a font-based icon in the HTML backend (e.g., <i class="icon-tags"></i>)
  • If the icons attribute does not have the value font, or the backend is DocBook, the macro will insert an image into the document that resolves to a file in the iconsdir directory (e.g., <img src="./images/icons/tags.png">)

The file resolution strategy when using image-based icons is the same used to locate images for the admonition icons. The file extension is set using the icontype attribute, which defaults to png.

Icon sets

At the moment, the font-based icon set is assumed to be Font Awesome. You can see the possible icon name options on the icons page page. Support for other icon sets is being discussed in issue #539.

When you aren't using font-based icons, or you are using the DocBook backend, the icon set is only limited by which icons you have in your iconsdir directory.

Customizing the icon

The icon macro has a few attributes that can be used to modify the size and orientation of the icon. At the moment, these are specific to Font Awesome and therefore only apply to HTML output when icon fonts are enabled.

  • size (first positional attribute) - scales the icon; possible values: large, 2x, 4x
  • rotate - rotates the icon: possible values: 90, 180, 270
  • flip - flips the icon: possible values: horizontal, vertical

The first unnamed attribute is assumed to be the size. For instance, to make the icon twice the size as the default, simply add 2x inside the square brackets.

icon:heart[2x]

This is equivalent to:

icon:heart[size=2x]

The previous example emits the following HTML:

<i class="icon-heart icon-2x"></i>

To rotate and flip the icon, specify these options using attributes:

icon:shield[rotate=90, flip=vertical]

The previous example emits the following HTML:

NOTE: This markup is subject to change. In particular, the <i> element may be replaced with the <span> element.

Additional metadata

Like an inline image, it's possible to add additional metadata to an inline icon.

Below are the possible attributes that apply to both font-based and image-based icons:

  • link - The URI target used for the icon, which will be rendered as a link
  • window - The target window of the link (when the link attribute is specified) (HTML backend)

Here's an example of an icon rendered as a link:

icon:download[link="http://rubygems.org/downloads/asciidoctor-0.1.3.gem"]

The previous example emits the following HTML:

<a class="image" href="http://rubygems.org/downloads/asciidoctor-0.1.3.gem"><i class="icon-download"></i></a>

Below are the possible attributes that apply in the case that font-based icons are not in use:

  • alt - The alternate text on the <img> tag (HTML backend) or text for <inlinemediaobject> (DocBook backend)
  • width - The width applied to the image
  • height - The height applied to the image
  • title - The title of the image displayed when the mouse hovers over it (HTML backend)
  • role - The role applied to the element that surrounds the icon

Currently, the inline icon macro doesn't support any options to change it's physical position (such as alignment left or right).

Member

mojavelinux commented Aug 7, 2013

Since we don't yet have docs in the project, I'm going to leave a snippet here so it can be copied to the appropriate place.

Icon macro

Asciidoctor 0.1.4 introduces a new inline macro for inserting an icon at an arbitrary place in paragraph content.

Here's an example that inserts a tags icon in front of a list of tag names:

icon:tags[] ruby, docs

Here's how this example renders in the HTML backed when the icons=font attribute is set:

<div class="paragraph">
<p><i class="icon-tags"></i> ruby, docs</p>
</div>

Here's how it renders in the HTML backend when the icons attribute is not set or empty:

<div class="paragraph">
<p><span class="image"><img src="./images/icons/tags.png" alt="tags"></span> ruby, docs</p>
</div>

Here's how it renders in the DocBook backend, regardless of the icons attribute value:

<inlinemediaobject>
  <imageobject>
    <imagedata fileref="./images/icons/tags.png"/>
  </imageobject>
  <textobject><phrase>tags</phrase></textobject>
</inlinemediaobject> ruby, docs

Relationship to the inline image macro

The inline icon macro is similar to the inline image macro with a few exceptions:

  • If the icons attribute has the value font, the macro will translate to a font-based icon in the HTML backend (e.g., <i class="icon-tags"></i>)
  • If the icons attribute does not have the value font, or the backend is DocBook, the macro will insert an image into the document that resolves to a file in the iconsdir directory (e.g., <img src="./images/icons/tags.png">)

The file resolution strategy when using image-based icons is the same used to locate images for the admonition icons. The file extension is set using the icontype attribute, which defaults to png.

Icon sets

At the moment, the font-based icon set is assumed to be Font Awesome. You can see the possible icon name options on the icons page page. Support for other icon sets is being discussed in issue #539.

When you aren't using font-based icons, or you are using the DocBook backend, the icon set is only limited by which icons you have in your iconsdir directory.

Customizing the icon

The icon macro has a few attributes that can be used to modify the size and orientation of the icon. At the moment, these are specific to Font Awesome and therefore only apply to HTML output when icon fonts are enabled.

  • size (first positional attribute) - scales the icon; possible values: large, 2x, 4x
  • rotate - rotates the icon: possible values: 90, 180, 270
  • flip - flips the icon: possible values: horizontal, vertical

The first unnamed attribute is assumed to be the size. For instance, to make the icon twice the size as the default, simply add 2x inside the square brackets.

icon:heart[2x]

This is equivalent to:

icon:heart[size=2x]

The previous example emits the following HTML:

<i class="icon-heart icon-2x"></i>

To rotate and flip the icon, specify these options using attributes:

icon:shield[rotate=90, flip=vertical]

The previous example emits the following HTML:

NOTE: This markup is subject to change. In particular, the <i> element may be replaced with the <span> element.

Additional metadata

Like an inline image, it's possible to add additional metadata to an inline icon.

Below are the possible attributes that apply to both font-based and image-based icons:

  • link - The URI target used for the icon, which will be rendered as a link
  • window - The target window of the link (when the link attribute is specified) (HTML backend)

Here's an example of an icon rendered as a link:

icon:download[link="http://rubygems.org/downloads/asciidoctor-0.1.3.gem"]

The previous example emits the following HTML:

<a class="image" href="http://rubygems.org/downloads/asciidoctor-0.1.3.gem"><i class="icon-download"></i></a>

Below are the possible attributes that apply in the case that font-based icons are not in use:

  • alt - The alternate text on the <img> tag (HTML backend) or text for <inlinemediaobject> (DocBook backend)
  • width - The width applied to the image
  • height - The height applied to the image
  • title - The title of the image displayed when the mouse hovers over it (HTML backend)
  • role - The role applied to the element that surrounds the icon

Currently, the inline icon macro doesn't support any options to change it's physical position (such as alignment left or right).

mojavelinux added a commit that referenced this issue Aug 8, 2013

@graphitefriction

This comment has been minimized.

Show comment
Hide comment
@graphitefriction

graphitefriction Aug 20, 2013

Member

@mojavelinux This is AWESOME! Thank you, thank you, thank you!

Member

graphitefriction commented Aug 20, 2013

@mojavelinux This is AWESOME! Thank you, thank you, thank you!

@llaville

This comment has been minimized.

Show comment
Hide comment
@llaville

llaville Nov 21, 2013

@mojavelinux Hello Dan,

As always your ideas are nice, and makes me want to do the same on AsciiDoc-Bootstrap backend.

This is done now. The results is available on my un-official version 3.1
http://laurent-laville.org/asciidoc/bootstrap/manual/3.1/en/macros.html#icons

Laurent

llaville commented Nov 21, 2013

@mojavelinux Hello Dan,

As always your ideas are nice, and makes me want to do the same on AsciiDoc-Bootstrap backend.

This is done now. The results is available on my un-official version 3.1
http://laurent-laville.org/asciidoc/bootstrap/manual/3.1/en/macros.html#icons

Laurent

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Nov 23, 2013

Member

Fantastic Laurent!

Hey, any chance you'd port your bootstrap backend to Asciidoctor. I think you'll find you have a lot more power with the template languages in the Ruby ecosystem (slim, haml, erb) than the homegrown one in AsciiDoc.

If you decide to port it, I'd be happy to invite the backend into the Asciidoctor organization on GitHub to help promote it. Just let me know.

Member

mojavelinux commented Nov 23, 2013

Fantastic Laurent!

Hey, any chance you'd port your bootstrap backend to Asciidoctor. I think you'll find you have a lot more power with the template languages in the Ruby ecosystem (slim, haml, erb) than the homegrown one in AsciiDoc.

If you decide to port it, I'd be happy to invite the backend into the Asciidoctor organization on GitHub to help promote it. Just let me know.

@lordofthejars

This comment has been minimized.

Show comment
Hide comment
@lordofthejars

lordofthejars Nov 23, 2013

Member

👍 to add bootstrap as backend,

Member

lordofthejars commented Nov 23, 2013

👍 to add bootstrap as backend,

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