이 페이지들의 출력 읽는 법
이 섹션의 페이지 대부분은 입력과 함께 출력도 보여 줍니다. 빌드가 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에는 이 두 속성이 들어 있을 것입니다. 표시를 보면 그 속성들이 그 자리에 있어야 한다는 것, 즉 빌드가 다르게 동작한 결과가 아니라 페이지가 다시 싣지 않기로 한 줄이라는 것을 알 수 있습니다. 표시는 줄이 빠진 자리마다 하나씩 놓이므로, 줄이 없다는 사실만큼 그 위치도 읽어 낼 수 있습니다.
표시는 항상 무엇이 빠졌는지를 말하며, 무언가 빠졌다는 사실만 말하지 않습니다. “apply 후에만 알 수 있는 것으로 보고되는 id 속성”이라고 하면 해당 줄을 만났을 때 알아보기에 충분하지만, 말줄임표만으로는 그렇지 않습니다.
대괄호는 의도된 것입니다. […로 시작하는 줄은 YAML, HCL, JSON 및 이 페이지들이
출력하는 다른 어떤 형식에서도 유효한 내용이 아니며, 여기에 나오는 어떤 도구도 그런
줄을 출력하지 않습니다. 따라서 그런 줄은 항상 페이지가 하는 말이지 빌드가 만든 것이
아닙니다. 출력으로 오인되지도 않고, 훑어보다가
놓치지도 않습니다.
생략이 아닌 것
다음 네 가지는 아무것도 빠뜨리지 않으면서 블록의 모양을 바꾸며, 어느 것에도 표시를 붙이지 않습니다.
- 더 좁은 범위 지칭. “
web서비스”라고 말한 뒤 그 서비스를 보여 주는 페이지는 지칭한 대상에서 아무것도 빠뜨리지 않은 것입니다. 파일의 나머지 부분은 범위에서 빠진 것이 아니라 범위 밖에 있는 것입니다. - 들여쓰기. 깊이 중첩된 구조에서 떼어 낸 조각은 그것만으로 읽히도록 보통 왼쪽 여백부터 보여 줍니다. 줄은 출력된 줄 그대로이며, 앞쪽 공백만 바뀌었습니다.
- 캡션이나 주석. 줄이 나온 파일을 지칭하는
#줄이나 값 옆의 짧은 주석은 빌드가 아니라 페이지가 하는 말임이 눈에 보입니다. - 인용한 메시지의 모든 줄에 붙은
#. 한 블록에 명령과 그 명령이 출력한 메시지를 함께 보여 주는 페이지에서는 블록 전체를 실행할 수 있도록 메시지를 주석 처리합니다. 출력된 긴 한 줄은 이 너비에서 읽기 쉽도록 여러#줄로 나뉠 수 있습니다. 어느 경우든 단어는 출력된 단어 그대로이고, 순서도 출력된 순서 그대로입니다.
표시는 달리 알아챌 수 없는 단 한 가지 경우, 즉 줄이 그냥 없는 경우를 위해 존재합니다.
재현하지 않고 예시하는 블록
여기의 몇몇 페이지는 빌드할 수 있는 작업 공간이 아니라 글로 쓴 안내이며, 한두 페이지는 특정 실행 결과가 아니라 페이로드의 형태를 보여 줍니다. 그런 블록은 diff로 비교할 수 있다는 약속을 담고 있지 않으므로, 주변 문장에서 그 사실을 밝힙니다. 그런 블록이 실제 결과를 슬그머니 대신하는 일은 없습니다. 블록이 그렇게 밝히지 않는다면 실행에서 복사한 것이며, 위의 두 가지 상태가 적용됩니다.
이 페이지들을 변형해 사용하는 경우
같은 두 가지 상태를 유지하십시오. 예제를 바꾸었거나 새 release가 다르게 렌더링해서 출력이 바뀌면, 블록을 손으로 편집하지 말고 실제 실행 결과로 교체하며, 생략하는 줄은 모두 표시하십시오. 그럴듯해 보이도록 편집한 블록은 검증된 블록과 똑같이 읽히므로, 이 관례가 막으려는 바로 그것입니다.