Table Of Contents

Previous topic

Ekzempla artikolo en reStrukturitaTeksto

Next topic

Pitono kaj ...

Ek al ReStrukturitaTeksto

Aŭtoro:Richard Jones
Eldono:$5801 eo: 2$
Kopirajto:Tiu ĉi dokumento estas publike uzebla
Resumo:enkonduko al reStrukturitaTeksto Tiu ĉi dokumento estas Esperanta traduko de la dokumento A reStructuredText Primer.

La teksto sube enhavas ligilojn kiuj aspektas kiel “(koncizaref)”. Ili estas relativaj ligiloj, kiuj direktas al reStrukturitaTeksto koncize uzulreferenco. Se la ligiloj ne funkcias, bonvolu rigardi ĉefa konciza referenco dokumenton.

Note

Tiu ĉi dokumento estas neformala enkonduko al reStrukturitaTeksto. La Kio nun? sekcio suben ligas al ceteraj risurcoj, inkludante formalan referencon.

Strukturo

Je la komenco, mi diru ke “Strukturita Teksto” estas verŝajne ia misnomo. Ĝi estas pli kiel “Relaksita Teksto” kiu uzas iun konsekvencajn motivojn. Tiuj motivoj estas pritraktataj per HTML konvertilo por krei “Tre Strukturitan Tekston” kiun povas legi foliumilo.

La plej baza, rekonata motivo, estas alineo (koncizaref). Ĝi estas parto de teksto separita per malplenaj linioj (po unu sufiĉas). La alineoj devas havi la saman deŝovon – tio estas, la linioj estu ĉiuj ĉe maldekstra rando. Alineo kiu komencas deŝovon, estas konsiderata citita alineo. Ekzemple:

Jen estas alineo.  Ĝi estas sufiĉe
mallonga.

   Tiu ĉi alineo rezultos kiel deŝovita bloko de
   teksto, kutime uzata por citi alian tekston.

Tiu ĉi estas ankoraŭ unu.

Kio rezultas jene:

Jen estas alineo. Ĝi estas sufiĉe mallonga.

Tiu ĉi alineo rezultos kiel deŝovita bloko de teksto, kutime uzata por citi alian tekston.

Tiu ĉi estas ankoraŭ unu.

Stiloj de teksto

(koncizaref)

Ene de alineoj kaj de aliaj partoj de teksto, oni povas krome marki tekston kiel kursiva per “*kursiva*” aŭ grasa per “**grasa**”. Ĝi nomiĝas “enlinia markado”.

Se oni volas ion aperi en egallarĝa tiparo, oni uzu “``duoblaj malapostrofoj``”. Notu ke neniu plia pritrakto okazas ene de la duoblaj malapostrofoj – tiel steleto “*” k.a. postrestas solaj.

Se oni bezonos uzi unu el “specialaj” signoj en teksto, ĝi kutime funkcios senprobleme – reStrukturitaTeksto estas sufiĉe sprita. Ekzemple, tiu ĉi sola steleto * estas pritraktata ĝuste, kiel la steleto en la ekvacio: 5*6=30. Se oni tamen volas tekston *ĉirkaŭitan per steletoj* ne estu kursiva, tiam oni devas indiki ke la steleto estas nenio speciala. Oni faras tion aldonante deklivan strekon antaŭ ĝi, tiel “\*” (koncizaref), aŭ ĉirkaŭfermante ĝin per duoblaj malapostrofoj (enteksta laŭliteraĵo), kiel tiu ĉi:

``*``

Tip

Pensu pri la enteksta markado kiel pri formo de (krampoj) kaj uzu ilin sammaniere: tuj antaŭ kaj post la markata teksto. La enteksta markado mem (ĉirkaŭita de blankaĵoj) aŭ meze de vorto ne estos rekonita. Vidu marklingva specifo por ĉiuj detaloj.

Listoj

Listoj de elementoj estas trispecaj: numeritaj, bulsignitaj kaj difinlistoj. En ĉiuj listospecoj, oni povas uzi tiom da alineoj, sublistoj, ktp., kiom oni volas, nur dum la maldekstra rando de la alineo, aŭ alio, deŝovas same kiel la unua linio de teksto en la listoelemento.

Listoj ĉiam devas komenci novan alineon – kio signifas, ke ili devas aperi post malplena linio.

numeritaj listoj (numeroj, literoj aŭ romiaj nombroj; koncizaref)

Oni komencu linion per numero aŭ litero sekvata de punkto ”.”, dekstra krampo ”)”, aŭ ĉirkaŭitan per krampoj “( )” – kiuj pli taŭgas al oni. Ĉiuj subaj formoj estas rekonataj:

1. numeroj

A. majusklaj literoj
   kaj tie la listoelemento povas

   daŭri kelkaj liniojn kun du alineoj kaj pli!

a. minusklaj literoj

   3. kun sublisto komenciĝanta per alia numero
   4. zorgu tamen ke la numeroj estu en ĝusta vico!

I. majusklaj romiaj numeroj

i. minusklaj romiaj numeroj

(1) denove numeroj

1) kaj denove

Rezultas kiel (rimarku: la diversaj stiloj de numeritaj listoj ne ĉiam videblas ĉe ĉiu retumilo, kaj oni povas ne vidi tie ĉiujn efektojn):

  1. numeroj
  1. majusklaj literoj kaj tie la listoelemento povas

    daŭri kelkaj liniojn kun du alineoj kaj pli!

  1. minusklaj literoj
    1. kun sublisto komenciĝanta per alia numero
    2. zorgu tamen ke la numeroj estu en ĝusta vico!
  1. majusklaj romiaj numeroj
  1. minusklaj romiaj numeroj
  1. denove numeroj
  1. kaj denove
bulsignitaj listoj (koncizaref)

Same kiel numeritaj listoj, oni komencu linion per bulsigna litero – iu el “-”, “+” aŭ “*”:

* bulsignita listo uzanta "*"

  - sublisto uzanta "-"

    + eĉ ankoraŭ unu sublisto

  - sekva elemento

Rezultas kiel:

  • bulsignita listo uzanta “*”
    • sublisto uzanta “-“
      • eĉ ankoraŭ unu sublisto
    • sekva elemento
difinlistoj (koncizaref)

Male ol la du ceteraj, la difinlisto konsistas el kapvorto, kaj la difino de la kapvorto. La formo de la difinlisto estas jena:

kio
  Difinlistoj kunigas kapvorton kun difino.

*kiel*
  La kapvorto estas unulinia frazo, la difino estas unu aŭ pli da
  alineoj aŭ tekstoelementoj, deŝovitaj relative al la kapvorto.
  Malplenaj linioj estas malpermesitaj inter la kapvorto kaj la priskribo.

Rezultas kiel:

kio
Difinlistoj kunigas kapvorton kun difino.
kiel
La kapvorto estas unulinia frazo, la difino estas unu aŭ pli da alineoj aŭ tekstoelementoj, deŝovitaj relative al la kapvorto. Malplenaj linioj estas malpermesitaj inter la kapvorto kaj la priskribo.

Antaŭformatado (kodekzemploj)

(koncizaref)

Por enmeti antaŭformatitan, nepritraktendan tekstoblokon, finu la antaŭan alineon per “::” La antaŭformatita bloko finiĝas, kiam la deŝovo de la teksto revenas al nivelo de la alineo antaŭanta la antaŭformatitan blokon. Ekzemple:

Ekzemplo::

    Blankaĵoj, novliniaĵoj, malplenaj linioj, kaj ĉiuj specoj
      de markado (kiel *tiu ĉi* aŭ \tiu ĉi) konserviĝas ene de
      laŭliteraj blokoj.
  Rigardiu tie ĉi, mi eĉ malgrandigis la deŝovnivelon
  (sed ne tro multe)

neniu plia ekzemplo

Rezultas kiel:

Ekzemplo:

  Blankaĵoj, novliniaĵoj, malplenaj linioj, kaj ĉiuj specoj
    de markado (kiel *tiu ĉi* aŭ \tiu ĉi) konserviĝas ene de
    laŭliteraj blokoj.
Rigardiu tie ĉi, mi eĉ malgrandigis la deŝovnivelon
(sed ne tro multe)

neniu plia ekzemplo

Rimarku ke, se alineo konsistigas nur de “::” ĝi estos forigita de la eligo:

::

    Ĝi estas la antaŭformatita teksto, kaj
    la lasta "::" alineo estas forigita

Rezultas kiel:

Ĝi estas la antaŭformatita teksto, kaj
la lasta "::" alineo estas forigita

Sekcioj

(koncizaref)

Por dividi longan tekston en sekciojn, oni uzu sekciotitolojn. Tiuj estas unuliniaj tekstoj (unu aŭ pli da vortoj) kun ornamaĵo: nur substreko, aŭ substreko kune kun superstreko, per streketoj “-----”, egalsignoj “======”, tildoj “~~~~~~” aŭ iu el la ne-letercifera signo = - ` : ' " ~ ^ _ * + # < > kiu plej taŭgas al oni. Ornamaĵo kun nur substreko diferencas de sub- kaj superstreka ornamaĵo, uzanta la saman signon. La sub-/superstreko devas esti almenaŭ same longa kiel la titolteksto. Estu konsekvenca, ĉar ĉiuj sekcioj markitaj per la sama ornamstilo estas konsiderataj samnivelaj:

Titiolo de ĉapitro 1
====================

Titolo de sekcio 1.1
--------------------

Titolo de subsekcio 1.1.1
~~~~~~~~~~~~~~~~~~~~~~~~~

Titolo de sekcio 1.2
--------------------

Titiolo de ĉapitro 2
====================

Ĝi rezultas en la ĉi-suba strukturo, ilustrita per simpligita kvazaŭ-XML:

<section>
    <title>
        Titiolo de ĉapitro 1
    <section>
        <title>
            Titolo de sekcio 1.1
        <section>
            <title>
                Titolo de subsekcio 1.1.1
    <section>
        <title>
            Titolo de sekcio 1.2
<section>
    <title>
        Titiolo de ĉapitro 2

(Kvazaŭ-XML uzas deŝovon por indikado, kaj ne havas fin-etikedojn. Ne eblas montri la aktualan eligon, kiel ĉe aliaj ekzemploj, ĉar sekcioj ne povas ekzisti ene de blokcitaĵoj. Por konkreta ekzemplo, komparu la sekciostrukturon de fonta teksto de tiu ĉi dokumento, kaj pritraktita eligo.)

Rimarku, ke sekciotitoloj estas ankaŭ ligiloceloj, simple uzante ĝiajn nomojn. Ligante al la titolo Listoj, oni skribu “Listoj_”. Se la titolo enhavas spaceton, kiel ĉe stiloj de teksto, oni devas citi la titolon “`stiloj de teksto`_”.

Titolo/subtitolo de dokumento

La titolo de la tuta dokumento, direfencas de aliaj sekciotitoloj, kaj povas esti formatita iom alie (ekz. HTML konvertilo, normale montras ĝin kiel centrita titolo).

Por indiki la dokumentotitolon en reStrukturitaTeksto, uzu unikan ornamaĵon ĉe la komenco de la dokumento. Por indiki subtitolon de la dokumento, uzu alian unikan ornamaĵon tuj post la dokumentotitolo. Ekzemple:

=================
 Dokumentotitolo
=================
-----------
 Subtitolo
-----------

Sekciotitolo
============

...

Rimarku, ke ambaŭ “Dokumentotitolo” kaj “Sekciotitolo” uzas egalsignojn, sed ili estas apartaj kaj nerilataj stiloj. Teksto kun super- kaj sub-strekitaj titoloj (sed ne nur sub-strekitaj) povas esti aldonitaj por estetiko.

Bildoj

(koncizaref)

Por aldoni bildon en la dokumenton, oni uzu la image direktivon. Ekzemple:

.. image:: biohazard.png

rezultas kiel:

../_images/biohazard.png

La parto biohazard.png indikas dosiernomon de la bildo kiu aperu en la dokumento. Estas neniu limigo pri la aldonata bildo (rilate al formato, grandeco ktp.). Se la bildo estu en HTML, kaj oni volas aldoni kromajn informojn, oni povas skribi:

.. image:: biohazard.png
   :height: 100
   :width: 200
   :scale: 50
   :alt: kroma teksto

Vidu la detalan dokumentaron pri bildodirektivoj por pli da informoj.

Kio nun?

Tiu ĉi enkonduko priskribas nur la plej ĝeneralajn trajtojn de reStrukturitaTeksto, sed estas multe pli esplorinda. La manlibro reStrukturitaTeksto koncize estas bona sekva paŝo. Por kompletaj detaloj, bona celo [1] estas la specifo de reStrukturitaTeksto marklingvo.

Uzantoj kiuj havas demandojn, aŭ bezonas asiston kun Docutils aŭ kun reStrukturitaTeksto, skribu mesaĝon al la Docutils-uzantoj dissendolisto.

[1]Se tiu ĉi relativa ligilo ne funkcias, provu iri al ĉefdokumento: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.