Membaca keluaran di halaman-halaman ini
Sebagian besar halaman di bagian ini menampilkan keluaran selain masukan: berkas yang
ditulis build di bawah dist/, teks yang dicetak build ke terminal Anda, atau apa yang
dicetak alat seperti tofu saat Anda menjalankannya pada hasil tulisan build.
Blok-blok tersebut disalin dari eksekusi nyata, bukan ditulis secara manual. Bangun contohnya sendiri, dan Anda dapat membandingkan keluaran Anda dengan halaman ini baris demi baris.
Perbandingan itulah alasan keluaran dicantumkan di sini. Beberapa halaman ini meminta Anda mengubah satu baris lalu membangun ulang, atau menghapus berkas hasil render lalu menjalankan alat itu lagi, kemudian membaca perbedaannya. Instruksi seperti itu hanya layak diikuti jika blok yang Anda jadikan pembanding itu persis — jika tidak, Anda tidak punya cara untuk membedakan perbedaan yang memang dimaksudkan halaman untuk Anda temukan dari perbedaan yang sama sekali tidak pernah disebutkannya.
Jadi, blok yang menampilkan keluaran selalu berada dalam salah satu dari dua keadaan, dan tidak pernah di antara keduanya.
Lengkap
Blok menampilkan keseluruhan dari apa yang disebut halaman. Ketika pengantarnya menyebut layanan
web, setiap baris layanan itu ada di sana. Ketika pengantarnya menyebut sebuah berkas,
seluruh berkas ada di sana.
Kutipan, dengan tanda di tempat penghilangan
Keluaran nyata sering kali panjang, dan mencetak semuanya akan menenggelamkan satu baris yang sedang diajarkan halaman. Di tempat baris-baris dihilangkan, blok menyatakannya, pada barisnya sendiri, tepat di titik baris-baris itu dihilangkan:
[… omitted: what was left out]Berikut contoh penggunaannya. Ini adalah plan untuk contoh terraform-declared-sensitivity, dengan pokok bahasan mengenai satu atribut:
# 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 Anda sendiri akan memuat kedua atribut itu. Tanda itulah cara Anda mengetahui bahwa atribut tersebut memang ada di sana — bahwa itu adalah baris yang sengaja tidak dicetak ulang oleh halaman, bukan sesuatu yang dilakukan build Anda secara berbeda. Tanda diletakkan di setiap tempat baris dihilangkan, sehingga posisinya sama jelasnya dengan ketiadaannya.
Tanda selalu menyebutkan apa yang dihilangkan, tidak pernah hanya bahwa sesuatu dihilangkan. “Atribut id, dilaporkan baru diketahui setelah apply” cukup memberi tahu Anda untuk mengenali baris itu saat Anda menjumpainya; elipsis saja tidak.
Tanda kurung siku itu disengaja. Baris yang diawali [… bukan konten yang valid dalam
YAML, HCL, JSON, atau format lain mana pun yang dicetak halaman-halaman ini, dan tidak satu pun
alat yang ditampilkan di sini mencetaknya. Jadi, baris seperti itu selalu merupakan suara halaman,
tidak pernah sesuatu yang dihasilkan build — baris itu tidak dapat dikira keluaran dan tidak
terlewat saat membaca sekilas.
Yang bukan penghilangan
Empat hal mengubah tampilan blok tanpa menghilangkan apa pun, dan tidak satu pun memerlukan tanda:
- Menyebut cakupan yang lebih kecil. Halaman yang menyebut “layanan
web” lalu menampilkan layanan itu tidak menghilangkan apa pun dari yang disebutnya. Bagian lain berkas berada di luar cakupan, bukan hilang darinya. - Indentasi. Fragmen yang diambil dari struktur bersarang dalam biasanya ditampilkan dari margin kiri agar dapat dibaca tersendiri. Baris-barisnya adalah baris yang dihasilkan; hanya spasi di awal yang berubah.
- Keterangan atau catatan. Baris
#yang menyebut berkas asal baris-baris itu, atau catatan singkat di samping sebuah nilai, jelas merupakan suara halaman, bukan build. - Tanda
#di setiap baris pesan yang dikutip. Ketika halaman menampilkan perintah dan pesan yang dicetaknya dalam satu blok, pesan itu dijadikan komentar agar seluruh blok tetap dapat dijalankan. Satu baris cetakan yang panjang dapat dipecah menjadi beberapa baris#agar tetap terbaca pada lebar ini. Bagaimanapun, kata-katanya adalah kata-kata yang dicetak, dalam urutan cetakannya.
Tanda ada untuk satu kasus yang tidak dapat Anda deteksi dengan cara lain: baris-baris yang memang tidak ada.
Blok yang mengilustrasikan, bukan mereproduksi
Beberapa halaman di sini adalah panduan tertulis, bukan workspace yang dapat Anda bangun, dan satu atau dua menampilkan bentuk payload, bukan eksekusi tertentu darinya. Blok seperti itu tidak membawa jaminan yang dapat Anda bandingkan dengan diff, sehingga hal itu dinyatakan dalam kata-kata di sekitarnya — blok itu tidak pernah diam-diam menggantikan yang sebenarnya. Jika sebuah blok tidak menyatakannya, blok itu disalin dari eksekusi dan dua keadaan di atas berlaku.
Jika Anda mengadaptasi salah satu halaman ini
Pertahankan dua keadaan yang sama. Ketika keluaran berubah — karena Anda mengubah contohnya, atau karena rilis yang lebih baru me-render-nya secara berbeda — ganti blok itu dari eksekusi nyata alih-alih menyuntingnya secara manual, dan tandai setiap baris yang Anda hilangkan. Blok yang disunting agar tampak benar adalah satu-satunya hal yang hendak dicegah oleh konvensi ini, karena blok itu terbaca persis seperti blok yang telah diperiksa.