如何评论重组文本中的字符串？

Posted 2023-02-24

【中文标题】如何评论重组文本中的字符串？

【英文标题】：How to comment a string in restructured text?

【发布时间】：2011-06-14 14:30:59

【问题描述】：

html 的注释是<!-- .. -->，我怎样才能用重组文本制作这个注释块？换句话说，我怎样才能注释掉重组文本中的一些行？

【参考方案1】：

From the reference:

任意缩进的文本可以跟在 显式标记开始并将是 作为评论元素处理。

..
   _This: is a comment!

..
   [and] this!

..
   this:: too!

..
   |even| this:: !

也可以把注释和双点放在同一行：

.. Avoid this type of comment

然而，这被认为是不好的做法，因为如果评论与正确的标记结构匹配，它可能会导致意想不到的后果，正如@CecilCurry 在the comment below 中指出的那样。

【讨论】：

作为这个有用答案的补充，第一种形式（即".. This is a comment"）应该从不在实践中使用。基本上，被认为是有害的。为什么？因为有条件。以这种方式定义的任何注释，其第一行与任何现有显式标记构造（例如，引用、指令、脚注、替换）的语法匹配的任何注释都将被默默地重新解释为该构造而不是注释——这太可怕了。 为防止这种情况发生，无条件地为 all cmets 添加一个单行 ".." 语句，如上述示例的其余部分。

鉴于 Cecil Curry 所说的，如果@jball 能够修改他的示例以首先显示一个理想的形式，那将是非常好的，所以我不需要阅读所有细则来发表一个臭名昭著的评论在我的休息中。此外，我已经假设我可以将任何我想要的内容放入评论中，因此其他示例中的所有额外符号只会使原本简单的答案变得复杂......除非这些是相关的。是吗？

@CecilCurry 感谢您的洞察力，我更正了我的 ryd 文档（所以我们又见面了！）

那么 line_1.. 和 line_2 This is a comment 好吗？也就是说，您可以从第一个示例的 line_2 中删除 _ 和 : 吗？它运行良好，但不确定影响。

使用.. .. 怎么样？ （点点空间点点空间）我一直在我的 .rst 文件中使用它...

【参考方案2】：

对于 cmets，添加 2 个句点 .. 后跟一个换行符，然后将您的注释缩进。

例子：

..
  comment goes here

【参考方案3】：

我遇到了这个线程，正在寻找一种更明确的方式将 cmets 放置在重组文本中。就个人而言，我当然也不喜欢单线.. this is a comment。为了保持 cmets 可搜索和可识别，我建议考虑使用

.. only:: comment

    This is a comment

如文档所述 (http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html)：“未定义的标签是错误的”，例如 comment。

或者，可以编写todo 样式的扩展，允许语法，例如

.. comment::
    This is a comment

如果没有这样的扩展，这样做当然会产生来自构建器的错误消息。但有了这样的扩展，就像 todo 一样，可以从文档中提取 cmets 列表。

【参考方案4】：

请原谅这个重复的答案，因为我正在努力帮助像我这样的 RST 新手。我的回答显示了评论的上下文。

我天真地尝试使用上面的答案在我的 RST 文档中标记一行，DO NOT DO THIS:

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    .. Hi everyone this line will never be seen
    Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Sphinx（或其他 RST 格式化程序）不会抱怨，但“大家好”会出现在输出中。而是在您的评论之前和之后放置一个空行，如下所示：

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

    .. 
        comment Hi everyone this line will never be seen

    Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

但这样做的缺点是段落结束然后重新开始，因此您之间会有空格。

我在 RST 中没有找到任何可以使某些文本完全消失的 C /* */ 或 HTML <!-- --> 注释语法的等效项。

【参考方案5】：

检查：http://docutils.sourceforge.net/docs/user/rst/quickref.html#comments

任何以显式标记开头但不使用上述任何构造的语法的文本都是注释。

【讨论】：

这个答案有一个例子会更好。

这是一个糟糕的答案。 reStructuredText cmets 的条件过于复杂。简洁的“RTFM”后跟单行引号在此处不 就足够了。从词法上讲，什么构成和不构成有效注释取决于该注释的内容和用于指定该注释的语法。它不平凡，不明显，而且非常脆弱。

@CecilCurry：就像 RST 中的其他一切一样。

@mhsmith - 每种语言都有它的结构和语法规则。 RST 也不能幸免于这个不变的法则。