ReStructuredText:Buku Pengenalan Asas/Buku Pengenalan Asas

Dokumen ini ialah pengenalan tak formal kepada ReStructerdText (atau reStructuredText). Bahagian Selepas ini? di bahagian bawah mengandungi pautan-pautan ke sumber-sumber lain termasuk satu rujukan formal.

Senarai

Senarai terdapat dalam tiga bentuk utama: enumerated (bernombor), bulleted (titik) dan definitions (definisi). Dalam semua kes senarai, anda boleh meletakkan sebanyak subperenggan, subsenarai dll., yang anda mahu, selagi sisi kiri perenggan sebaris dengan baris pertama teks item senarai.

Senarai perlu bermula dengan perenggan baharu – yakni senarai perlu hadir hanya selepas baris kosong.

Senarai bernombor (angka, huruf atau angka romawi)

Mulakan baris dengan nombor atau huruf diikuti noktah ".", tanda kurungan kanan ")" atau di kelilingi tanda kurungan "( )" – apa jua bentuk yang anda berasa selesa. Kesemua bentuk ini diterima:

    1. nombor

    A. huruf besar
       dan ia boleh merangkumi banyak baris

       dengan dua perenggan!!

    a. huruf kecil 

       3. dengan subsenarai yang mula dengan nombor lain
       4. pastikan nombor berada dalam jujukan betul!

    I. nombor romawi besar

    i. nombor romawi kecil 

    (1) nombor, lagi

    1) dan lagi

Hasil:

1. nombor

A. huruf besar
dan ia boleh merangkumi banyak baris

dengan dua perenggan!!

a. huruf kecil

3. dengan subsenarai yang mula dengan nombor lain
4. pastikan nombor berada dalam jujukan betul!

I. nombor romawi besar
i. nombor romawi kecil
(1) nombor, lagi
1) dan lagi

Senarai titik

Sama seperti senarai bernombor, mulakan baris dengan aksara titik – sama ada "-", "+" atau "*":

 * titik menggunakan "*"

    - subsenarai menggunakan "-"

        + satu lagi subsenarai 

    - satu lagi item

Hasil:

titik menggunakan "*"
- subsenarai menggunakan "-"
  - satu lagi subsenarai
satu lagi item

Nota penterjemah: Paparan titik tidak berubah kerana hambatan pada format wiki

Senarai definisi

Berlainan dengan dua senarai di atas, senarai definisi terdiri daripada nama, dan takrif nama itu. Format senarai definisi adalah seperti berikut:

    istilah
      Senarai definisi mengaitkan nama dengan definisinya

    ''bagaimana''
      Istilah merupakan frasa satu baris, dan definisinya terdiri daripada satu atau lebih 
      perenggan ataupun unsur badan, yang terengsot relatif kepada istilah. Baris kosong 
      tidak dibenarkan di antara istilah dan definisi.

Hasil:

istilah

Senarai definisi mengaitkan nama dengan definisinya

bagaimana

Istilah merupakan frasa satu baris, dan definisinya terdiri daripada satu atau lebih perenggan ataupun unsur badan, yang terengsot relatif kepada istilah.
Baris kosong todak dibenarkan di antara istilah dan definisi.

Prapemformatan (sampel kod)

Untuk memuatkan teks prapemformatan, akhiri perenggan sebelumnya dengan "::". Blok prapemformatan diakhiri apabila teks pulang kepada aras pengengsotan sebagai perenggan yang hadir sebelum blok prapemformatan. Misalnya:


  Contoh::

      Ruang putih, baris baharu, baris kosong, dan semua jenis penanda  
        (seperti *ini* atau \ini) dikekalkan oleh blok literal.
    Tengok, saya telah gugurkan satu aras pengengsotan
    (tetapi tak berapa dalam)

  tiada lagi contoh

Hasil:

Contoh:

Ruang putih, baris baharu, baris kosong, dan semua jenis penanda

(seperti *ini* atau \ini) dikekalkan oleh blok literal.

Tengok, saya telah gugurkan satu aras pengengsotan
(tetapi tak berapa dalam)

tiada lagi contoh

Perhatikan sekiranya perenggan hanya mengandungi "::", ia akan dibuang daripada output:

  ::

      Ini teks prapemformatan, dan 
      perenggan "::" terakhir dibuang

Hasil:

Ini teks prapemformatan, dan
perenggan "::" terakhir dibuang

Bahagian

Gunakan pengepala bahagian bagi mengasingkan teks panjang ke dalam bahagian lebih kecil. Pengepala bahagian adalah sebaris teks (satu atau lebih perkataan) dengan hiasan: tanda baris bawah, atau tanda baris bawah dan tanda baris atas (overline) seiring, dengan tanda sempang "-----", tanda sama dengan "======", tilde "~~~~~" atau mana-mana aksara bukan angka abjad = - ` : ' " ~ ^ _ * + # < > yang anda berasa selesa. Hiasan tanda baris bawah tunggal berlainan daripada tanda baris bawah yang seiring dengan tanda baris atas yang menggunakan aksara yang sama. Tanda baris, sama ada bawah atau atas, perlu sama panjang dengan teks tajuk. Gunakan tanda-tanda ini secara tekal, oleh sebab semua bahagian ditandai dengan gaya hiasan yang sama dan dianggap seperti berada pada aras yang sama:

  Bab 1 Tajuk
  ===========

  Bahagian 1.1 Tajuk
  ------------------

  Subseksyen 1.1.1 Tajuk
  ~~~~~~~~~~~~~~~~~~~~~~

  Bahagian 1.2 Tajuk
  ------------------

  Bab 2 Tajuk
  ===========

Ini menghasilkan struktur berikut, yang diperikan dengan pseudo-XML mudah:

  <?xml version="1.0" encoding="UTF-8"?>

    <section>
        <title>
            Bab 1 Tajuk
        <section>
            <title>
                Bahagian 1.1 Tajuk
            <section>
                <title>
                    Subseksyen 1.1.1 Tajuk
        <section>
            <title>
                Bahagian 1.2 Tajuk
    <section>
        <title>
            Bab 2 Tajuk

(Pseudo-XML menggunakan pengengsotan bagi penyarangan dan tidak mempunyai tag pengakhiran. Output terproses sebenar tidak dapat dipaparkan, sama dengan contoh-contoh lain, kerana bahagian tidak boleh wujud di dalam petikan blok).

Perhatikan yang pengepala bahagian disediakan sebagai sasaran pautan, dengan hanya menggunakan nama masing-masing. Untuk memaut kepada pengepala #SenaraiSenarai, saya tulis "Senarai_". Jika pengepala mempunyai ruang seperti yang terdapat pada Gaya Teks, kita perlu gunakan tanda petikan pada pengepala seperti ini "`Gaya Teks_`".

Tajuk/Tajuk kecil Dokumen

Tajuk dokumen keseluruhan berlainan daripada tajuk-tajuk bahagian dan diformatkan berlainan sedikit (misalnya, perisian penulis HTML memaparkannya sebagai pengapal tengah secara lalai).

Bagi menandakan tajuk dokumen dalam ReStructuredText, gunakan hiasan unik pada permulaan dokumen. Bagi menandakan tajuk kecil dokumen, gunakan satu lagi hiasan unik betul-betul selepas tajuk dokumen. Contoh:

    ================
     Tajuk Dokumen
    ================
    --------------
     Tajuk kecil
    --------------

    Tajuk Bahagian
    ==============

    ...

Perhatikan bahawa kedua-dua "Tajuk Dokumen" dan "Tajuk Bahagian" menggunakan tanda dengan, akan tetapi merupakan gaya yang berlainan antara satu sama lain. Teks tajuk yang menggunakan tanda garis bawah dah garis atas (tetapi tidak tanda garis bawah sahaja) boleh diengsotkan atas sebab-sebab estetika.

Imej

Untuk memuatkan imej ke dalam dokumen, anda perlu mengguna direktif `image

Contoh:

  .. image:: File:Biohazard symbol.svg

menghasilkan:

Bahagian <codeFile:Biohazard symbol.svg menandakan fail imej yang anda mahu letakkan ke dalam dokumen. Tidak ada hambatan terhadap penggunaan imej (format, saiz, dll). Jika imej itu disasarkan untuk paparan HTML dan anda berniat membekalkan maklumat tambahan, anda boleh masukkan:

  .. image:: File:Biohazard symbol.svg
     :height: 100
     :width: 200
     :scale: 50
     :alt: teks pilihan

Selepas ini?

Buku pengenalan asas ini memperkenalkan ciri-ciri yang sering terjumpa dengan ReStructuredText, akan tetapi terdapat banyak lagi perkara yang perlu dijelajahi. Dokumen rujukan pengguna, [bahasa Inggeris] Quick reStructuredText merupakan tempat yang baik untukselepas ini. Untuk mendapatkan perincian lengkap, pergi ke reStructuredText Markup Specification (Spesifikasi Penanda reStructuredText) .

Lihat juga

HTML
HTML5
Python di Wikipedia

Pautan luar

Laman Docutils di Sourceforge.net
Laman rasmi Python