Duurzaam auteurschap

Stel dat je een schrijfmethode zou hebben waarmee je zeker bent dat de bestanden waarin je schrijft binnen 10, 20 ... jaar nog leesbaar zullen zijn. Waarbij je die bestanden zelf naar eender welk formaat kan omzetten. Zonder daarbij afhankelijk te zijn van propriëtaire software (en je dus niets moet kopen).

En stel dat je om dat te realiseren enkel 10' moet besteden aan het bekijken van een eenvoudige syntax...

basisprincipes

principe 1: scheiden van inhoud/structuur en opmaak

Above all, avoid the urge to format.

Dit borduurt verder op het html/css verhaal dat tijdends de OPO informatiekunde al aan bod kwam.

Ter herhaling van dit principe een stokoude, maar nog steeds welsprekende presentatie over structuur aanbrengen met een tekstverwerker (openoffice.org): Gestructureerde tekst -- presentatie Andreas Bovens

Moet ik dan html (of xml) kunnen schrijven?

Hetzelfde verhaal als bij informatiekunde: er is een verschil tussen schrijfformaten en publicatieformaten. Html is een publicatieformaat, het wordt bij voorkeur gegenereerd niet geschreven. Via markdown bijvoorbeeld (cfr. infra).

Het is wel van belang om html (en ook css overigens) te kunnen corrigeren. Vandaar de aandacht in de 'schrijven voor het web' module van informatiekunde.

Een tweede reden waarom het interessant is om html/xml en css te begrijpen is dat het je helpt om structuur te kunnen terugvinden in webpagina's. Hier gaan we dieper op in tijdens sessie 9 "data scraping".

principe 2: duurzaam auteurschap

Duurzaamheid heeft te maken met het bewaren van bestanden op lange termijn. Elementen daarbij zijn, naast het scheiden van vorm en inhoud, aandacht voor de fragiliteit van formaten en het vermijden van propriëtaire formaten en software.

Onderstaande demo is gebaseerd op de workflow in http://programminghistorian.org. De visie uitgezet in de philosophy en principles paragrafen deel ik helemaal.

voordelen van platte tekst

  1. kan gelezen worden door elke computer
  2. kan gescynchroniseerd worden op al je toestellen
  3. kan naar zo goed als elk ander formaat worden omgezet
  4. is gegarandeerd in de toekomst nog leesbaar (beantwoordt aan de standaarden van langetermijnbewaring)
  5. is makkelijk te lezen en catalogiseren
  6. is een handig formaat voor datamining
  7. is een uitstekend formaat voor versiebeheer

markdown

markdown toepassingen

demo: een schrijf-workflow gebaseerd op platte tekst

welke applicaties hebben we nodig?

we publiceren in volgende formaten vanuit hetzelfde moederbestand

stroom

  1. folder en bestand .md openen in Sublime Text, atom.io of een andere editor
    • desgewenst kan je de markdown-versie van dit bestand downloaden en gebruiken
    • of je kan via pandoc een webpagina omzetten naar markdown en daarmee starten: $ pandoc -f html -t markdown http://informatiewijzer.be/methodologie_en_digitale_geletterdheid_japanse_studies -o mdg16.md
    • preview de html met
      • een aparte app zoals bijvoorbeeld Marked
      • atom.io markdown preview plugin
      • in de browser
  2. semantische elementen in het markdown bestand overlopen
    • titels
    • lijstjes
    • code, blockquote
    • voetnoten [^2]
    • zotero export (komt aan bod in sessie 7 op 22/3)
  3. publiceren in een html-omgeving (drupal)
    • genereer html via pandoc $ pandoc -o writing_workflow.html writing_workflow.md of $ pandoc -s --toc -o writing_workflow.html writing_workflow.md
    • of via stackedit (cfr.supra)
    • knip en plak de html (alles binnen de body tags)
    • of gebruik de drupal markdown filter, indien beschikbaar
  4. omzetten via pandoc naar mediawiki tekstformaat
    • $ pandoc -t mediawiki -o writing_workflow.txt writing_workflow.md
  5. omzetten naar pdf via pandoc met weergave van
    • toc (inhoudsopgave)
    • voetnoten
    • bibliografische referenties (komt aan bod in sessie 7 op 22/3)
    • $ pandoc -S -o writing_workflow.pdf writing_workflow.md -V geometry:margin=1in -N --toc --filter pandoc-citeproc
    • bekijk de pandoc documentatie om te zien waar de verschillende opties voor dienen
  6. maak van je markdown bestand een presentatie met reveal.js
    • met pandoc kan je slideshows in verschillende formatenproduceren
    • reveal.js kan je downloaden van github , hier is het lijstje met wat het kan en hier lees je de installatieprocedure
    • download folder
    • editeer de titelpagina van de presentatie in het bestand index.html
    • en koppel je markdown bestand
    • slides in bestand aangeven
    • bekijk het resultaat in je browser
    • je hoeft reveal.js zelf niet te installeren, je kan die ook als app op een gratis sandstorm.io account gebruiken
    • of de folder in zijn geheel opladen naar je eigen domein

Starting off in Markdown with Word-to-Markdown:

If there’s one thing I’ve learned trying to convert Word documents to Markdown, it’s that Markdown is not an alternative to traditional desktop formats. It’s an entirely different animal. It’s both machine- and human-readable, but more importantly, it forces you to author content openly, semantically, and for an internet-based world.

Next time you begin a new project for which the internet, not paper is the primary output, think twice before firing up that desktop publishing platform. You’ll gain more than mere semantics.

Aanpassingen template pandoc voor xelatex Japans

Om Japans te kunnen weergeven bij het genereren van een pdf via pandoc dien je te verwijzen naar de juiste fonts in een configuratiebestand van pandoc. Hoe een studente dit vorig jaar heeft opgelost kan je hier lezen.

Samengevat kan het in drie stappen:

  1. zet het standaard pandoc sjabloon om naar een bestand: $ pandoc -D latex > pandoc.template

  2. editeer dat bestand (pandoc.template dus) door regel 20 aan te passen. Het hoeft niet MS Mincho te zijn, je kiest een Japanse font op je toestel.

\else % if luatex or xelatex
  \ifxetex
    \usepackage{mathspec}
    \usepackage{xltxtra,xunicode,fontspec,xeCJK}
  \setCJKmainfont{MS Mincho}
  1. genereer de pdf, met als optie het aangepaste bestand

$ pandoc -o outputbestandsnaam.pdf --latex-engine=xelatex --template=pandoc.template inputbestandsnaam.md

Connectie met portfolio

Het uitwerken van een individuele portfolio is één van de rode draden door de sessies. Naast het aspect duurzaamheid komen hier ook deze twee principes te pas:

Oefeningen

  1. Het individuele log wordt in markdown geschreven.
  2. Installeer pandoc. Log de vragen en eventuele problemen die zich daarbij aandienen, én de oplossingen. Vergeet niet dat je voorgangers dat ook al gedaan hebben -- verwijzen mag ook.
  3. Zet (de broncode van) je wiki-artikel voor geschiedenis om naar markdown. Log de vragen en eventuele problemen die zich daarbij aandienen (weergave beelden bijvoorbeeld), én de oplossingen.
  4. Maak een e-book (e-pub formaat) van je groepspaper politiek.
  5. Voor wie durft: genereer een academisch ogende pdf van je wiki-artikel met pandoc; of zet je blogpost om in een presentatie met reveal.js.

Voor deze opdrachten is er geen aparte deadline.

[^2]: voor de gebruikers van sublime text is er een plugin voor pandoc voetnoten http://inlustre.net/2014/01/pandoc-referencing-for-sublime-text-3-a-plugin/