在 Docbook 中使用很棒的字体生成 HTML

using font awesome in Docbook generated HTML

我应该采取哪些步骤在 docbook xml 文件中创建一个占位符，以便在生成的 HTML 输出中使用 font awesome 字体。 在从 DocBook 生成的 HTML 输出中寻找使用 font awesome 字体的 xslt 示例。

希望这个答案不是 tl;dr。如果您希望我将其分解为 3 个单独的答案，请告诉我。

选项 1

第一个选项是在实体声明中使用 HTML 标记，就像我在评论中首先提到的那样。

优点

  • XSLT 1.0 对文档样式表的 XSLT 更改极少

缺点

  • i html 元素无效，因此您的文档中会出现验证错误
  • 感觉像个黑客

您需要做的事情：

  1. 将您的实体声明更改为如下所示：

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

    这与我在第一条评论中的略有不同。我添加了一个空命名空间，这样 i 元素就不会自动出现在默认命名空间中。

  2. 将 link 添加到 head 中的字体真棒 css。 （我让它在本地指向超棒的字体。）

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

    为了测试我修改了 frameworks/docbook/xsl/html/profile-docbook.xsl。我在 match="*" mode="process.root" 模板的第 460 行附近添加了 link。

  3. 添加模板以匹配 i 元素，这样它就不会被替换。

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

示例...

文档输入

<!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输出（使用DocBookHTML转换场景）

<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

选项 2

第二种选择是在实体声明中使用 font awesome class 并使用具有特殊 role 属性的 symbol 元素来保存引用。

优点

  • XSLT 1.0 对文档样式表的 XSLT 更改极少
  • symbol 是一个 DocBook 元素，因此您不应该有验证问题

缺点

  • symbol 可能无法在您需要使用超赞字体图标的所有地方使用
  • 感觉像是对 symbol 的 hacky 使用（虽然可能不像第一个选项那么 hacky）

您需要做的事情：

  1. 将您的实体声明更改为如下所示：

    <!ENTITY fa-birthday-cake "fa-birthday-cake">

  2. 将 link 添加到 head 中的字体真棒 css。 （我让它在本地指向超棒的字体。）

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

    为了测试我修改了 frameworks/docbook/xsl/html/profile-docbook.xsl。我在 match="*" mode="process.root" 模板的第 460 行附近添加了 link。

  3. 添加模板以匹配symbol元素与'fa'role并输出i。 （d 绑定到配置文件中的 http://docbook.org/ns/docbook 命名空间-docbook.xsl）

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

示例...

文档输入

<!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输出（使用DocBookHTML转换场景）

<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

选项 3

第三个选项是切换到 XSLT 2.0 并使用 xsl:character-map。

优点

  • 简单的概念
  • docbook 实例或实体声明中不需要额外的标记
  • 感觉不错（不黑）

缺点

  • XSLT 2.0 因此需要使用 2.0 处理器
  • 更改为 2.0 处理器后可能会有其他 XSLT 更改。 （例如，在我的测试中，我不得不删除 profile-docbook.xsl 中的 3 个 exslt:node-set() 使用。）

您需要做的事情：

  1. 让你的实体声明看起来像这样（基于你的其他问题）：

    <!ENTITY fa-birthday-cake "&#xf1fd;">

  2. 将 link 添加到 head 中的字体真棒 css。 （我让它在本地指向超棒的字体。）

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

    为了测试我修改了 frameworks/docbook/xsl/html/profile-docbook.xsl。我在 match="*" mode="process.root" 模板的第 460 行附近添加了 link。

  3. 将xsl:stylesheet版本更改为2.0。

  4. 导入 xsl:character-map.

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

    我已经包含了一个示例 "font-awesome.xsl"。我今天有基于 font-awesome 备忘单的完整版本 (2015-05-06)。添加全部内容会使我的答案超出字符数限制；如果您需要，请告诉我。

    <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. 在xsl:output.

    中引用字符映射（带use-character-maps） 
    <xsl:output method="html" encoding="ISO-8859-1" indent="no" use-character-maps="fa"/>

  6. 可能的其他更改。

    如 "cons" 部分所述，您可能需要根据使用的处理器对 docbook 样式表进行一些更改。我使用 Saxon-HE 9.5.1.3。我通过复制 DocBook HTML 转换方案并更改处理器来做到这一点。

示例...

文档输入

<!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输出（使用修改后的DocBookHTML转换场景）

<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