0

What steps should I take in creating a placeholder in docbook xml files that will use font awesome fonts in the generated HTML output. Looking for xslt examples that use font awesome fonts in HTML output generated from DocBook.

10
  • Actually I think the approach I want to take is create an entity file for all the unicode characters representing the awesome fonts and then reference that entity file from a DOCTYPE ENTITY statement in the xml header. Currently characters appear as a # pound symbol in the output. Guessing I need to add something to custom xsl layer that translates to correct awesome icon, not sure. Any ideas? May 5, 2015 at 12:17
  • You also need to specify the FontAwesome font-family. To do this without changing the surrounding font, you'll end up adding a span anyway. If you use entity references, might as well put the entire markup in the entity: <!ENTITY cake "<i class='fa fa-birthday-cake'></i>"> (Don't forget that you also need the FontAwesome font so the font-family can be resolved.) May 5, 2015 at 17:21
  • Thanks for info it is getting me closer, however the docbook validation and xsl files don't allow the i element. Appears that I will need to find which docbook element and attributes will be converted to the i element and class attribute in the HTML output by the docbook xsl, or attempt to customize the xsl. May 5, 2015 at 22:47
  • <!ENTITY coffee "&lt;i class='fa fa-coffee'&gt;&lt;/i&gt;"> If I use Dec hex or html unicode the html output also contains the &lt; and &gt; instead of actual characters. If I use entity statement as you indicated, then the tag is empty - no fa class iinfo. May 6, 2015 at 0:53
  • To clarify, no matter how I represent the less than and greater than symbols in the ENTITY declaration the xsl transformed html source contains &lt; and &gt;. If I manually change them to < and > for the i element the page is displayed correctly with awesome font. Is there a way to force the html output to contain < and >. May 6, 2015 at 3:20

1 Answer 1

3

Hopefully this answer isn't tl;dr. If you would rather me break this out into 3 separate answers, please let me know.

Option 1

The first option is to use the HTML markup in the entity declaration like I first mentioned in the comments.

Pros

  • XSLT 1.0 so minimal XSLT changes to docbook stylesheets

Cons

  • i html element isn't valid so you'll have validation errors in your docs
  • feels like a hack

What you'll need to do:

  1. Change your entity declarations to look like this:

    <!ENTITY fa-birthday-cake "<i class='fa fa-birthday-cake' xmlns=''></i>">
    

    This is slightly different from what I had in my first comment. I added an empty namespace so that the i element wasn't automatically in the default namespace.

  2. Add the link to the font-awesome css in the head. (I have it pointing to font-awesome locally.)

    <link rel="stylesheet" href="font-awesome-4.3.0/css/font-awesome.min.css"/>
    

    For testing I modified frameworks/docbook/xsl/html/profile-docbook.xsl. I added the link around line 460 in the match="*" mode="process.root" template.

  3. Add the template to match the i element so it doesn't get replaced.

    <xsl:template match="i">
        <xsl:copy-of select="."/>
    </xsl:template>
    

Example...

Docbook Input

<!DOCTYPE section [
<!ENTITY fa-birthday-cake "<i class='fa fa-birthday-cake' xmlns=''></i>">
]>
<section xmlns="http://docbook.org/ns/docbook" version="5.0">
    <title>Section Template Title</title>
    <para>birthday cake: &fa-birthday-cake;</para>
</section>

HTML Output (using DocBook HTML transformation scenario)

<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
        <link rel="stylesheet" href="font-awesome-4.3.0/css/font-awesome.min.css">
        <title>Section Template Title</title>
        <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
    </head>
    <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
        <div class="section">
            <div class="titlepage">
                <div>
                    <div>
                        <h2 class="title" style="clear: both">
                        <a name="d56e3"></a>Section Template Title</h2>
                    </div>
                </div>
                <div></div>
                <hr>
            </div>
            <p>birthday cake: <i class='fa fa-birthday-cake'></i></p>
        </div>
    </body>
</html>

Rendererd HTML

Rendered HTML

Option 2

The second option is to use font awesome class in the entity declaration and use the symbol element, with a special role attribute, to hold the reference.

Pros

  • XSLT 1.0 so minimal XSLT changes to docbook stylesheets
  • symbol is a DocBook element so you shouldn't have validation issues

Cons

  • symbol might not be available in all of the places you need to use a font-awesome icon
  • feels like a hacky use of symbol (probably not as hacky as the first option though)

What you'll need to do:

  1. Change your entity declarations to look like this:

    <!ENTITY fa-birthday-cake "fa-birthday-cake">
    
  2. Add the link to the font-awesome css in the head. (I have it pointing to font-awesome locally.)

    <link rel="stylesheet" href="font-awesome-4.3.0/css/font-awesome.min.css"/>
    

    For testing I modified frameworks/docbook/xsl/html/profile-docbook.xsl. I added the link around line 460 in the match="*" mode="process.root" template.

  3. Add the template to match the symbol element with the 'fa' role and output the i. (d is bound to the http://docbook.org/ns/docbook namespace in profile-docbook.xsl)

    <xsl:template match="d:symbol[@role='fa']">
        <i class="fa {.}"></i>
    </xsl:template>
    

Example...

Docbook Input

<!DOCTYPE section [
<!ENTITY fa-birthday-cake "fa-birthday-cake">
]>
<section xmlns="http://docbook.org/ns/docbook" version="5.0">
    <title>Section Template Title</title>
    <para>birthday cake: <symbol role="fa">&fa-birthday-cake;</symbol></para>
</section>

HTML Output (using DocBook HTML transformation scenario)

<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
        <link rel="stylesheet" href="font-awesome-4.3.0/css/font-awesome.min.css">
        <title>Section Template Title</title>
        <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
    </head>
    <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
        <div class="section">
            <div class="titlepage">
                <div>
                    <div>
                        <h2 class="title" style="clear: both">
                        <a name="d56e3"></a>Section Template Title</h2>
                    </div>
                </div>
                <div></div>
                <hr>
            </div>
            <p>birthday cake: <i class='fa fa-birthday-cake'></i></p>
        </div>
    </body>
</html>

Rendererd HTML

Rendered HTML

Option 3

The third option is to switch to XSLT 2.0 and use an xsl:character-map.

Pros

  • Simple concept
  • No additional markup needed in the docbook instance or in the entity declarations
  • Feels good (not hacky)

Cons

  • XSLT 2.0 so will need to use a 2.0 processor
  • There might be additional XSLT changes after changing to the 2.0 processor. (For example, in my testing I had to remove 3 exslt:node-set() uses in profile-docbook.xsl.)

What you'll need to do:

  1. Keep your entity declarations looking like this (based on your other question https://stackoverflow.com/questions/30055181/how-do-i-insert-fonts-as-an-entity-in-docbook):

    <!ENTITY fa-birthday-cake "&#xf1fd;">
    
  2. Add the link to the font-awesome css in the head. (I have it pointing to font-awesome locally.)

    <link rel="stylesheet" href="font-awesome-4.3.0/css/font-awesome.min.css"/>
    

    For testing I modified frameworks/docbook/xsl/html/profile-docbook.xsl. I added the link around line 460 in the match="*" mode="process.root" template.

  3. Change the xsl:stylesheet version to 2.0.

  4. Import the xsl:character-map.

    <xsl:include href="font-awesome.xsl"/>
    

    I've included an example "font-awesome.xsl". I have the complete version based on the font-awesome cheatsheet today (2015-05-06). Adding the entire contents pushes my answer over the character limit; let me know if you need it.

    <xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:character-map name="fa">
            <xsl:output-character string="&lt;i class='fa fa-birthday-cake'&gt;&lt;/i&gt;" character="&#xf1fd;"/>
        </xsl:character-map>
    </xsl:stylesheet>
    
  5. Reference the character map (with use-character-maps) in the xsl:output.

    <xsl:output method="html" encoding="ISO-8859-1" indent="no" use-character-maps="fa"/>
    
  6. Possible additional changes.

    Like mentioned in the "cons" section, you might need to make some changes to the docbook stylesheets depending on what processor you use. I used Saxon-HE 9.5.1.3. I did this by duplicating the DocBook HTML transformation scenario and changing the processor.

Example...

Docbook Input

<!DOCTYPE section [
<!ENTITY fa-birthday-cake "&#xf1fd;">
]>
<section xmlns="http://docbook.org/ns/docbook" version="5.0">
    <title>Section Template Title</title>
    <para>birthday cake: &fa-birthday-cake;</para>
</section>

HTML Output (using the modified DocBook HTML transformation scenario)

<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
        <link rel="stylesheet" href="font-awesome-4.3.0/css/font-awesome.min.css">
        <title>Section Template Title</title>
        <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
    </head>
    <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
        <div class="section">
            <div class="titlepage">
                <div>
                    <div>
                        <h2 class="title" style="clear: both">
                        <a name="d56e3"></a>Section Template Title</h2>
                    </div>
                </div>
                <div></div>
                <hr>
            </div>
            <p>birthday cake: <i class='fa fa-birthday-cake'></i></p>
        </div>
    </body>
</html>

Rendererd HTML

Rendered HTML

12
  • This sounds great. I think this is something a lot company pubs depts could use. I would like a copy of your font-awesome.xsl file. I also experimented with option 2 using the docbook literal element, but decided it too may have limitations on where it could be used. I will try this out tomorrow. Thanks once again. May 7, 2015 at 1:18
  • @JeffCunningham - If you send me an email (dhaley77 gmail) I will send it to you. May 7, 2015 at 1:24
  • Ok sent you email from jeffcc. Thanks May 7, 2015 at 1:47
  • I had to put a space before the closing </i> tag in the entity. If not there the html source leaves off the closing tag as puts in /> empty tag closure format. This causes multiple icons to appear in browser if </i> is missing. May 7, 2015 at 3:06
  • 1
    This is what I am going with for now until we move to an XSLT 2.0 processor. Entity declaration: <!ENTITY fa-beer "<markup role='fa fa-beer'></markup>"> In xml file: <para>&fa-beer; Assistant</para> In xsl file: <xsl:template match="d:markup[@role]"> ` <span class="{@role}"></span>` </xsl:template> HTML output: <span class="fa fa-beer"/> May 8, 2015 at 19:54

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.