Як читати виведення на цих сторінках
Більшість сторінок цього розділу показують вам не лише вхідні дані, а й виведення: файл, який збірка записала в 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», а потім показує цей сервіс, нічого не пропустила з того, що назвала. Решта файлу перебуває поза цим обсягом, а не відсутня в ньому. - Відступи. Фрагмент, узятий із глибоко вкладеної структури, зазвичай показано від лівого краю, щоб він читався самостійно. Рядки — це згенеровані рядки; змінилися лише початкові пробіли.
- Підпис або примітка. Рядок із
#, що називає файл, з якого взято рядки, або коротка примітка біля значення — це явно слова сторінки, а не збірки. #у кожному рядку наведеного повідомлення. Там, де сторінка показує команду й виведене нею повідомлення в одному блоці, повідомлення закоментовано, щоб увесь блок залишався придатним до запуску. Один довгий виведений рядок може бути розбито на кілька рядків із#, щоб він залишався читабельним за цієї ширини. В обох випадках слова — це виведені слова, у виведеному порядку.
Позначка існує для єдиного випадку, який інакше не виявити: рядків, яких просто немає.
Блок, що ілюструє, а не відтворює
Кілька сторінок тут — це письмові покрокові описи, а не робочі простори, які можна зібрати, а одна-дві показують форму корисного навантаження, а не конкретний його запуск. Такий блок не обіцяє нічого, з чим можна порівнювати через diff, тож він каже про це в тексті навколо себе — він ніколи мовчки не підміняє справжнє виведення. Якщо блок цього не каже, його скопійовано із запуску, і до нього застосовуються два описані вище стани.
Якщо ви адаптуєте одну з цих сторінок
Зберігайте ті самі два стани. Коли виведення змінюється — бо ви змінили приклад або бо новіший реліз генерує його інакше, — замініть блок виведенням реального запуску, а не редагуйте його вручну, і позначте всі пропущені рядки. Блок, відредагований так, щоб виглядати правильно, — це саме те, чому покликана запобігти ця домовленість, адже він читається точнісінько як перевірений блок.