转义索引指令中的特殊字符

如何解决转义索引指令中的特殊字符

我正在为使用 Sphinx 的 Prolog 系统实现生成文档。 Prolog 语言包括分别由复合词 (',')/2 和 (;)/2 表示的合取和析取控制结构。

但是由于逗号和分号的存在，以下索引指令不会生成正确的条目：

.. index:: (',')/2

.. index:: (;)/2

到目前为止，我一直无法找到字符转义解决方案。我对 Prolog !/0 控制结构也有同样的问题，但我在那里找到了一种解决方法：

.. index:: !!/0

尝试使用反斜杠无济于事。是否支持在我缺少的指令中转义特殊字符？是否有其他解决方案可以让 (',')/2、(;)/2 和 !/0 索引条目？

解决方法

.. index:: 是专门的 Sphinx 指令，而不是 standard reST directive。

我认为这是一个 Sphinx 错误，请注意如果不使用 name: 选项，以下仅使用分号的示例会中断：

.. index::
    single: ;
    name: aa

给出以下 HTML：

<li><a href="my_index.html#index-2">;</a></li>

使用 name: 选项的两个示例

.. index::
    single: (',')/2
    name: aaa

.. index::
    single: !!/0
    name: aaaaa

提供以下 HTML：

<li><a href="my_index.html#index-5">!!/0</a></li>
<li><a href="my_index.html#index-3">(&#39;,&#39;)/2</a></li>

但是现在如果我们使用

.. index::
    single: (;)/2
    name: a

它给出了这个 HTML：

      <li>
    (

      <ul>
        <li><a href="my_index.html#index-1">)/2</a>
</li>
      </ul></li>

所以这可能是解析名称的错误，分号没有理由导致在 <ul> 中间引入额外的 <li> 对。

一开始人们往往会责怪名称中使用了符号并试图逃避它们。接下来您会质疑分号本身是否被允许，因为这些字段很可能在 HTML 中使用，因此受 Identifier normalization of class names and identifiers keys 的约束。查看 docutils 规范：

ID 和 NAME 标记必须以字母 ([A-Za-z]) 开头，后面可以跟任意数量的字母、数字 ([0-9])、连字符 ("-")、下划线 (" _")、冒号 (":") 和句点 (".")。

但这被一个简单的事实所推翻，即使用 name: 和 single: 选项解决了两种情况 - 其中一种用分号分隔。 name: 选项本身是最近的，see issue #1671。查看 issue #7031 允许的字符最近也发生了变化。最后，最近出现了一个可疑的类似分号 issue #8405...

旁注：

由于这是一个 Prolog 线程，我将提到“语法生产显示”可能会使用 .. productionlist:: 指令和 :token: 角色为您的文档提供一些东西。我没有看到它被使用。显然它只需要复制一个 (BNF) grammar of Prolog。