Using Icon Fonts in DITA Projects

Modern Web applications use fonts with scalable vector icons that render sharply at any resolution. Similar techniques can be used in DITA projects to include icons from the user interface in output. This session presents several options for integrating icon fonts in DITA projects and includes markup examples and renderer configurations to include icon glyphs in multiple output formats.

Presented at DITA Europe in Munich November 19, 2014 http://www.infomanagementcenter.com/DITAeurope/2014/

Transcript

1. Using Icon Fonts in DITA Projects
   ! Scalable Vector Icons in HTML & PDF Output
   infotexture
   Information Architecture & Content Strategy
   Roger W. Fienhold Sheen
   

   View Slide

2. "
   Agenda
   Introduction
   Part I — Background & Concepts
   Why Use Fonts for Icons?
   Selecting an Icon Font
   Adding the Icon Resources to Your Project
   Part II — Markup Examples
   Defining & Referencing Icons in DITA Source
   Customizations for HTML Output
   Customizations for Print (PDF) Output
   Editor Affordances
   References & Resources
   2
   

   View Slide

3. #
   $
   Introduction
   Modern Web applications use fonts with scalable
   vector icons that render sharply at any resolution.
   Similar techniques can be used in DITA projects to include
   icons from the user interface in output.
   This session presents several options for integrating
   icon fonts in DITA projects and includes markup
   examples and renderer configurations to include
   icon glyphs in multiple output formats.
   3
   

   View Slide

4. %
   Part I — Background & Concepts
   Why Use Fonts for Icons?
   At 16 pixels, an icon like this
   might look fine, but at 320?
   “Here there be jaggies…” →
   Icon font benefits
   Scale easily
   Change color easily
   Include shadows easily
   Can have transparent knockouts
   Well-supported by modern web browsers
   Can be designed on the fly (change on :hover, etc.)
   Can do anything image icons can do (change opacity, rotate, etc.)
   4
   

   View Slide

5. &
   Selecting an Icon Font
   Many popular open source fonts have licenses that permit
   commercial use. Check glyphsearch.com to find icons you like.
   Font Awesome
   Ionicons
   Iconic
   Octicons
   Other factors to consider:
   Size & glyph coverage: how large are the files and what icons do they include?
   Custom icon fonts: create a custom font with only the icons you need
   Accessibility: what will screen readers “see” and visually impaired users hear?
   Acessibility-aware fonts often use the Unicode Private Use Area (PUA) and the
   CSS property speak:  none to ensure screen readers don’t read icons aloud.
   5
   

   View Slide

6. '
   Adding the Icon Resources to Your Project
   Decide where & how to import the icons.
   Are the icons likely to change during the project lifecycle?
   If not, just download & unpack a .zip file
   If yes, consider installing via a package manager
   Bower
   Component
   Duo
   Or use version control mechanisms to easily fetch upstream updates
   Mercurial subrepository
   Git submodule (or subtree)
   [submodule  "dita-­‐src/assets/font-­‐awesome"]
      path  =  dita-­‐src/assets/font-­‐awesome
      url  =  git@github.com:FortAwesome/Font-­‐Awesome.git
   6
   

   View Slide

7. (
   Part II — Markup Examples
   Defining & Referencing Icons in DITA Source
   Decide which element to customize: seems like a
   logical candidate, but it isn’t allowed everywhere. The generic
   phrase element is more flexible (permits nesting).
   Defining icon keys in a key map
      
   
   For HTML output, add an @outputclass attribute to each key
   
   For PDF output, add the character glyph to each key’s content
   
   But why?
   7
   

   View Slide

8. What’s going on here?
   — Why Different Markup for HTML & PDF?
   For HTML output, icons are inserted via the CSS ::before pseudo-element,
   which inserts content before every instance of the element it is associated with.
   Icon fonts typically include stylesheets (CSS, LESS or SCSS files) with rules like:
   .icon-­‐check:before  {
      /*  Insert  check  mark  */
      content:  "\f046";
   }
   For PDF output, the character glyph must be explicitly added to each key’s
   content, since XSL-FO does not support the ::before pseudo-element.
   The numeric value for each icon is typically provided in a reference document
   (or “cheatsheet”), which lists each icon with its CSS class & Unicode value:
   ) icon-check (  )
   8
   

   View Slide

9. Markup alternatives
   Conditional elements (filtered by output format)
   
   
   Combine conditional elements in a
   
      
          
          
      
   
   Conditionalize key definitions by output type, use simpler (unconditional) keys
   
   
   
   
   
   9
   

   View Slide

10. Referencing icon keys
    To include an icon in your document, include a reference to the key like this:
    
    The icons can be combined with other elements and
    referenced together.
    The following example shows an excerpt from menus.dita ,
    which is defined in the root map as the source for menus keys:
       
        Dashboard    
    
    Insert a key reference like
    to show both the icon and the text: * Dashboard.
    10
    

    View Slide

11. +
    Customizations for HTML Output
    Icon fonts designed for the web are easy to integrate.
    Extend custom CSS
    Import the style sheets provided with the icon fonts to your custom CSS file
    (typically CSS, LESS or SCSS):
    @import  "../assets/icons/font-­‐awesome/less/font-­‐awesome.less";
    Extend build scripts to copy fonts to output
       
       
           
               
               
               
               
               
           
    
    11
    

    View Slide

12. ,
    Customizations for Print (PDF) Output
    PDF output requires a bit more work than HTML, and the
    steps depend on which renderer you use to convert XSL-FO
    (Apache FOP, RenderX XEP, Antenna House).
    Customization Overview
    1. Extend (or create) custom PDF plugins to use your icon font
    Add new character set for icons to logical fonts in font-­‐mappings.xml
    Extend logical fonts to associate icon character set with a new font
    Add a new attribute set to commons-­‐attr.xsl
    Create new template to apply the custom attribute set to icons
    2. Configure your XSL Formatting Objects renderer to find & use your icon font
    Define new character set for icon code ranges (XEP)
    Define new font family for icon font (XEP)
    Add, install, and/or register font file(s)
    12
    

    View Slide

13. PDF Plugins
    The font-­‐mappings.xml file maps logical fonts used in the XSLT stylesheets to the
    physical fonts used by the FO processor to generate PDF output.
    Add a new logical font to the in font-­‐mappings.xml
    
       
           
           
               
                   FontAwesome
               
               
           
       
    
    Extend the existing logical font entries with a new physical-­‐font element to
    map the icon character set to the icon font
    
       FontAwesome
    
    13
    

    View Slide

14. Add a new attribute set to /cfg/fo/attrs/commons-­‐attr.xsl
    
       0pt
       0pt
       FontAwesome
    
    Create new template to apply the custom attribute set to all phrase elements
    whose @outputclass contains icon-­‐*
       
           
               
                   
                       
                       
                   
               
               
                   
                       
                       
                   
               
           
    
    14
    

    View Slide

15. RenderX XEP Configuration
    Define new character set for icon code ranges in XEP/xep.xml
       
           
               
           
    
    Define new font family for icon font & add font file to XEP/fonts
       
           
               
           
    
    15
    

    View Slide

16. Apache Formatting Objects Processor (FOP) Configuration
    Install the icon font on your operating system.
    For DITA-OT versions prior to 1.8, adjust the Apache FOP configuration to tell
    FOP to look for the icon font in the system fonts.
    In your custom PDF plugin, edit fop/conf/fop.xconf to allow Apache FOP to
    detect the system fonts: add an auto-­‐detect element to the fonts element in the
    renderer element with the @mime attribute set to “application/pdf ”:
       
           
               
                   
                   
               
           
    
    16
    

    View Slide

17. -
    Editor Affordances
    Customizing your authoring environment to display the icons.
    Example
    The XML Editor allows you to customize the presentation of XML
    content shown in Author mode by creating alternate style sheets that extend the
    built-in (default) styles.
    This mechanism can be used to approximate the look-and-feel of company
    documents by adjusting fonts & colors to according to branding guidelines.
    Add @font-­‐face declaration to define the font file to use for the icons:
    @font-­‐face  {    
       font-­‐family:  'FontAwesome';    
       src:  url('font-­‐awesome/font/fontawesome-­‐webfont.ttf?v=3.2.1')  format('truetype');    
       font-­‐weight:  normal;    
       font-­‐style:  normal;    
    }
    17
    

    View Slide

18. Add a rule to select elements whose @outputclass begins with or contains icon-­‐
    and set them to use the new font-­‐family :
    [outputclass^="icon-­‐"],    
    [outputclass*="  icon-­‐"]  {    
       font-­‐family:  FontAwesome;    
       font-­‐weight:  normal;    
       font-­‐style:  normal;    
       text-­‐decoration:  inherit;    
       -­‐webkit-­‐font-­‐smoothing:  antialiased;    
       margin-­‐right:  .3em;    
    }
    18
    

    View Slide

19. .
    References & Resources
    Further Reading
    Leigh White’s DITA for Print: A DITA Open Toolkit Workbook
    Eliot Kimber’s DITA for Practitioners
    Popular Icon Fonts
    Font Awesome / http://fontawesome.io
    Ionicons / http://ionicons.com
    Typicons / http://typicons.com
    Iconic / https://useiconic.com/open
    Octicons / https://octicons.github.com
    Foundation / http://zurb.com/playground/foundation-icon-fonts-3
    19
    

    View Slide

20. Thank You!
    Updates
    For updates, comments and the latest code samples, visit http://infotexture.net/.
    Contact
    0 E-mail roger@infotexture.net
    1 GitHub @infotexture
    2 Twitter @infotexture
    20
    

    View Slide