README

此模块支持导入 BibTeX 格式的文档。

尽管 OPUS4 已经能够导出文档的 BibTeX 格式元数据，但相关代码尚未包含在此模块中。

在没有用户交互的情况下导入 BibTeX 实际上是不可能的，因为 BibTeX 文件有很多种版本，通常包含非标准自定义字段。因此，需要允许用户决定特定 BibTeX 文件中字段的自定义映射和解释。

要求

OPUS4 的 BibTeX 解析器需要 Pandoc 工具来处理 BibTeX 文件中的特殊字符。

请确保安装/使用 Pandoc 的最新版本，至少版本 2.17。当前实现尚未针对旧版本的 Pandoc 进行测试。

在基于 Ubuntu/Debian 的 Linux 系统中，可以使用 apt 安装 Pandoc。

$ sudo apt install pandoc

要检查已安装的 Pandoc 版本，请运行

$ pandoc -v

要检查 Pandoc 的最新版本号，您可以访问 https://github.com/jgm/pandoc/releases。

此模块中的 BibTeX 导入是在 Pandoc 版本 2.9（2020 年 5 月发布）上开发和测试的，该版本包含在最新的 Ubuntu 版本（20.10 和 21.04）中。

配置选项

BibTeX 文件导入的默认设置位于 src\Import\import.ini。该文件不应本地编辑。可以在全局 OPUS 4 配置中扩展或修改设置。

字段映射

您可以注册任意数量的字段映射（见下文）。每个字段映射都需要一个名称，该名称是键的一部分。您可以使用 default 名称替换默认映射。目前支持的唯一选项是用于外部 JSON 字段映射配置文件名称的 file。如果未指定绝对路径，则需要指定在 bibtex.mappingsBasePath 中的基本路径。

bibtex.mappingsBasePath = APPLICATION_PATH "/application/config/bibtex"
bibtex.mappings.default.file = custom-default-mapping.json
bibtex.mappings.custom1.file = custom-mapping.json

默认字段映射由 src/Import/default-mapping.json 提供。

文档类型映射

将 BibTeX 记录映射到 OPUS4 元数据文档的重要步骤之一是确定给定的 BibTeX 类型映射到哪个 OPUS4 文档类型。您可以使用以下方式定义 BibTeX 类型 btype 和 OPUS4 文档类型 otype 之间的自定义映射

bibtex.entryTypes.btype = otype

请注意，在类型映射中使用的 BibTeX 类型名称不仅限于 14 个官方 BibTeX 类型。允许定义未知 BibTeX 类型的自定义类型映射，例如。

bibtex.entryTypes.journal = article

您可以为未定义 BibTeX 条目类型的默认 OPUS4 文档类型提供默认值。默认回退是 misc。

bibtex.defaultDocumentType = misc

字段映射

字段映射指定了某些 BibTeX 字段中的值如何映射到 OPUS4 元数据字段。字段映射由配置文件提供。目前 OPUS4 仅支持 JSON 格式的配置文件。可以在一个 OPUS4 实例中管理多个字段映射。

默认字段映射由 src/Import/default-mapping.json 提供。

字段映射配置文件的 最小 定义如下

{
  "name": "default",
  "description": "Default BibTeX Mapping Configuration.",
  "mapping": [
    …
  ]
}

其中 name 是字段映射的（任意）名称，而 description 允许您指定适合给定字段映射的预期用例。字段映射由一个或多个规则组成，这些规则在 mapping 列表中给出。请注意，给定映射规则的顺序是有意义的 - 列表中较后出现的映射规则具有更高的优先级，可以覆盖先前分配给 OPUS 文档字段的旧值。

字段映射规则

每个映射规则必须在相应的 name 键中指定至少一个名称，例如

{
  "name": "publishedYear"
}

在这种情况下，BibTeX 处理器尝试实例化类 PublishedYear（在规则类默认命名空间中，Opus\Bibtex\Import\Rules）。如果规则类不存在，则创建一个 SimpleRule 实例。此类在无需进一步处理的情况下执行 BibTeX 字段（在 bibtexField 中给出）和 OPUS 元数据字段（在 opusField 中给出）之间的简单一对一映射，例如

{
  "name": "issue",
  "options": {
    "bibtexField": "number",
    "opusField": "Issue"
  }
}

您还可以添加自定义规则类（需要实现 RuleInterface），甚至来自其他命名空间。在这种情况下，您需要显式指定命名空间，例如

{
  "name": "year",
  "class": "Opus\\Bibtex\\Custom\\Year"
}

OPUS4 为您提供了大量的预定义规则映射类，可以重复使用以制定自定义字段映射，甚至复杂的映射（见下文）。

如果正在使用的规则类允许可选配置（通过适当的设置方法），您可以按以下方式传递配置属性值

{
  "name": "pdfUrl",
  "class": "Note",
  "options": {
    "bibtexField": "pdfurl",
    "messagePrefix": "URL of the PDF: ",
    "visibility": "public"
  }
}

在此示例中，处理器通过将映射过程委托给 Note 实例来映射 BibTeX 字段 pdfurl 的内容，以 Note 对象的值（message）为目标。这是一个与 OPUS4 一起提供的类。此外，选项 messagePrefix 和 visibility 允许向 Note 的消息添加固定前缀并控制 Note 的可见性。

另一个映射条目示例由以下规则给出

{
  "name": "belongsToBibliography",
  "options": {
    "value": false
  }
}

该规则将 OPUS 文档的 belongsToBibliography 字段的值设置为固定值（在本例中为 false），而不依赖于某些 BibTeX 字段。

映射到丰富字段

BibTeX 字段可以映射到丰富字段。映射需要一个唯一的 名称，映射类称为 Enrichment。需要指定 BibTeX 字段和丰富键的名称作为选项。

{
    "name": "LocalId",
    "class": "Enrichment",
    "options": {
        "bibtexField": "LocalId",
        "enrichmentKey": "local-id"
    }
}

在上面的示例中，自定义 BibTeX 字段 "LocalId" 将映射到丰富 "local-id"。

预定义规则类

OPUS4 提供了一系列预定义的规则类（位于命名空间 Opus\Bibtex\Import\Rules）

基本规则类

OPUS4 支持创建自定义规则实现的方式。每个规则类都必须实现 RuleInterface 接口。

可以通过创建一个扩展以下基本规则类之一的类来定义自定义规则实现

或者，您可以扩展上面列出的预定义规则类之一，并适应您的需求。