Yliopiston etusivulle In English
Helsingin yliopisto
Kielenkäsittelyn ATK-palvelut

Yhteystiedot

Yleisen kielitieteen laitos
PL 9 (Siltavuorenpenger 20 A)
00014 HELSINGIN YLIOPISTO

Puhelin +358 (09) 1911 (vaihde)
Faksi +358 (09) 191 29307

Yksinkertainen tapa tehdä verkkosivuja: reStructuredText

Python-ohjelmointikieleen ja DocUtils-hankkeeseen liittyy reStructuredText -niminen (RST) tapa tehdä pelkillä tasalevyisillä merkeillä dokumentteja, esim. ohjelman funktioiden tai luokkien käyttöohjeita ja selostuksia. Ominaista RST:lle on se, että se sellaisenaan on varsin luettavaa ja siistiä esimerkiksi ohjelman kommenttina tai vaikkapa sähköpostin osana, mutta että se on rakenteinen ja noudattaa tarkkoja sääntöjä, joiden perusteella RST-muotoinen teksti voidaan muuntaa toisiin muotoihin vapaasti saatavilla olevilla ohjelmilla.

reStructuredText -muoto

RST-muoto on dokumentoitu DocUtils -hankkeen sivuilla, ks. http://docutils.sourceforge.net/rst.html, josa on kolme erilaajuista ohjetta, joissa muoto kuvaillaan sekä esimerkein että määritelmien avulla. Muutamalla pääsäänöllä selviää aika pitkälle, tämänkin sivun lähdekoodina on .rst -muotoinen teksti.

  • Otsikot alleviivataan ja koko sivun otsikko yleensä sekä alleviivataan että samanlainen viivaus laitetaan otsikon yläpuolelle. Viivausten pitää olla täsmälleen samanmittaisia kuin otsikonkin (siis RST-dokumentin pitää näyttää siistiltä ollakseen oikeanmutoinen). Alleviivauksina käytetään siinä tarkoituksessa siistiltä näyttäviä merkkejä kuten =, - tai +.
  • Kappaleiden välissä on tyhjä rivi. Tavalliset kappaleet aloitetaan vasemmasta reunasta, sillä sisentäminen merkitsee sitä, että XHTML:ssä tai muussa muunnetussa muodossa teksti sisennettäisiin erityisesti.
  • Vahvennukseen käytetään tähtiä ennen ja jälkeen vahvennettavien sanojen. Yksi tähti kursivoi, kaksi lihavoi.
  • URL-osoitteet voi kirjoittaa sellaisenaan, niin niistä tulee linkkejä. Vähän enemmän vaivaa tarvitaan, jos halutaan HTML:n kaltaisia piilolinkkejä, mutta niistä em. dokumenteissa enemmän.
  • Ns. ranskalaisia viivoja (bullets) saa, kun laittaa rivin alkuun miinusmerkin ja välilyönnin. Jatkorivit sisennetään samaan linjaan, siis kahdella välilyönnillä.

Emacsin rst-mode

Venuksen Emacsissa on valmiiksi ladattuna RST-muotoisia dokumentteja varten laadittu rst-mode, joka tukee RST-dokumenttien laatimista. Käyttäjän täytyy kuitenkin luultavasti itse huolehtia siitä, että Emacs huomaisi, että .rst -loppuinen tiedostonnimi kertoo, että tiedoston sisältö on RST-muotoista. Seuraavat ~/.emacs tiedostoon sijoitettavat rivit hoitavat tämän (ja muutaman muunkin asian):

(setq auto-mode-alist
    (append
     (list
      '("\\.rst" . rst-mode)
      '("\\.xhtml" . nxml-mode)
      '("\\.xml" . nxml-mode)
      '("\\.xsl" . nxml-mode)
      '("\\.shtml" . sgml-mode)
      '("\\.html" . sgml-mode))
     auto-mode-alist))

Seuraavat rivit samassa paikassa huolehtivat siitä, että Emacs jakaa pitkiä rivejä kirjoitettaessa, kuten yleensä toivotaan:

(setq text-mode-hook
  '(lambda () (auto-fill-mode 1)))

RST-muotoisen dokumentin muuntaminen

Jos tekee verkkosivua, sen voi tehdä RSR-muotoisena XHTML-muotoisen sijasta ilman, että tarvitsee tehdä itse mitään. Ne Makefile -tiedostot, jotka skripteillä kopioidaan hoitavat tarvittavat muunnokset automaattisesti edellyttäen, että ne ovat ajantasaisia ja käyttävät /web/ling/util/MK/make-1.07.mk -versiota. Silloin siis RST-muotoisesta tiedostosta tehdään ensin XHTML-versio ja se koristellaan normaalisti SHTML-muotoiseksi.

Jos on itse tarvis tehdä XHTML-tiedosto RST-muotoisesta tiedostosta, se sujuu komennolla:

rst2html --initial-header-level sivu.rst sivu.xhtml

RST-muotoisesta tiedostosta voidaan myös tehdä LaTeX-muotoinen tiedosto komennolla rst2latex, josta saa ohjeita helposti arvattavalla tavalla:

rst2latex --help

Vastaava keino on toki tarjolla rst2html -ohjelmalle.