Lire la sortie sur ces pages
La plupart des pages de cette section vous montrent la sortie en plus de l’entrée : un fichier que le build a écrit sous dist/, le texte que le build a affiché dans votre terminal, ou ce qu’un outil comme tofu a affiché lorsque vous l’avez exécuté sur ce que le build a écrit.
Ces blocs sont copiés d’une exécution réelle, et non écrits à la main. Construisez l’exemple vous-même et vous pourrez comparer votre propre sortie à la page ligne par ligne.
Cette comparaison est la raison même pour laquelle la sortie figure ici. Plusieurs de ces pages vous demandent de modifier une ligne et de reconstruire, ou de supprimer un fichier rendu et de relancer l’outil, puis de lire la différence. Une instruction de ce genre ne vaut la peine d’être suivie que si le bloc auquel vous comparez est exact — sinon, vous n’avez aucun moyen de distinguer une différence que la page voulait vous faire trouver d’une différence qu’elle n’a tout simplement jamais mentionnée.
Un bloc qui montre une sortie se trouve donc toujours dans l’un de deux états, et jamais quelque part entre les deux.
Complet
Le bloc montre l’intégralité de ce que la page a nommé. Lorsque la phrase d’introduction dit le service web, chaque ligne de ce service y figure. Lorsqu’elle nomme un fichier, le fichier entier y figure.
Un extrait, marqué à l’endroit de l’omission
La sortie réelle est souvent longue, et tout l’afficher enfouirait la seule ligne qu’une page enseigne. Là où des lignes sont omises, le bloc le dit, sur une ligne à part, à l’endroit où elles ont été omises :
[… omitted: what was left out]Voici ce que cela donne en pratique. Ceci est un plan pour l’exemple terraform-declared-sensitivity, où le propos porte sur un seul attribut :
# 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", ] }Votre propre plan comportera ces deux attributs. La marque est ce qui vous indique qu’ils ont leur place là — qu’il s’agit de lignes que la page a choisi de ne pas réimprimer, et non de quelque chose que votre build a fait différemment. Une marque se trouve à chaque endroit où des lignes ont été retirées, si bien que leur position est aussi lisible que leur absence.
La marque dit toujours ce qui a été retiré, jamais seulement que quelque chose l’a été. « Un attribut id, signalé comme connu seulement après l’apply » vous en dit assez pour reconnaître la ligne quand vous la rencontrez ; de simples points de suspension ne le feraient pas.
Les crochets sont délibérés. Une ligne commençant par [… n’est pas un contenu valide en YAML, HCL, JSON ni dans aucun des autres formats que ces pages affichent, et aucun des outils montrés ici n’en affiche. Une telle ligne est donc toujours la page qui parle, jamais quelque chose que le build a produit — elle ne peut être ni prise pour de la sortie ni manquée lors d’une lecture en diagonale.
Ce qui n’est pas une omission
Quatre choses changent l’apparence d’un bloc sans rien omettre, et aucune d’elles ne reçoit de marque :
- Nommer une étendue plus restreinte. Une page qui dit « le service
web» puis montre ce service n’a rien omis de ce qu’elle a nommé. Le reste du fichier se trouve hors de l’étendue plutôt que d’y manquer. - L’indentation. Un fragment extrait d’une structure profondément imbriquée est généralement montré à partir de la marge gauche afin qu’il se lise seul. Les lignes sont les lignes émises ; seuls les espaces de début ont changé.
- Une légende ou une note. Une ligne
#qui nomme le fichier d’où proviennent les lignes, ou une courte note à côté d’une valeur, est visiblement la page qui parle plutôt que le build. - Un
#sur chaque ligne d’un message cité. Lorsqu’une page montre dans un même bloc une commande et le message qu’elle a affiché, le message est mis en commentaire afin que le bloc entier reste exécutable. Une seule longue ligne affichée peut être répartie sur plusieurs lignes#pour rester lisible à cette largeur. Dans un cas comme dans l’autre, les mots sont les mots affichés, dans l’ordre affiché.
La marque existe pour le seul cas que vous ne pourriez pas détecter autrement : des lignes qui ne sont tout simplement pas là.
Un bloc qui illustre plutôt qu’il ne reproduit
Quelques pages ici sont des tutoriels pas à pas écrits plutôt que des espaces de travail que vous pouvez construire, et une ou deux montrent la structure d’une charge utile plutôt qu’une exécution particulière de celle-ci. Un tel bloc ne comporte aucune promesse avec laquelle vous pourriez faire un diff, il le dit donc dans les mots qui l’entourent — il ne se substitue jamais discrètement à la chose réelle. Si un bloc ne le dit pas, il a été copié d’une exécution et les deux états ci-dessus s’y appliquent.
Si vous adaptez l’une de ces pages
Conservez les deux mêmes états. Lorsque la sortie change — parce que vous avez modifié l’exemple, ou parce qu’une version plus récente la rend différemment — remplacez le bloc à partir d’une exécution réelle plutôt que de le modifier à la main, et marquez toutes les lignes que vous omettez. Un bloc modifié pour paraître correct est précisément ce que cette convention vise à empêcher, puisqu’il se lit exactement comme un bloc qui a été vérifié.