Docinfo 文件

Docinfo 是 AsciiDoc 的一项功能，它允许您将自定义内容插入到输出文档的头部（head）、页眉（header）或页脚（footer）中。这些自定义内容由转换器从称为 docinfo 文件的文件中读取。Docinfo 文件旨在作为一种便捷的方式来补充转换器生成的输出。例如，可以注入转换器尚未提供的辅助元数据、样式表和脚本逻辑。

Docinfo 功能并非适用于所有后端。虽然它在转换为 HTML 和 DocBook 等输出格式时有效，但在使用 Asciidoctor PDF 转换为 PDF 时无效。

Docinfo 功能必须通过 docinfo 属性显式启用（参见启用 docinfo）。将使用哪些 docinfo 文件取决于 docinfo 属性的值以及后端。

头部 docinfo 文件

头部 docinfo 文件内容会被注入到文档的顶部。对于 HTML，内容会被追加到 <head> 元素中。对于 DocBook，内容会被追加到根 <info> 元素中。

用于 HTML 输出的 docinfo 文件可以包含有效的元素来填充 HTML <head> 元素，包括

<base>
<link>
<meta>
<noscript>
<script>
<style>

不建议使用 <title> 元素，因为它已经由转换器发出。

您不需要包含封闭的 <head> 元素，因为它被假定为外壳。

下面是一个例子

示例 1. 用于 HTML 输出的头部 docinfo 文件

<meta name="keywords" content="open source, documentation">
<meta name="description" content="The dangerous and thrilling adventures of an open source documentation team.">
<link rel="stylesheet" href="basejump.css">
<script src="map.js"></script>

用于 HTML 输出的 docinfo 文件必须以 .html 文件扩展名保存。有关更多详细信息，请参阅命名 docinfo 文件。

用于 DocBook 5.0 输出的 docinfo 文件可以包含 <info> 元素的任何子元素，例如

<address>
<copyright>
<edition>
<keywordset>
<publisher>
<subtitle>
<revhistory>

以下示例展示了 DocBook 的 docinfo 文件可能包含的一些内容。

示例 2. 用于 DocBook 5.0 输出的 docinfo 文件

<author>
  <personname>
    <firstname>Karma</firstname>
    <surname>Chameleon</surname>
  </personname>
  <affiliation>
    <jobtitle>Word SWAT Team Leader</jobtitle>
  </affiliation>
</author>

<keywordset>
  <keyword>open source</keyword>
  <keyword>documentation</keyword>
  <keyword>adventure</keyword>
</keywordset>

<printhistory>
  <para>April, 2021. Twenty-sixth printing.</para>
</printhistory>

用于 DocBook 输出的 docinfo 文件必须以 .xml 文件扩展名保存。有关更多详细信息，请参阅命名 docinfo 文件。

您可以在 Clojure Cookbook 的源代码中找到 DocBook docinfo 文件的实际示例。

页眉 docinfo 文件与头部 docinfo 文件区分开来，是通过在文件名中添加 -header 来实现的。在 HTML 输出中，页眉内容会立即插入到页眉 div (即 <div id="header">) 之前。在 DocBook 输出中，页眉内容会立即插入到开标签 (例如 <article> 或 <book>) 之后。

页眉 docinfo 文件的一个可能用途是完全替换标准样式表中的默认页眉。只需设置 noheader 属性，然后应用自定义的页眉 docinfo 文件。

页脚 docinfo 文件与头部 docinfo 文件区分开来，是通过在文件名中添加 -footer 来实现的。在 HTML 输出中，页脚内容会立即插入到页脚 div (即 <div id="footer">) 之后。在 DocBook 输出中，页脚内容会立即插入到结束标签 (例如 </article> 或 </book>) 之前。

页脚 docinfo 文件的一个可能用途是完全替换标准样式表中的默认页脚。只需设置 nofooter 属性，然后应用自定义的页脚 docinfo 文件。

命名 docinfo 文件

选择哪个文件提供 docinfo 取决于使用的是哪个转换器 (html, docbook 等) 以及 docinfo 范围是配置为特定文档 (“private”) 还是同一目录中的所有文档 (“shared”)。docinfo 文件的文件扩展名必须与输出文件的文件扩展名匹配（由 outfilesuffix 属性指定，该值始终以句点 (.) 开头）。

Docinfo 文件命名
模式	位置	行为	Docinfo 文件名
私有	头部	为 <docname>.adoc 文件向 `<head>`/`<info>` 添加内容。	`<docname>-docinfo<outfilesuffix>`
	标题	为 <docname>.adoc 文件向文档开头添加内容。	`<docname>-docinfo-header<outfilesuffix>`
	页脚	为 <docname>.adoc 文件向文档末尾添加内容。	`<docname>-docinfo-footer<outfilesuffix>`
共享	头部	为同一目录中的任何文档向 `<head>`/`<info>` 添加内容。	`docinfo<outfilesuffix>`
	标题	为同一目录中的任何文档向文档开头添加内容。	`docinfo-header<outfilesuffix>`
	页脚	为同一目录中的任何文档向文档末尾添加内容。	`docinfo-footer<outfilesuffix>`

启用 docinfo

要指定要应用的文件，请将 docinfo 属性设置为以下任何值的组合

private-head
private-header
private-footer
private (private-head,private-header,private-footer 的别名)
shared-head
shared-header
shared-footer
shared (shared-head,shared-header,shared-footer 的别名)

将 docinfo 设置为空值等同于将其值设置为 private。

例如：

:docinfo: shared,private-footer

此 docinfo 配置将应用共享的 docinfo 头部、页眉和页脚文件（如果存在），以及私有页脚文件（如果存在）。

让我们用一个例子来应用

您有两个 AsciiDoc 文档，adventure.adoc 和 insurance.adoc，保存在同一个文件夹中。您希望在将这两个文档转换为 HTML 时将相同的内容添加到它们的头部。

创建一个包含 <head> 元素的 docinfo 文件。
将其保存为 docinfo.html。
在 adventure.adoc 和 insurance.adoc 中将 docinfo 属性设置为 shared。

您还想包含一些额外的内容，但只添加到 adventure.adoc 的头部。

创建另一个包含 <head> 元素的 docinfo 文件。
将其保存为 adventure-docinfo.html。
在 adventure.adoc 中将 docinfo 属性设置为 shared,private-head

如果将其他 AsciiDoc 文件添加到同一文件夹，并在这些文件中将 docinfo 设置为 shared，那么在转换这些文件时只会添加 docinfo.html 文件。

定位 docinfo 文件

默认情况下，docinfo 文件会在文档文件所在的目录中进行搜索（这可以通过设置 :base_dir API 选项 / --base-dir CLI 选项来覆盖）。如果您想从其他位置加载它们，请将 docinfodir 属性设置为文件所在的目录。如果 docinfodir 属性的值是相对路径，则该值会被追加到文档目录。如果该值是绝对路径，则直接使用该值。

:docinfodir: common/meta

请注意，如果您使用此属性，将只会搜索指定的文件夹；文档目录中的 docinfo 文件将不再被找到。

docinfo 文件中的属性替换

Docinfo 文件可能包含属性引用。应用哪些替换由 docinfosubs 属性控制，该属性接受一个由逗号分隔的替换名称列表。如果未设置此属性，则其默认值为 attributes（即，属性引用会被解析）。

例如，如果您创建了以下 docinfo 文件

示例 3. 包含 revnumber 属性引用的 docinfo 文件 (docinfo.xml)

<edition>{revnumber}</edition>

以及这个源文档

示例 4. 包含修订号的源文档

= Document Title
Author Name
v1.0, 2020-12-30
:doctype: book
:backend: docbook
:docinfo: shared

那么转换后的 DocBook 输出将是

示例 5. 包含 docinfo 的已转换 DocBook 输出

<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>Document Title</title>
<date>2020-12-30</date>
<author>
<personname>
<firstname>Author</firstname>
<surname>Name</surname>
</personname>
</author>
<authorinitials>AN</authorinitials>
<revhistory>
<revision>
<revnumber>1.0</revnumber>
<date>2020-12-30</date>
<authorinitials>AN</authorinitials>
</revision>
</revhistory>
<edition>1.0</edition> (1)
</info>
</book>

1	`docinfo.xml` 中的 revnumber 属性引用已被替换为源文档的修订号，出现在转换后的输出中。

另一个例子是，如果您想在 HTML 头部定义许可证链接标签。

示例 6. 包含许可证 meta 标签的 docinfo 文件 (docinfo.html)

<link rel="license" href="{license-url}" title="{license-title}">

现在，在您的 AsciiDoc 源中定义这些属性

示例 7. 定义许可证属性的源文档

= Document Title
:license-url: https://mit-license.org
:license-title: MIT
:docinfo: shared

那么转换后的 HTML 中的 <head> 标签将包含

示例 8. HTML 输出中渲染的许可证链接标签

<link rel="license" href="https://mit-license.org" title="MIT">