Как читать вывод на этих страницах
Большинство страниц этого раздела показывают не только входные данные, но и вывод: файл, который сборка записала в dist/, текст, который сборка напечатала в терминале, или то, что напечатал инструмент вроде tofu, когда вы запустили его на результате сборки.
Эти блоки скопированы из реального запуска, а не написаны вручную. Соберите пример сами, и вы сможете построчно сравнить свой вывод со страницей.
Именно ради такого сравнения вывод здесь и приводится. Несколько страниц предлагают изменить одну строку и пересобрать проект или удалить сгенерированный файл и снова запустить инструмент, а затем изучить разницу. Следовать такой инструкции имеет смысл, только если блок, с которым вы сравниваете, точен, — иначе вы никак не отличите разницу, которую страница предлагала найти, от той, о которой она просто не упомянула.
Поэтому блок с выводом всегда находится в одном из двух состояний и никогда — в промежуточном.
Полный
Блок показывает целиком то, что назвала страница. Когда во вступлении сказано сервис
web, в блоке есть все строки этого сервиса. Когда названо имя файла, в блоке есть весь файл.
Фрагмент с пометкой в месте пропуска
Реальный вывод часто длинный, и если напечатать его целиком, в нём затеряется та единственная строка, которой посвящена страница. Там, где строки опущены, блок сообщает об этом отдельной строкой в том месте, где они пропущены:
[… omitted: what was left out]Вот как это выглядит на практике. Это план для примера terraform-declared-sensitivity, где речь идёт об одном атрибуте:
# 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", ] }В вашем собственном плане эти два атрибута будут. Пометка позволяет понять, что они там на своём месте — это строки, которые страница решила не повторять, а не что-то, что ваша сборка сделала иначе. Пометка стоит в каждом месте, где строки были опущены, так что их положение видно так же ясно, как и их отсутствие.
Пометка всегда говорит, что именно опущено, а не просто что что-то опущено. «Атрибут id, известный только после apply» даёт достаточно, чтобы узнать строку, когда вы её встретите; голое многоточие этого бы не дало.
Квадратные скобки выбраны намеренно. Строка, начинающаяся с […, не является допустимым содержимым в YAML, HCL, JSON или любом другом формате, который печатают эти страницы, и ни один из показанных здесь инструментов такую строку не печатает. Поэтому такая строка — всегда слова страницы, а не результат сборки: её нельзя ни принять за вывод, ни пропустить при беглом просмотре.
Что не является пропуском
Четыре вещи меняют вид блока, ничего из него не убирая, и ни одна из них не требует пометки:
- Указание меньшего объёма. Страница, которая говорит «сервис
web» и затем показывает этот сервис, не опустила ничего из названного. Остальная часть файла находится за пределами этого объёма, а не пропущена в нём. - Отступы. Фрагмент, извлечённый из глубоко вложенной структуры, обычно показан от левого края, чтобы его можно было читать отдельно. Строки — это выведенные строки; изменились только начальные пробелы.
- Подпись или примечание. Строка
#с именем файла, из которого взяты строки, или короткое примечание рядом со значением явно принадлежат странице, а не сборке. - Символ
#в каждой строке цитируемого сообщения. Если страница показывает команду и напечатанное ею сообщение в одном блоке, сообщение закомментировано, чтобы весь блок оставался исполняемым. Одна длинная напечатанная строка может быть разбита на несколько строк#, чтобы оставаться читаемой при этой ширине. В обоих случаях слова — это напечатанные слова в напечатанном порядке.
Пометка существует для единственного случая, который иначе обнаружить нельзя: строк, которых просто нет.
Блок, который иллюстрирует, а не воспроизводит
Некоторые страницы здесь — это описанные пошаговые руководства, а не рабочие пространства, которые можно собрать, а одна-две показывают форму полезной нагрузки, а не конкретный её запуск. Такой блок не обещает ничего, с чем можно сравнить вывод, поэтому об этом сказано в окружающем тексте — он никогда молча не подменяет настоящий вывод. Если в блоке об этом не сказано, он скопирован из запуска, и к нему применимы два описанных выше состояния.
Если вы адаптируете одну из этих страниц
Сохраняйте те же два состояния. Когда вывод меняется — потому что вы изменили пример или потому что более новый выпуск генерирует его иначе, — заменяйте блок выводом реального запуска, а не правьте его вручную, и помечайте все строки, которые опускаете. Блок, отредактированный так, чтобы выглядеть правильно, — это именно то, что призвано предотвратить это соглашение, ведь он читается точно так же, как проверенный блок.