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 stel dat je om dat te realiseren enkel een open source applicatie moet installeren en 10' besteden aan het bekijken van een eenvoudige syntax...

We werken deze workflow uit in drie sessies:

20180213: leer Markdown kennen

20180220: teksteditor en Markdown

20180313: workflow gebaseerd op platte tekst en Markdown

 

Teksteditor

  • een computerprogramma waarmee onopgemaakte digitale tekst bewerkt kan worden. Een teksteditor wordt onderscheiden van een tekstverwerker, die tot doel heeft om opgemaakte tekst te maken.
  • een noodzakelijke tool als je schrijft voor het internet
  • Atom
  • sublime text (met plugins marked, evernote, pandoc, git)

formaat: platte tekst

  • In de informatica wordt met platte tekst bedoeld: tekst die uitsluitend bestaat uit letters, spaties, cijfers en leestekens.
  • Tekst die is voorzien van opmaak (vet, cursief, onderstreept, sub- en superscript alsook tabellen en afbeeldingen) is geen platte tekst.
  • Een aantal opmaaktekens zoals regelovergang (carriage return/line feed) en tabstop komen in platte tekst wel voor.

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 (pandoc)
  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

  • is geen taal of programma, enkel een conventie om semantische eenheden in een tekst aan te duiden, met eenvoudige syntax:
  • Markdown is een de facto standaard voor online schrijven geworden
  • Writing in this way liberates the author from the tool - je kan schrijven met eender welke editor (own your data)
  • Een markdown bestand kan als moederbestand dienen voor een breed gamma van documentformaten: wetenschappelijke artikels, wikis, syllabi, blog posts ...
  • leer Markdown kennen

Markdown toepassingen

Starting off in Markdown with Word-to-Markdown: Word to Markdown Converter

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.

Basisbegrippen en principes

  1. duurzaamheid
  2. gestructureerde tekst
  3. moederkopie in platte tekst formaat

1. Duurzaamheid

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 workflow is gebaseerd op http://programminghistorian.org. De visie uitgezet in de philosophy en principles paragrafen deel ik helemaal.

open standaarden

voordelen van platte tekst

cfr.supra

unix filosofie

2. Gestructureerde tekst

scheiden van inhoud/structuur en opmaak

Above all, avoid the urge to format.

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 negen "data scraping".

Markdown

cfr. supra

Schrijf-workflow gebaseerd op platte tekst en Markdown

Welke applicaties hebben we nodig?

  • sublime text (met plugins marked, evernote, pandoc, git) of een andere editor

  • terminal (iterm, terminal op Mac of powershell voor windows)

    The command line is a friendly place, once you get used to it.

  • pandoc 1 (met LaTeX, en de daarbij horende extensies voor Japans)

  • zotero

We publiceren in volgende formaten vanuit hetzelfde moederbestand

  • blogpost: html
  • academisch: pdf (met inhoudsopgave, bibliografische referenties en voetnoten)
  • wiki-artikel: mediawiki
  • presentatie: reveal.js
  • website: met mkdocs

stroom

  1. folder en bestand .md openen in Sublime Text, atom.io of een andere editor

    • 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
  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 5)
    • $ 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 formaten produceren
    • 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
  7. maak van je markdown bestanden een statische website

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:

  • own your data, eigenaar zijn en blijven van je gegevens, heeft niet alleen te maken met de locaties waarop die gegevens terechtkomen maar ook met (on)afhankelijkheid van propriëtaire formaten
  • “write on your own domain, syndicate everywhere" is een principe uit het IndieWeb dat goed aansluit bij deze workflow

Howto

De voorbije afleveringen van MDGJS zijn een aantal howto's aangemaakt die van pas zullen komen:

Oefeningen

  • Oefening in zelfredzaamheid: installeer pandoc op het platform dat je gebruikt. Indien installatie niet mogelijk is (op chromebook bijvoorbeeld) kan je dan online met pandoc aan de slag?
  • Gebruik pandoc om je wiki-artikel (OPO Geschiedenis van Japan) om te zetten naar markdown en genereer daaruit een academisch ogende pdf. Beschrijf de caveats en de oplossingen die je hebt gevonden.
  • Verwijs correct naar twee Japanse bronnen (een monografie en een artikel).

  1. http://johnmacfarlane.net/pandoc/installing.html ↩

  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/ ↩