anchor.diff:  To learn how the theming system works and how to create and apply custom themes, refer to the <<docs/theming-guide.adoc#,Asciidoctor PDF Theme Guide>>.
   You can use the built-in theme files, which you can find in the [file]_data/themes_ directory, as examples.
   
  -== Icons
  -
  -You can use icons in your PDF document by using one of 4 icon sets.
  -
  -fa - Font Awesome
  -octicon - Octicons
  -fi - Foundation icons
  -pf - Payment font
  -
  -You can set the following attributes globally at the top of your document
  -
  +== Font-based Icons
  +
  +You can use icons in your PDF document using any of the following icon sets:
  +
  +* *fa* - https://fortawesome.github.io/Font-Awesome/[Font Awesome^] (default)
  +* *octicon* - https://octicons.github.com/[Octicons^]
  +* *fi* - http://zurb.com/playground/foundation-icon-fonts-3[Foundation Icons^]
  +* *pf* - http://paymentfont.io/[Payment font^]
  +
  +You can enable font-based icons by setting the following attribute in the header of your document:
  +
  +[source,asciidoc]
  +----
   :icons: font
  -:icon-set: octicon
  -
  -An example for "the amazon icon in the pf (payment font) icon set" is written as:
  -
  -Available now at icon:amazon[set=pf]
  +----
  +
  +If you want to override the font set globally, also set the `icon-set` attribute:
  +
  +[source,asciidoc]
  +----
  +:icons: font
  +:icon-set: pf
  +----
  +
  +Here's an example that shows how to use the Amazon icon from the payment font (pf) icon set in a sentence:
  +
  +[source,asciidoc]
  +----
  +Available now at icon:amazon[].
  +----
  +
  +You can use the `set` attribute on the icon macro to override the icon set for a given icon.
  +
  +[source,asciidoc]
  +----
  +Available now at icon:amazon[set=pf].
  +----
   
   In addition to the sizes supported in the HTML backend (lg, 1x, 2x, etc), you can enter any relative value in the size attribute (e.g., 1.5em, 150%, etc).
   
  +[source,asciidoc]
  +----
   icon:android[size=40em]
  -
  -Coloring of the icon is unsupported yet.
  -
  -You can enable use of fonts during PDF generation with the following command. In this example, we enable font awesome icons
  -
  - $ asciidoctor-pdf -a icons=font basic-example.adoc
  +----
  +
  +You can enable use of fonts during PDF generation (instead of in the document header) by passing the `icons` attribute to the `asciidoctor-pdf` command.
  +
  + $ asciidoctor-pdf -a icons=font -a icon-set=octicon sample.adoc
  +
  +Icon-based fonts are handled by the `prawn-icon` gem.
  +To find a complete list of available icons, consult the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon] repository.
   
   == Optional scripts
   
  
positive.code: .Pygments
   $ gem install pygments.rb
   
  IMPORTANT: You'll need to the `coderay` gem installed to run this example since it uses the `source-highlighter` attribute with the value of `coderay`. You can invoke syntax highlighting with coderay by adding the following line at the tom of the document.
  
  :source-highlighter: coderay 
  
  Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script:
  
  
negative.code: :uri-rvm: http://rvm.io
  :uri-asciidoctor: http://asciidoctor.org
  
  // NOTE Until Asciidoctor 1.5.3, it's necessary to set outfilesuffix after header and restore it at the end of the document (see last line)
  :original-outfilesuffix: {outfilesuffix}
  :outfilesuffix: .adoc
  _Lo and behold_, a native PDF converter for AsciiDoc built with {uri-asciidoctor}[Asciidoctor] and {uri-prawn}[Prawn]! +
  _No more middleman._ +
  _No more DocBook toolchain._ +
  