问题描述
我正在为使用 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">(',')/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。