Tools

Open Access Publishing at TUHH: Exemplary Step-by-step guide for a toolchain with TORE, GitLab, Sherpa Romeo and Zenodo

The following step-by-step guide is updated regularly and should be seen as a kind of living document. A more recent version, if available, can be viewed via the repository linked in the license note at the end of the post.

Publishing a paper as preprint would work as described in the following steps:

  1. You have to get an overview on possibilities to publish and open access sharing rights (further information on the websites of the TU library)
  2. Check the permissions of your journal or publisher where you would like to publish via Sherpa Romeo. Example for IEEE proceeding is:
Example for aggregated permissions of IEEE proceedings via Sherpa Romeo

Here you can see that preprints (research papers that are shared before peer review) are possible and which rules you have to follow. For example for CDC (Conference on Decision and Control) you can upload the preprint with a notice that this paper is submitted for review and afterwards you have to place a copyright notice and a DOI link of the IEEE finally published version. You are not allowed to publish the final version, just an author version with the copyright terms. See IEEE policy, section 3 for that.

  1. Create a repository for your publication in our gitlab instance: TUHH – Gitlab (private repo, a public repo can be seen here). In general you create

    • a repository for your paper
    • a repository for your software code (See Code Section)

Use the following scheme: Year-paper-conference-FirstSixWordsOfTitleOfYourPublication (e.g. 2021-paper-ECC-A-Gradient-Descent-Method-for-Finite) while the code is in the corresponding Year-code-TitleOfYourContribution repository.

  1. Have in mind to add references to supplimentary material in the readme.
  2. Add submission or copyright terms to your paper and create a prefinal pdf. You might keep some space (Where??) to place the preprint DOI for references.
  3. Open tore submission page with your personal account (more details via tore help).
  4. Select Publications with fulltext and click on manual submission
  5. The next pages collect metadata:
    • Title
    • Authors (Add an ORCID if possible, Add Prof Werner, for example). Clicking on the magnifier allows searching for entries. Validated entries are marked with a green arrow.
    • Select Language: English
    • Type: Preprint
    • Enter Abstract in English
    • Select TUHH Institute: Type E14 and by using the magnifier select the validated entry.
    • Go next
A click on the magnifier allows searching for entries
  1. Next page collects publisher metadata:
    • These information will be updated with the final version to be submitted for publication
    • Enter Date of issue: Todays date
    • Go next
  2. License details
    • License: Copyright should be selected
    • Supplemented by: Here you can add your Code DOI
    • Project: If you are working for a DFG program, you should reference it here
    • Funder: Here you should add DFG or BMWI as Funder
  3. Now you get your DOI.
    • Copy this DOI into your paper and compile it with this DOI. The DOI is booked but not finally registered. This will be done in the next steps
  4. Now, upload the pdf of your preprint
    • upload pdf
    • check filename (should be meaningful)
    • Set embargo date if neccessary
    • next
  5. Verfiy your submission and accept the license of TORE
  6. Your submission is nearly done. TUHH Library will check your submission. Either they accept it or ask you to change things. You will be emailed. Your entry is so to say, peer review on metadata level
  7. For now you are done. Further version have to be uploaded when the paper got accepted and you can upload the final author version to TORE. Please make sure that you reference the publisher DOI and add the correct credits to the paper.

Publish your software files related to your paper publication

You want to publish files like your source code, your data or videos in a save manner and cite them using a DOI?

The code you publish should be able to reproduce all figures you show in your publication by running one or multiple files which are than related to your figure. If your code uses special software or libraries to run, you should note them down in a dependancies and software section in a readme file of the repository. You should not include these files to your repository. Installation steps should be explained.

Than this is one way to go:

  1. Create a repository for your publication in our gitlab instance: TUHH – Gitlab. In general you create
    • a repository for your paper (See Paper Section)
    • a repository for your software code in https://collaborating.tuhh.de/ICS/ics-private/phd-students/papers (private repo) by using the following scheme: Year-code-conference-FirstSixWordsOfTitleOfYourPublication (e.g. 2021-code-ECC-A-Gradient-Descent-Method-for-Finite) while the paper is in the corresponding Year-paper-conference-TitleOfYourContribution repository.
  2. Upload your code by using git (You can use this repo already when starting to work on an idea: Repositories can be renamed and moved in the gitlab structure). Code should be cleaned up and except for dependancies and libraries selfcontaining. (Be careful on which branch to push, master gets automatically pushed to github, others not)
  3. Add a License file to the repo using templates: GPLv3 (Software) and CC-BY-SA (for all other media) and remove all lines after End of Terms and Conditions around line 625
  4. Add the following header lines to the beginning of each of your files. In references your refere to papers, software or tools you base on to cite them. Make sure that our license in compatible with the build on software/library/code.
```
%------
% Project: Name and Link
% Copyright: 
% License: 
% References:
% Authors:
%------

%---------------------------------------------------------------------------------------------
% For Paper, 
% "A Gradient Descent Method for Finite Horizon Distributed Control of Discrete Time Systems"
% by Simon Heinke and Herbert Werner
% Copyright (c) Institute of Control Systems, Hamburg University of Technology. All rights reserved.
% Licensed under the GPLv3. See LICENSE in the project root for license information.
% Uses an own implementation of the work of 
% "A. Vamsi and N. Elia, Design of distributed controllers realizable over arbitrary directed networks,
% IEEE Conference on Decision and Control, 2010."
% Author(s): Simon Heinke
%--------------------------------------------------------------------------------------------
```
  1. You also might want to enter a section in the Readme file on how to cite your work. Therefore you should include bibtex code for citing authors to reference your work in their publication. E.g.:
``` 
@misc{1606.01540,
    Author = {Greg Brockman and Vicki Cheung and Ludwig Pettersson and Jonas Schneider and John Schulman and Jie Tang and Wojciech Zaremba},   Title = {OpenAI Gym},
    Year = {2016},
    Eprint = {arXiv:1606.01540},
}
 ```

Example for Readme.md from Christian Hespe:

Example for a Readme.md file
  1. Create a repository at github.com/TUHH-ICS
    • with the same name as in gitlab
    • Give a short meaningful description
    • Select public
    • Click on create repository
    • Ask Lennart Heeren or Patrick Göttsch to grant you maintainer rights in that particular repository
    • Copy the SSH url from github
  2. Enable mirroring in gitlab
    • Switch to your private gitlab repository
    • Left menu -> Settings -> Repository -> Expand Mirroring repositories
    • Paste your github url in Input the remote repository URL
    • Modify it this way: ssh:// at the beginning and replace the colon after github.com with a slash. It should look like this now: ssh://git@github.com/TUHH-ICS/REPO_NAME
    • Klick on Detect host keys button
    • Select (although it does not seam to be clickable) in authentification method SSH Public Key
    • And select Mirror only protected branches. By default only the master branch will be pushed as it is.
    • Click on mirror repository to setup the mirror.
    • Now you have to click on the Copy ssh public key
Copy the ssh public key via mousclick on the copy item
  • After a click on the key…
    • go back to GitHub;, click on Settings > Deploy Keys > Add deploy key
    • Give it some title, paste the copied key in the key field and check Allow write access abd than click on Add key
    • Now you can trigger the mirroring by pushing or merging into the master branch in gitlab or manually in the gitlab repo mirroring settings page
  1. Uploading to Zenodo
    • Login to Zenodo using ** Log in with this credentials **
      • user: ics@tuhh.de
      • passwd: JJ^Q?…
    • Click on setting->github (1),
    • Click on Sync now button (2),
    • and enable the repository (3, located at the end of the list),
    • Then we go back to github and create a new release (4):
  • give a version tag like v1.0
  • give a meaningful title
  • and some description (will also be published by zenodo)
  • click on Publish Release
Click on „Publish release“ after assigning a tag, a title and a description

This automatically generates a zip of the code and this zip gets uploaded to zenodo, also automatically.

  1. Creating a DOI/Publishing
  • Back in Zenodo click on upload at the top of the page
Upload-Button
  • Here you find your software code already published
Published software code
  • Since not all metadata is available on github, you have to edit your entry
    • Click on the title opens the entry and shows a view as readers would see it.
    • You can click on edit to add or change metadata. The next view is organised in multiple sections:
      • Files: Here you can upload a new version manually. But normmaly you would choose a github release as the way to go.
      • Communities: Please select Hamburg University of Technology to reference this contribution to TUHH
      • Upload Type: Should already be Software
      • Basic Information:
        • Adjust the Title because the github repo name has been used. E.g.: Code for paper: Name of my marvellous paper
        • Authors: Clean up authors list; Lastname, Firstname – Hamburg University of Technology – Institute of Control Systems – ORCID
        • Add Prof Werner to this list: Werner, Herbert Hamburg University of Technology – Institute of Control Systems – 0000-0003-3456-5539
        • Add a meaningful Description
        • Version tag got automatically set
        • Language: Choose English
        • Give similar Keyword as you choose for your paper
      • License: All should be okay. The License is provided in the repository. Zenodo so far does not support GPLv3.
      • Funding: Select nothing
      • Save the changes. And when you think they can be published, hit the publish button.
  1. Cite code
    • use Zenodo Bibtex generator to get a bibtex entry of your code for your latex literature file – Export section (bottom right)
BibTeX code export via Zenodo

Put a DOI patch into the readme -> Use latest version DOI by clicking on the DOI entry (1) and copying the markdown code (2) from the window. You can add a badge to your gitlab repo as well, either in the readme (2) or by adding a batch using (3a) and (3b)

Zendodo DOI Badge

You might want to change the DOI to the DOI for the latest version:

Adjust the DOI
  1. Updating
    • Create new release on github
    • update Description on zenodo
CC BY 4.0
Weiternutzung als OER ausdrücklich erlaubt: Dieses Werk und dessen Inhalte sind – sofern nicht anders angegeben – lizenziert unter CC BY 4.0. Nennung gemäß TULLU-Regel bitte wie folgt: Open Access Publishing at TUHH: Exemplary Step-by-step guide for a toolchain with TORE, GitLab, Sherpa Romeo and Zenodo von Patrick Göttsch, Christian Hespe, Adwait Datar, Simon Heinke und Lennart Heeren Lizenz: CC BY 4.0. Eine ggf. aktualisierte Version des Workflows kann über dieses GitLab-Repositorium abgerufen werden.

Schreiben mit Markdown – weniger ist (oftmals) mehr

Es ist nun schon einige Jahre her: im Rahmen meines Bachelorstudiums hat unsere Projektgruppe einen gemeinsamen Projekt-Abschlussbericht geschrieben. Zahlreiche Interviews haben wir zu Nutzungsgewohnheiten bei Webangeboten geführt, Daten gesammelt und ausgewertet. Die Inhalte waren da, Zuständigkeiten für die einzelnen Textabschnitte geregelt. Und doch gab es am Ende den „großen Knall“. Die vielen unterschiedlichen Textbausteine – überwiegend geschrieben mit Word – mussten zusammengefügt werden. Unterschiedliche Wordversionen, unterschiedliche Formatierungen, unterschiedliche Layouts – es war ein Graus. Nur mit verhältnismäßig viel Aufwand konnte aus dem Wildwuchs im Dokument am Ende ein recht einheitlich und sauber formatierter Bericht generiert werden.

Ähnliche Erfahrungen machte ich über die Jahre hinweg – unter anderem in Studium, Beruf und privat – immer und immer wieder. Dazu gesellte sich E-Mail-Ping-Pong (eine neue Version eines gemeinsamen Dokuments wird immer wieder überarbeitet hin- und hergeschickt) oder das Verlieren im Button-Dschungel der zahlreichen Formatierungsoptionen von Schreibanwendungen. Mein eigentlicher Schreibfluss geriet dabei oftmals ins Stocken. Eine Alternative musste her. Und mit Markdown habe ich für mich eine gefunden.

Was ist eigentlich Markdown?

John Gruber veröffentlichte Markdown im Jahr 2004. Ursprünglich als einfache Alternative zu HTML entwickelt, um Interessierten ohne HTML-Erfahrung die Erstellung von Webseiten zu ermöglichen, ist Markdown auch eine sehr gute Möglichkeit Texte unterschiedlichster Gattungen zu schreiben.

Im Kern ist Markdown ein simpler Weg um Formatierungen für einfachen Text (auch: plain text, also menschenlesbar) umzusetzen. Wie mit Hilfe von gängigen WYSIWYG-Editoren (What You See Is What You Get) lassen sich also Texte mit Überschriften, Listen, Verlinkungen und Hervorhebungen erzeugen. Im Gegensatz zu Word oder beispielsweise Pages müssen wir uns aber nicht mit den zahlreichen Menüs (oder alternativ Tastenkombinationen) auseinandersetzen, die über die Jahre Einzug in viele Texteditoren erhalten haben.

Beim Einsatz von Markdown nutzen wir Zeichen, die uns bereits aus dem (Schreib-)alltag bekannt sind. Mit der Raute erzeugen wir so zum Beispiel Überschriften unterschiedlicher Ordnung:

Überschriften in Markdown

Überschriften unterschiedlicher Ordnung mit Markdown erzeugen.

Für einfache Listen muss nur ein Sternchen und ein Leerzeichen vor den jeweiligen Listeneintrag gesetzt werden. Kursive Begriffe werden mit Hilfe umschliessender Sterne erzeugt. Für Fettdruck reichen doppelte umschliessende Sterne:

Formatierungen mit Markdown

Auswahl an möglichen Formatierungen mit Markdown.

So haben wir eigentlich schon alles, was man für das Schreiben vieler Texte benötigt. Markdown sah für mich – als bis dahin überwiegend nur Word gewohnten Nutzer – ein wenig kompliziert aus. Aber nach nicht einmal einer Stunde hat man einen Überblick über alle wesentlichen Auszeichnungsoptionen gewonnen. Routine kommt dann ebenfalls recht zügig durch regelmäßige Nutzung.

Warum sollte man Markdown nutzen?

Doch warum sollte man nun Markdown nutzen oder zumindest einmal ausprobieren? Die eigenen Schreibgewohnheiten regelmäßig zu hinterfragen und zu überprüfen ist in meinen Augen grundsätzlich empfehlenswert. Statt etwas immer und immer wieder so zu machen wie bisher, da es eben immer so gemacht wurde, können wir uns neue Gewohnheiten erarbeiten und zu nutze machen. Darüber hinaus gibt es natürlich weitere Gründe, die für Markdown sprechen:

Schnell erlernbar

Markdown zu schreiben ist anders, als man es von bekannten kommerziellen Texteditoren mit zahlreichen Zusatzfunktionen kennt. Aber es ist auch einfach zu lernen und schnell praktisch nutzbar. Für den Einstieg gibt es viele gute Tutorials. Auch ein Cheat-Sheet kann hilfreich sein. Die komplette Ur-Syntax könnt ihr hier abrufen. Ich persönlich würde empfehlen ein kurzes Tutorial durchzuspielen, um im Anschluss beispielsweise in einer kollaborativen Schreibumgebung wie WriteMD der TUHH praktische Erfahrungen zu sammeln und selbst loszulegen. Hier hat man die Möglichkeit neben der reinen Syntaxansicht auch mit Vorschauoptionen zu arbeiten, um so direkt sehen zu können welche Auswirkungen einzelne Textauszeichnungen haben.

Ansichtenwechsel

Wechsel von der Schreibansicht zur geteilten Ansicht (Schreib- und Leseansicht).

 

Wer bisher überwiegend mit WYSIWYG-Editoren gearbeitet hat, wird so sicher einen besseren Einstieg in das Schreiben mit Markdown haben.

Schnelle Schreibumgebung

In Markdown zu schreiben bedeutet, dass zunächst keine exzessiven Formatoptionen zur Verfügung stehen. Und genau das kommt zumindest meinem Schreibprozess oftmals entgegen. Der Fokus liegt auf mir als Schreibendem und meinen Inhalten. So haben wir eine nicht verworrene, schnelle und übersichtliche Schreibumgebung. Der Griff zur Maus ist nach der Eingewöhnungsphase nicht mehr nötig, um Textformatierungen vorzunehmen. Also keine ungewollte Pause mehr beim Schreibprozess alle paar Minuten oder gar Sekunden, um zu klicken, zu markieren, wieder zu klicken, sich für eine Formatierung zu entscheiden, um dann anschließend mit dem eigentlichen Schreiben weiterzumachen. Gerade wenn man Wörter und Ideen einfach erst einmal aus dem Kopf „auf Papier“ bringen möchte, ist dies in meinen Augen ein großer Vorteil, um den eventuell auch schwer erarbeiteten Schreibflow beizubehalten.

Portables Format

Bei Markdown handelt es sich um ein portables Format. Markdown-Dateien können im Grunde mit jeder Anwendung geöffnet werden. Neben simplen Texteditoren gibt es eine Reihe von Markdown-Editoren mit zusätzlichen Optionen. An dieser Stelle seien die kollaborative Online-Schreibumgebung WriteMD der TUHH, VSCodium, Typora und Zettlr erwähnt. Gefällt einem die aktuell genutzte Anwendung nicht, so können Markdowndateien – ganz im Gegensatz zu proprietären Textformaten – ohne Probleme in eine andere Anwendung importiert werden. Darüber hinaus funktioniert Markdown auch völlig plattformunabhängig – es spielt also keine Rolle, ob wir uns auf einer Windows-, Mac OS- oder Linux-Maschine bewegen. Markdown ist überall „zuhause“.

Zukunftssicher und schnell zu konvertieren

Markdown ist zukunftssicher. Selbst wenn die Anwendung, die wir aktuell verwenden, in naher Zukunft nicht mehr funktioniert, können wir unsere mit Markdown verfassten Texte immer noch mit einem Texteditor unserer Wahl nutzen. Gerade im Hinblick auf Dokumente, die wir auf unbestimmte Zeit hin aufbewahren wollen (ob nun private Dokumente, Abschlussarbeiten, Forschungsberichte, etc.) ein riesiger Vorteil.

Darüber hinaus lässt sich Markdown in viele Formate mit Hilfe von Unterstützung durch Open-Source-Anwendungen wie Pandoc konvertieren. Ein Beispiel dafür ist das Projekt Modernes Publizieren mit Swapfire.

Wo kommt Markdown zum Einsatz?

Bei uns an der TU beziehungsweise tub. wird Markdown unter anderem bei kollaborativen Protokollen, Dokumentationen oder auch bei der Erstellung kurzer Präsentationen im Rahmen von WriteMD verwendet. Für das tub.-Bachelorseminar Wissenschaftliches Arbeiten erstellen wir zudem Seminarskripte mit interaktiven Elementen.

Auch Chatumgebungen wie Mattermost, Foren wie Reddit oder Chats größerer Social-Media-Plattformen bieten das Nutzen der Markdown-Syntax an. Viele Webseiten werden ebenfalls mit Markdown umgesetzt und selbst für Schreibanwendungen wie Word oder Content-Management-Systeme wie WordPress gibt es Markdown-Plugins.

Ausblick

Markdown ist sicher nicht für alle Schreibenden die Ideallösung. Aber wem einfacher Text zu wenig und andere Schreibanwendungen gefühlt zu überfrachtet sind, sollte auf jeden Fall einen Blick riskieren. Es ist angenehm schnell zu lernen und man kann eine ganze Menge damit machen. In einem kommenden Beitrag zeigen wir euch in diesem Zusammenhang mit Zettlr einen Markdowneditor, der eine Vielzahl an Exportmöglichkeiten und eine Anbindung an die eigene Literaturverwaltung ermöglicht – eine ideale Grundlage für das Schreiben wissenschaftlicher Arbeiten. Ans Herz gelegt sei an dieser Stelle auch unser kleines Quiz zu den eigenen Schreibgewohnheiten.

 

CC BY 4.0
Weiternutzung als OER ausdrücklich erlaubt: Dieses Werk und dessen Inhalte sind – sofern nicht anders angegeben – lizenziert unter CC BY 4.0. Nennung gemäß TULLU-Regel bitte wie folgt: Schreiben mit Markdown – weniger ist (oftmals) mehr“ von Florian Hagen, Lizenz: CC BY 4.0. Der Beitrag steht als Markdown-, DOCX- und PDF-Datei zur Verfügung.