Jak czytać dane wyjściowe na tych stronach
Większość stron w tej sekcji pokazuje zarówno dane wejściowe, jak i wyjściowe: plik, który kompilacja zapisała w dist/, tekst, który kompilacja wypisała w terminalu, albo to, co wypisało narzędzie takie jak tofu
uruchomione na wyniku kompilacji.
Te bloki są skopiowane z rzeczywistego uruchomienia, a nie napisane ręcznie. Po samodzielnym zbudowaniu przykładu można porównać własne dane wyjściowe ze stroną wiersz po wierszu.
To porównanie jest jedynym powodem, dla którego dane wyjściowe w ogóle tu są. Kilka z tych stron prosi o zmianę jednego wiersza i ponowną kompilację albo o usunięcie wygenerowanego pliku i ponowne uruchomienie narzędzia, a następnie o odczytanie różnicy. Taką instrukcję warto wykonywać tylko wtedy, gdy blok, z którym się porównuje, jest dokładny — w przeciwnym razie nie da się odróżnić różnicy, którą strona miała pokazać, od takiej, o której po prostu nie wspomniała.
Dlatego blok pokazujący dane wyjściowe jest zawsze w jednym z dwóch stanów i nigdy w stanie pośrednim.
Kompletny
Blok pokazuje całość tego, co wskazała strona. Gdy wprowadzenie mówi o usłudze
web, obecny jest każdy wiersz tej usługi. Gdy wskazuje plik, obecny jest
cały plik.
Fragment z oznaczeniem miejsca pominięcia
Rzeczywiste dane wyjściowe są często długie, a wypisanie ich w całości ukryłoby jedyny wiersz, którego dotyczy strona. Tam, gdzie pominięto wiersze, blok informuje o tym w osobnym wierszu, w miejscu, w którym je pominięto:
[… omitted: what was left out]Oto przykład zastosowania. To plan dla przykładu terraform-declared-sensitivity, w którym chodzi o jeden atrybut:
# 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", ] }Własny plan będzie zawierał te dwa atrybuty. Oznaczenie pozwala wiedzieć, że mają tam być — że są to wiersze, których strona postanowiła nie powtarzać, a nie coś, co kompilacja zrobiła inaczej. Oznaczenie stoi w każdym miejscu, z którego usunięto wiersze, więc ich położenie jest równie czytelne jak ich brak.
Oznaczenie zawsze mówi, co pominięto, a nigdy tylko, że coś pominięto. „Atrybut id, zgłaszany jako znany dopiero po apply” mówi wystarczająco dużo, by rozpoznać ten wiersz po jego napotkaniu; sam wielokropek by nie wystarczył.
Nawiasy są celowe. Wiersz zaczynający się od [… nie jest poprawną treścią w
YAML, HCL, JSON ani w żadnym innym formacie wypisywanym na tych stronach, a żadne z
pokazanych tu narzędzi takiego wiersza nie wypisuje. Taki wiersz to więc zawsze głos strony, nigdy
coś, co wytworzyła kompilacja — nie można go ani pomylić z danymi wyjściowymi, ani przeoczyć
podczas pobieżnego czytania.
Co nie jest pominięciem
Cztery rzeczy zmieniają wygląd bloku, niczego nie pomijając, i żadna z nich nie wymaga oznaczenia:
- Wskazanie mniejszego zakresu. Strona, która mówi o „usłudze
web”, a następnie pokazuje tę usługę, niczego nie pominęła z tego, co wskazała. Reszta pliku leży poza zakresem, a nie jest z niego wycięta. - Wcięcia. Fragment wyjęty z głęboko zagnieżdżonej struktury jest zwykle pokazywany od lewego marginesu, aby był czytelny samodzielnie. Wiersze są wierszami wygenerowanymi; zmieniły się tylko spacje na początku.
- Podpis lub uwaga. Wiersz
#podający plik, z którego pochodzą wiersze, albo krótka uwaga obok wartości to wyraźnie głos strony, a nie kompilacji. - Znak
#w każdym wierszu cytowanego komunikatu. Gdy strona pokazuje w jednym bloku polecenie i komunikat, który ono wypisało, komunikat jest zakomentowany, aby cały blok dało się uruchomić. Pojedynczy długi wypisany wiersz może zostać zawinięty na kilka wierszy#, aby pozostał czytelny przy tej szerokości. W obu przypadkach słowa są słowami wypisanymi, w wypisanej kolejności.
Oznaczenie istnieje dla jedynego przypadku, którego nie dałoby się inaczej wykryć: wierszy, których po prostu nie ma.
Blok, który ilustruje, a nie odtwarza
Kilka stron to opisane krok po kroku przykłady, a nie obszary robocze, które można zbudować, a jedna lub dwie pokazują kształt ładunku, a nie konkretne jego uruchomienie. Taki blok nie daje żadnej gwarancji, z którą można by porównywać, więc mówi o tym w otaczającym go tekście — nigdy po cichu nie udaje prawdziwych danych. Jeśli blok tego nie mówi, został skopiowany z uruchomienia i obowiązują go dwa opisane wyżej stany.
Adaptowanie jednej z tych stron
Należy zachować te same dwa stany. Gdy dane wyjściowe się zmieniają — z powodu zmiany przykładu albo dlatego, że nowsze wydanie generuje je inaczej — należy zastąpić blok wynikiem rzeczywistego uruchomienia zamiast edytować go ręcznie i oznaczyć wszystkie pominięte wiersze. Blok edytowany tak, by wyglądał poprawnie, to właśnie to, czemu ta konwencja ma zapobiegać, ponieważ czyta się go dokładnie tak samo jak blok, który sprawdzono.