阅读这些页面上的输出
本节的大多数页面既展示输入,也展示输出:构建在 dist/ 下写出的文件、构建打印到终端的文本,或者在构建写出的内容上运行 tofu 之类的工具时它打印的内容。
**这些块是从真实运行中复制的,而不是手写的。**自己构建该示例,你就可以逐行将自己的输出与页面进行比较。
正是为了这种比较,这里才给出输出。其中一些页面会让你修改一行后重新构建,或删除一个渲染出的文件后再次运行工具,然后阅读其中的差异。只有当你用来比较的块是精确的,这样的指示才值得遵循——否则你无法分辨哪些差异是页面希望你发现的,哪些只是页面从未提及的。
因此,展示输出的块总是处于两种状态之一,绝不会介于两者之间。
完整
该块展示页面所指内容的全部。当引导语说 web 服务 时,该服务的每一行都在其中。当它指明一个文件时,整个文件都在其中。
摘录,并在省略处加以标记
真实输出通常很长,全部打印会淹没页面要讲解的那一行。凡是省略了行的地方,块会在省略处单独用一行说明:
[… omitted: what was left out]下面是实际用法。这是 terraform-declared-sensitivity 示例的一个 plan,要说明的重点是其中一个属性:
# module.store.terraform_data.reference will be created + resource "terraform_data" "reference" { [… omitted: an id attribute, reported as known only after apply] + input = (sensitive value) [… omitted: an output attribute, reported as known only after apply] + triggers_replace = [ + "app-artifacts", + "AKIAEXAMPLE0001", ] }你自己的 plan 会包含这两个属性。通过该标记,你就知道它们本应在那里——它们是页面选择不重复打印的行,而不是你的构建做了不同的事情。每个删去行的位置都有一个标记,因此它们的位置与它们的缺失一样清晰可读。
标记总是说明删去了什么,而不只是说明有内容被删去。“一个 id 属性,报告为仅在 apply 后可知”足以让你在遇到该行时认出它;单纯的省略号则做不到。
**方括号是有意为之的。**以 [… 开头的行在 YAML、HCL、JSON 或这些页面打印的任何其他格式中都不是有效内容,这里展示的工具也都不会打印这样的行。因此这样的行总是页面在说话,绝不是构建产生的内容——它既不会被误认为输出,也不会在浏览时被漏掉。
哪些不算省略
有四种情况会改变块的外观,但并未省略任何内容,它们都不加标记:
- **指明较小的范围。**页面说“
web服务”,然后展示该服务,就没有省略它所指的任何内容。文件的其余部分在该范围之外,而不是从中缺失。 - **缩进。**从深层嵌套结构中摘出的片段通常从左边距开始展示,以便单独阅读。这些行就是输出的行;只有前导空格有变化。
- **标题或注释。**指明这些行来自哪个文件的
#行,或值旁边的简短注释,显然是页面在说话,而不是构建。 - **引用消息的每一行前加
#。**当页面在一个块中同时展示命令及其打印的消息时,消息会被注释掉,使整个块仍可运行。单个很长的打印行可能会被折成多个#行,以便在此宽度下保持可读。无论哪种情况,文字都是打印出的文字,顺序也是打印的顺序。
标记只为一种你无法通过其他方式察觉的情况而存在:根本不在那里的行。
用于示意而非复现的块
这里有少数页面是书面的演练,而不是你可以构建的工作区;还有一两个页面展示的是载荷的结构,而不是它的某次具体运行。这样的块不承诺你可以拿来 diff,因此会在其周围的文字中说明这一点——它绝不会悄悄地冒充真实内容。如果一个块没有这样说明,那么它就是从运行中复制的,上述两种状态适用于它。
如果你改编这些页面
保持同样的两种状态。当输出发生变化时——因为你修改了示例,或者因为较新的 release 以不同方式渲染它——请用真实运行的结果替换该块,而不是手动编辑,并标记你省略的任何行。经过编辑而看起来正确的块,正是这一约定要防止的情况,因为它读起来与经过核对的块完全一样。