Dokumentasi tanpa contoh hanyalah katalog janji. Bagian ini mengisi section Instalasi dan Penggunaan dengan empat elemen pembentuk contoh yang baik: blok perintah pre+code, nama perintah code inline, tombol kbd, dan keluaran program samp. Keempatnya dibedah pada chapter Code, Kbd, Samp, dan Var, sementara perilaku whitespace-nya pada chapter Pre.

Blok Perintah Pemasangan #

Ganti section Instalasi dengan versi lengkapnya:

html 
<section id="instalasi">
  <h2>Instalasi</h2>
  <p>Tugas terdistribusi sebagai satu berkas mandiri. Unduh rilis terbaru, beri izin eksekusi, lalu pindahkan ke folder yang tercantum pada variabel <code>PATH</code>:</p>
  <pre><code>curl -O https://tugas-cli.example.com/unduh/tugas-1.0
chmod +x tugas-1.0
sudo mv tugas-1.0 /usr/local/bin/tugas</code></pre>
  <p>Uji pemasangan dengan menjalankan <code>tugas bantuan</code> lalu menekan <kbd>Enter</kbd>; baris <samp>Tugas v1.0</samp> di bagian atas ringkasan menandakan alat siap dipakai.</p>
</section>

Mari kita bedah baris demi baris:

  1. section dan h2 (baris 1-2): sudah terpasang sejak Bagian 3 — bagian ini hanya menambah isinya.
  2. Paragraf pengantar (baris 3): diakhiri titik dua — sinyal bahwa baris-baris berikutnya adalah perintah yang bisa disalin.
  3. pre+code (baris 4-6): pre mempertahankan baris baru dan spasi persis seperti ditulis; code di dalamnya menandai seluruh isi sebagai kode. Kombinasi keduanya adalah pola baku blok perintah.
  4. Satu perintah satu baris (baris 4-6): tiga baris berisi tiga perintah terpisah yang dijalankan berurutan — bukan satu skrip — sehingga pembaca menyalinnya selangkah demi selangkah.
  5. Paragraf uji (baris 7): tiga elemen bekerja dalam satu kalimat — code untuk nama perintah dalam kalimat, kbd untuk tombol Enter yang ditekan pengguna, dan samp untuk keluaran Tugas v1.0 yang dicetak program.

Perintah dan Keluarannya #

Section Penggunaan menambahkan pola pasangan: perintah diikuti balasannya.

html 
<section id="penggunaan">
  <h2>Penggunaan</h2>
  <p>Alur harian Tugas singkat: catat, tinjau, lalu tandai selesai. Dua perintah berikut memperlihatkan keseluruhannya:</p>
  <pre><code>tugas tambah "Kirim laporan mingguan tiap Jumat"
tugas daftar</code></pre>
  <p>Terminal membalas:</p>
  <pre><samp>1. [ ] Kirim laporan mingguan tiap Jumat</samp></pre>
  <p>Angka di depan tiap baris adalah nomor tugas — <code>tugas selesai 1</code> menutup tugas pertama tersebut.</p>
</section>

Empat keputusan pada blok ini:

  1. Pengantar dan blok perintah (baris 3-5): dua perintah alur harian — mencatat, lalu meninjau.
  2. Kalimat pengantar keluaran (baris 6): “Terminal membalas:” memisahkan ketikan dari balasan — hanya sebaris, tetapi menuntun mata pembaca.
  3. pre+samp (baris 7): keluaran program diberi samp — contoh keluaran, bukan kode yang diketik. Pembaca layar mengumumkannya sebagai contoh keluaran; tanda [ ] di dalamnya menandakan tugas yang belum ditutup.
  4. Paragraf penutup (baris 8): nama perintah inline tugas selesai 1 menautkan kembali keluaran ke tindakan berikutnya.

Karakter Khusus dalam Contoh #

Perhatikan kembali uraian tugas bantuan dari Bagian 3 — baris terakhirnya memuat tugas selesai &lt;nomor&gt;. Bentuk generik perintah itu memakai tanda kurung sudut, dan dalam HTML tanda < adalah pembuka tag. Bandingkan dua cara menulisnya:

html 
<!-- keliru: browser membaca <nomor> sebagai elemen -->
<p>Sintaksnya: <code>tugas selesai <nomor></code></p>

<!-- benar: kurung sudut ditulis sebagai entitas karakter -->
<p>Sintaksnya: <code>tugas selesai &lt;nomor&gt;</code></p>

Pada bentuk pertama, browser mencoba membaca <nomor> sebagai elemen bernama nomor — tanda penutup </code> tidak lagi berpasangan dengan benar dan contoh tampil berbeda dari maksud kita. Bentuk kedua memakai entitas karakter: &lt; untuk < dan &gt; untuk > — keduanya tampil sebagai kurung sudut biasa tanpa dibaca sebagai tag. Tanda > sebenarnya aman ditulis mentah; kita tetap menulis pasangannya sebagai entitas supaya kurung pembuka dan penutup terlihat seimbang di mata pembaca kode sumber. Aturan yang sama berlaku untuk & yang ditulis &amp;.

Elemen var dari chapter Code, Kbd, Samp, dan Var juga relevan di sini: ia bisa menandai placeholder seperti nomor pada contoh generik. Dokumentasi kita memilih menulis placeholder secara literal di dalam code supaya pembaca menyalin contoh apa adanya — cukup tepat untuk dokumentasi ringkas seperti ini.

Hasil pada Browser #

Blok perintah pemasangan tampil dalam huruf berjarak tetap dengan tiga barisnya tetap terpisah. Tombol Enter tampil dengan gaya bawaan browser, diikuti keluaran Tugas v1.0 sebagai contoh keluaran. Section Penggunaan memperlihatkan dua blok bertumpuk: ketikan pengguna, lalu balasan terminalnya — dua peran yang berbeda dan dua penanda elemen yang berbeda pula.

Inilah kedua section itu persis seperti hasil Bagian 4 — bandingkan rupa pre+code pada blok ketikan dengan pre+samp pada blok balasan:

Ringkasan Bagian 4 #

  • Blok perintah memakai pre+code; keluaran program pre+samp; tombol kbd; nama perintah dalam kalimat code inline.
  • Isi pre ditulis tanpa menjorok — whitespace di dalamnya dipertahankan persis oleh browser.
  • Tanda < pada contoh ditulis &lt; dan & ditulis &amp; supaya tidak dibaca sebagai tag.

Bagian berikutnya menutup Perintah dengan tabel ringkasan dan mengisi Konfigurasi.