Om reStructured Text, rST

Innholdsfortegnelse

1   Innledning

Dette er et eksempeldokument for rST.

Kildefilen ligger på http://folk.uio.no/kjell/rst-mal.rst.

Det er lett å få med både en innholdsfortegnelse og seksjonsnummerering av kapittler og avsnitt, se over. Linjer som starter med to punktum er magiske se også fotnotene.

Dokumentasjonen finner du på http://docutils.sourceforge.net/docs/user/rst/quickstart.html

Den fullstendige referansen er http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

1.1   Hvordan installere nødvendig programvare På UiO:

For å skrive RST og kompilere koden til html eller pdf trenger man noe programvare. Her er verktøyene man kan bruke etter installasjonen:

rst2html            rst2odt             rst2s5              rstpep2html
rst2latex           rst2odt_prepstyles  rst2xetex
rst2man             rst2pseudoxml       rst2xml

1.2   RST-installasjon på Fedora23

[root@jobb ~]# dnf install docutils
Package             Arch       Version          Repository   Size
===================================================================
Installing:
python-docutils     noarch     0.12-0.3.20140510svn7747.fc23   fedora  1.5 M
python-pillow       x86_64     3.0.0-3.fc23                    updates 559 k

rst2pdf kommer ikke automastisk med og må installeres separat sammen med 4 andre pakker:

[root@jobb ~]# dnf install rst2pdf
Package             Arch      Version         Repository       Size
=====================================================================
Installing:
python-pdfrw        noarch    0.1-5.fc23      fedora           67 k
python-pygments     noarch    2.0.2-3.fc23    updates         1.6 M
python-reportlab    x86_64    3.1.8-5.fc23    fedora          1.2 M
python-simplejson   x86_64    3.5.3-3.fc23    fedora          190 k
rst2pdf             noarch    0.93-6.fc23     fedora          304 k

1.3   Bruk av RST etter installasjon

$ rst2html.py rst-mal.rst > rst-mal.html

Det er også mulig å få laget ei latex-fil for f.eks å generere .ps-fil eller .pdf-fil senere. med rst2latex.

$ rst2pdf rst-mal.rst >rst-mal.pdf

Denne feilet og laget en tom fil. Må feilsøke..

2   Ting og merking i praksis

2.1   Avsnitt og lister

Her er et avsnitt. Det er skilt fra det neste med ei blank linje.

NB! Uten blanke linjer får du heller ikke linjeskift jf. http://folk.uio.no/kjell/rst-mal.html#det-som-ikke-er-anbefalt-eller-mulig

Under her lager jeg ei liste i to nivå. Merk den tomme linja etter første punkt og før lista:

  • punkt A i en liste
      1. Ei underliste, punkt 1 - 2. punkt 2
  • punkt B punkt C

2.1.1   Underavsnitt

Trenger du flere nivåer gjør du det med forskjellige linjer under overskriften.

2.2   Uthevet skrift

Skal du ha noe i kursiv eller sterkt uthevet?

2.3   Skrive spesialtegn

Å skrive stjerner (asterisk) kan gjøres rett frem med /usit/modell/*

2.4   Bilder

For å legge inn et bilde bruker du de magiske to punktum og kaller det med ordet image:

./usit/TSM/sumo-t.jpg

2.5   <pre>

  1. To kolon

    Preformatert tekst med magikken med to kolon her

    Dette er preformatert tekst.
    
    Den er indentert også og fortsetter helt ut avsnittet.
    

    Her er det slutt.

  2. Doble quotes-tegn for hver linje:

    Trenger du å skrive noe på en spesiell måte kan du det med doble quotes.

    Du må gjenta for hver linje da linjeskift ikke vil klare seg.

  3. Ved inntrykk i teksten

    Trolig er det mye lettere både å skrive og å lese tekst som er indentert i teksten slik.

    Dette brukes mye for sitater ol.

    Kommentar: Dersom du bruker emacs er det to kjekke funksjoner for å få til disse innrykkene i teksten. Det er:

    • ^ r t <et knippe blanke>
    • M-x fill-individual-paragraphs som virker på ei lang linje med et knippe blanke i starten av linja.

2.6   Fotnoter

Fotnoter[1] kommer med i html-dokumentet om de har de magiske to punktumene nederst, i kallet.

Det er også mulig med autonummererte fotnoter, se http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#auto-numbered-footnotes

Tester auto_fotnote [2] da de kan mikses. Her er nok [3] en fotnote. De automatiske får superscript i teksten, mens de manuelle kommer i firkant-parenteser.

2.7   Tabeller

Her er et eksempel på en tabell:

Header row, column 1 (header rows optional) Header 2 Header 3 Header 4
body row 1, column 1 column 2 column 3 column 4
body row 2 Cells may span columns.
body row 3 Cells may span rows.
  • Table cells
  • contain
  • body elements.
body row 4

2.9   Ikke klikkbar (anonym?) peker

Dersom du kun vil ha en http://folk.uio.no/kjell/ peker som IKKE er klikkbar må det gjøres slik: Med en underline foran pekeren som står i sitat-tegn

3   Filsync av innhold (deriblant RST) til Vortex

På UiO kan man bruke filsync for å lage dokumenter i rst eller andre formater og konverteres til Vortex artikler, forutsatt at de inneholder en tittel. Hvis de ikke inneholder tittel, blir de for tiden xhtml dokumenter

Se Filsync

4   Det ukjente

4.1   Referanser

Q: Hva er disse referanser for noe?

A: Trolig bare en peker ned i dokumentet.

De virker greit opp i innholdsfortegnelsen også.

5   Det som litt vanskelig eller ikke er anbefalt/mulig

5.2   Kun linjeskift

Dersom det er et linjeskift og ikke et avsnitt er det ikke lett.

Fra the reStructuredText Markup Specification:

"If the preservation of line breaks and/or other whitespace is important, literal blocks should be used"
[1]Merk at det ikke er noe kolon etter klammeparentesen her i fotnoten.
[2]Får se om det virker!
[3]Det er viktig å skrive fotnotene i rett rekkefølge uansett