Markdown ja pandoc - tekstipohjaisen tieteellisen kirjoittamisen työvirta

research
open science
git
pandoc
Tekijä

Markus Kainu

Julkaistu

15. lokakuuta 2013

Tässä kirjoituksessa esitellään tekstipohjainen työvirta digitaalisten tekstien kirjoittajalle, joka haluaa tehdä yksinkertaiset asiat yksinkertaisesti ja keskittyä monimutkaisten asioiden monimutkaisuuteen.

Digitaalisuus ja MS Wordin kuolema

Skottilaisen scifi-kirjailijan Charles Strossin lauantaina julkaisema blogiposti Why Microsoft Word must Die on herättänyt vilkasta keskustelua blogin kommenttiosiossa, ja tekstiä on jaettu ahkerasti sosiaalisessa mediassa viime päivinä. Stross on läpensä kyllästynyt Microsoftin tekstinkäsittelyohjelman yleiseen epätarkoituksenmukaisuuteen, tekniseen takapajuisuuteen sekä ansaitsemattomaan valta-asemaan ja haluaa sen kuolevan.

Microsoft Word is a tyrant of the imagination, a petty, unimaginative, inconsistent dictator that is ill-suited to any creative writer’s use. Worse: it is a near-monopolist, dominating the word processing field. Its pervasive near-monopoly status has brainwashed software developers to such an extent that few can imagine a word processing tool that exists as anything other than as a shallow imitation of the Redmond Behemoth. But what exactly is wrong with it?

Stross kirjoittaa ansiokkaasti siitä, mikä kaikki ohjelmassa on vialla kirjoja kirjoittavan ammattilaisen näkökulmasta. Tieteellisen kirjoittamisen näkökulmasta MS Wordissä on vialla huomattavasti useampi seikka kuin mihin Stross puuttuu, mutta silti sillä on yhä vankka asema myös tieteellisen kirjoittamisessa.

Wordin suosion ja kelvottomuuden ydin on sen WYSIWYG, eli What You See Is What You Get (mitä näet, sitä saat) -tyyppinen käyttöliittymä. Useat ihmiset haluavat edelleen hahmottaa tekstinsä vasten valkoista A4-koodin paperia, vaikka yhä useampi teksti julkaistaan vain digitaalisessa muodossa (blogi,e-kirja,www-sivu, tms.) tai se tullaan taittamaan uudelleen ennen paperille tulostamista. Tämä on tietysti seurausta laajemmasta tiedonvälityksen digitalisoitumisesta, jota ei ole tarpeen tässä laajemmin käsitella kuin vain todeta että MS Wordin What You See Is What You Get -lupaus pitää paikkansa koko ajan yhä harvemmin. Kirjoittajat tuottavat tekstejä yhä laajemmalle kirjolle julkaisualustoja, mikä tarkoittanee MS Wordille nopeaa kuolemaa ja siihen luottaville kirjoittajille lisääntyviä ongelmia.

Lähdekoodiajattelu tieteellisessä kirjoittamisessa

Tämä blogipäivitys valmistaa lukijaansa Wordin kuolemaan esittelemällä nokkelan lähestymistavan digitaaliseen kirjoittamiseen. (mikäli kirjoitat käsin tai mekaanisella kirjoituskoneella et tule hyötymään tästä) Kutsun sitä lähdekoodiajatteluksi kirjoittamisessa ja ajattelun ydin on siinä, että kirjoittaja laatii tekstistä tekstimuotoisen lähdekoodin, joka käännetään kulloinkin tarvittavaan asiakirjaformaattiin. Tässä esimerkissä teksti kirjoitetaan markdown-merkintäkielellä ja käännetään pandoc-dokumentinkääntäjällä haluttuun julkaisuformaattiin, joka voi olla esim:

Kun tekstistä on olemassa tekstimuotoinen lähdekoodi täytyy kirjoittajan ylläpitää vain tätä yhtä tekstiä ja kaikki muut formaatit on käännettävissä tästä lähteestä tarpeen mukaan. Tekstimuotoinen lähdekoodi luo puitteet myös kunnollisen versionhallinnan, kuten git:in käytölle. Sillä on myös monia muita etuja, joista kenties myöhemmissä kirjoituksissa lisää.

Tekstipohjaisen kirjoittamisen ohjelmistoympäristö

Tekstin kirjoittamiseen tietokoneella vaaditaan vain tekstieditori, joista muistio/notepad lienee Windows-käyttäjille tutuin. Wikipediassa on kattava lista editoreista, mutta hyvään alkuun pääsee Windowsissa notepad++:lla ja OS X:ssä esim. Aquamacs-emacs-pohjaisella editorilla. Linux-jakeluiden oletuseditorit ovat aivan kelpoja.

Markdown on tekstipohjainen merkintäkieli, joten sen kirjoittaminen ei vaadi kuin tekstieditorin. Markdown-muotoisen lähdekoodin kääntämiseen haluttuun formaattiin tarvitaan jo aiemmin mainittu pandoc, jota kehittää aktiivisesti Berkeleyn yliopiston filosofian professorin John MacFarlane. Mikäli haluat kääntää tekstin tieteellisissä julkaisuissa suosittuun LaTeX-formaattiin, niin sinun tulee asentaa koneellesi myös LaTeX. Alla on ohjeet sekä pandocin että latexin asentamiseen:

Seuraava esimerkki perustuu uusimpaan pandocin versioon pandoc 1.12.0.2 (2013-09-20).

Esimerkki tieteellisen tekstin lähdekoodista

Seuraavassa esiteltävä minimaalinen esimerkki sisältää:

  1. julkaisun tekstin markdown-muodossa sekä
  2. viitattujen julkaisujen bibliografiset tiedot BibTeX-muodossa.

1. teksti markdown-muodossa

Tekstin alussa on YAML-muotoinen metadata-osio, johon tulee dokumentin metatiedot. Muilta osin teksti noudattelee markup-syntaxia lisättynä kahdella matemaattisella kaavalla sekä erityyppisillä lähdeviittauksilla kahteen artikkeliin. Merkintäkieli on helppolukuista myös lähdekoodi-muodossaan. Tässä demossa lähdeviitetiedoston nimi on teksti.md.



---
title:  'Esimerkkiteksti kirjoitettuna markdown-merkintäkielellä'
author: Markus Kainu
affiliation: Turun yliopisto
date: Lokakuu 2013
bibliography: bibtex.bib
lang: finnish
...

# Suhteellisuusteoriasta ja Higgsin bosonista

## Suhteellisuusteoriasta

Lorem ipsum[^1] @einstein1935can dolor sit amet, consectetur adipiscing elit. Etiam at augue et quam placerat tristique [s. 12-15, @einstein1935can]. 

$e = mc^2$

Vestibulum ante ipsum [-@einstein1935can] primis in faucibus orci luctus et ultrices posuere cubilia Curae; Mauris imperdiet sem odio, at pharetra mauris congue dignissim.

![Massa aiheuttaa poikkeaman avaruuden geometriassa](http://upload.wikimedia.org/wikipedia/commons/2/22/Spacetime_curvature.png)

[^1]: Alaviitteen teksti on tässä.

## Higgsin bosonista

Donec tortor justo, venenatis sodales fermentum ut, eleifend sit amet lorem. Curabitur rutrum faucibus leo, nec porttitor est consequat sit amet. [@lee1977weak]

![Tiettyjen partikkeleiden välisten suhteiden standardi-mallin mukainen tiivistelmä](kuvat/higgs.png)

Lorem ipsum dolor @lee1977weak [s. 35] sit amet, consectetur adipiscing elit. Etiam at augue et quam placerat tristique. 

$M_Z=\frac{v\sqrt{g^2+{g'}^2}}2$

Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Mauris imperdiet sem odio, at pharetra mauris congue dignissim. Donec tortor justo, venenatis sodales fermentum ut, eleifend sit amet lorem. Curabitur rutrum faucibus leo, nec porttitor est consequat sit amet.

# Taulukot

Table: Einsteinin lapset

Syntymäaika Etunimet        Sukunimi    Sukupuoli
---------   --------        --------    ----------
14.05.1904  Hans, Albert    Einstein    mies
28.06.1910  Eduard          Einstein    mies

*Lähde: [wikipedia](http://fi.wikipedia.org/wiki/Albert_Einstein#Einsteinin_avioliitot)*


# Lähdeviitteet

2. lähdeviitteet BiBTeX-muodossa

Kenties yksinkertaisin tapa käyttää lähdeviitteitä on LaTeX-ladontajärjestelmästä tuttu BibTeX-muoto. Viitteet on mahdollista viedä kaikista viitteidenhallintaohjelmista ko. muotoiseen tekstitiedostoon. Google Scholar -palvelun hakutuloksissa on mm. suora linkki osuman bibliografisten tietojen lataamiseen BibTeX-muodossa. Tässä demossa lähdeviitetiedoston nimi on bibtex.bib ja se näyttää seuraavalta:

@article{einstein1935can,
title={Can quantum-mechanical description of physical reality be considered complete?},
author={Einstein, Albert and Podolsky, Boris and Rosen, Nathan},
journal={Physical review},
volume={47},
number={10},
pages={777},
year={1935},
publisher={APS}
},

@article{lee1977weak,
title={Weak interactions at very high energies: The role of the Higgs-boson mass},
author={Lee, Benjamin W and Quigg, Chris and Thacker, Harry B},
journal={Physical Review D},
volume={16},
number={5},
pages={1519},
year={1977},
publisher={APS}
}

Dokumentin kääntäminen pandoc-ohjelmalla

Pandoc-ohjelmaan ei ole olemassa graafista käyttöliittymää, vaan komennot tulee ajaa ns. komentorivissä. Windowsissa komentorivi voi olla hankalasti löydettävissä, mutta oheinen Jyväskylän yliopiston ohje auttaa asiassa: Komentorivit Windowsissa: Command Prompt. OS X:ssä komentorivin saa auki klikkailemalla: Applications>Utilities>Terminal. Linuxissa pikanäppäin Ctrl + Alt + tavaa päätteen.

Kun olet avannut komentorivin, sinun tulee vaihtaa hakemistoksi se hakemistoksi, jossa lähdekoodisi sijaitsee. Mikäli se on kansio essee työpöydällä, niin oikea komento voisi olla cd desktop/essee. Komentorivin komennot eroavat eri käyttöjärjestelmissä hieman, joten katso apua täältä: Selviytymisopas: Komentorivin käyttö tai käytä googlea.

Kun olet saanut navigoitua itsesi oikeaan hakemistoon komentorivillä tulee sinun enää syöttää komento, joka kääntää lähdekoodin haluamaasi formaattiin. Erityisen yksinkertaisissa käännöksissä riittää yleensä pandoc lahdekoodi.md -o haluttu_formaatti.xxx. Pandocin ohjeista löytyy miltei rajaton määrä ohjeita kääntämisen hienosäätämiseen. Alla on komennot yleisimpiin käännöksiin siten, että myös matemaattiset kaavat sekä lähdeviitteet generoituvat käännettäessä.


# latex-pdf -muotoon
pandoc teksti.md -o teksti.pdf --toc --number-section --latexmathml --filter pandoc-citeproc
# .html-muotoon
pandoc -s teksti.md -o teksti.html --toc --number-section --latexmathml --filter pandoc-citeproc
# .odt-muotoon
pandoc teksti.md -o teksti.odt --toc --number-section --latexmathml --filter pandoc-citeproc
# .docx-muotoon
pandoc teksti.md -o teksti.docx --toc --number-section --latexmathml --filter pandoc-citeproc
# .epub-muotoon
pandoc teksti.md -o teksti.epub --toc --number-section --latexmathml --filter pandoc-citeproc

Lataukset

Lähdekoodi, viitetiedot, kuvat ja komennot zipattuna

Zipatussa paketissa on lähdeteksti (teksti.md), viitteet (bibtex.bib), pandoc-komennot (komennot.md) sekä kansio kuvat, jossa kuva higgs.png. Toinen kuva tulee suoraan wikipediasta.

Esimerkkiteksti eri formaateissa

html-käännös ilman tyylitiedostoa näyttää nykypäivän silmään luotaantyöntävältä ja sitä voi ehostaa esim. tämän css-tiedoston avulla: markuskainu.fi/material/css/article.css. Voit lisätä sen lähdekoodiin vaikkapa metatietojen alle oheisella koodilla

<link href="https://markuskainu.fi/material/css/article.css" rel="stylesheet" type="text/css" title="compact"></link>

Muotoiltu html-muotoinen teksti näyttäisi sitten tältä: teksti_css.html

Lopuksi

Kirjoituksessa kuvattu työvirta ei tietenkään ole virheetön saati ns. valmis, mutta toimii hyvin jo tällaisenaan. Aivan erityisen hyödylliseksi kuvatun kaltainen työvirta tulee, mikäli tieteellinen tutkimus sisältää laskennallista analyysiä, jonka tuloksia (taulukoita, kuvioita) tekstissä esitellään. Mm. R-kielessä on olemassa erinomainen ekosysteemi laskennallisen analyysin ja sitä kuvaavan tekstin kirjoittamiseen rinnakkain yhteen tekstiin. Tähän ns. toistettavan analyysin lähdetymistapaan voi tutustua englanniksi juuri julkaistussa kirjassa Xie, Yihui. 2014. Dynamic Documents with R and Knitr (kirjan lähde githubissa) tai suomeksi vaikka osoitteessa: markuskainu.fi/workshop/toistettava/. Asiaa käsiteltäneen myös tässä blogissa syksyn aikana.

Kysymyksiä ja kommentteja rohkeasti tuohon alapuolelle!

Uudelleenkäyttö

Viittaus

BibTeX-viittaus:
@online{kainu2013,
  author = {Kainu, Markus},
  title = {Markdown ja pandoc - tekstipohjaisen tieteellisen
    kirjoittamisen työvirta},
  date = {2013-10-15},
  url = {https://markuskainu.fi/posts/2013-10-15-markdown-pandoc-tieteellinen-teksti},
  langid = {fi}
}
Viitatkaa tähän teokseen seuraavasti:
Kainu, Markus. 2013. “Markdown ja pandoc - tekstipohjaisen tieteellisen kirjoittamisen työvirta.” October 15, 2013. https://markuskainu.fi/posts/2013-10-15-markdown-pandoc-tieteellinen-teksti.