CMP-03a: Word-Datei in bookdown einspielen

CMP-03a ergänzt die Kurseinheit CMP-03. Hier zeige ich Ihnen wie Sie bereits fertig formtierten Text aus einer Word-Datei in Ihr bookdown-Projekt einspielen können. Die vorgezeigte Lösung ist nicht perfekt und erfordert weiterhin ein Nachbearbeiten. Vor allem Grafiken, Tabellen und Zitierungen müssen weiterhin direkt in bookdown bearbeitet werden. Trotzdem: Die Arbeitsersparnis ist enorm! Innerhalb einer Stunde sehen Sie Ihren gesamten Buchtext in einer Rohfassung in allen drei Publikationsformen (PDF, ePub und Webseite).

CMP-03a ergänzt die Kurseinheit CMP-03. Hier zeige ich Ihnen wie Sie bereits fertig formtierten Text aus einer Word-Datei in Ihr bookdown-Projekt einspielen können. Die vorgezeigte Lösung ist nicht perfekt und erfordert weiterhin ein Nachbearbeiten. Vor allem Grafiken, Tabellen und Zitierungen müssen weiterhin direkt in bookdown bearbeitet werden. Trotzdem: Die Arbeitsersparnis ist enorm! Innerhalb einer Stunde sehen Sie Ihren gesamten Buchtext in einer Rohfassung in allen drei Publikationsformen (PDF, ePub und Webseite).

Im dritten Teil des Kurses habe ich über die Formatierung von Cross Media Texten mit Markdown gesprochen. Dabei habe ich vorgeschlagen bei vorhandenen Texten mit copy & paste zu arbeiten.

Ich habe nun eine bessere Möglichkeit gefunden. CMP-03a zeigt Ihnen, wie Sie ein komplettes Buch als Word-Datei importieren können. Die hier gezeigte Lösung ist allerdings nicht perfekt und erfordert weiterhin Nachbearbeiten. Vor allem Grafiken, Tabellen und Zitierungen müssen direkt in RStudio bearbeitet werden. Aber die Arbeitsersparnis ist enorm! Nach nur einer Stunde haben Sie Ihren gesamten Text als Rohfassung eingespielt und können sich auf die Details der Formatierung konzentrieren.

Ich empfehle Ihnen daher von copy & paste auf den hier gezeigten Import umzusteigen. Ihre bisherige Arbeit ist nicht verloren, weil Sie ja die bereits fertig formatierten Teile kopieren können bzw. bereits fertige Kapitel weiterhin nutzen. Wie? Das zeigt Ihnen diese Kurseinheit.

CMP-03a: Voraussetzungen

  • Erfolgreiches Durcharbeiten von Cross Media Publishing Tutorial Nr. 1 (CMP-01)
  • Erfolgreiches Durcharbeiten von Cross Media Publishing Tutorial Nr. 2 (CMP-02)
  • Sie sollten das Cross Media Publishing Tutorial Nr. 3 (CMP-03) zumindest einmal durchgelsen haben. Diese Kurseinheit ersetzt bzw. ergänzt den Abschnitt CMP-03: Text eines Kapitels einspielen.

CMP-03a: Learning Outcomes

Wenn Sie dieses Tutorial durcharbeiten, dann können Sie

  • eine Word-Datei in Markdown konvertieren
  • die Markdown-Datei in Ihr bookdown-Projekt einspielen
  • die Ergebnisse Ihrer formatieren Texte in allen Publikationsformen vergleichen

CMP-03a: Hintergrundinfos zur Konvertierung

Diesen Unterabschnitt brauchen Sie nur zu lesen, falls Sie an Hintergrundinformationen interessiert sind und keine Kenntnisse der Eingabe von Kommandozeilen für Ihr Betriebssystem haben.

1. Installation von pandoc

Mit dem bereits in CMP-03 erwähnten Konvertierungsprogramm pandoc können Sie Word-Dateien in Markdown-Datein umwandeln. Allerdings genügt es dafür nicht, dass pandoc in Rstudio und bokkdown bereits integriert ist, sondern wir müssen das Programm extra installieren:

Dazu rufen Sie die Installationsseite von pandoc auf und installieren die akutellste Programm für Ihr Betriebssystem auf der Download-Seite. Danach fahren Sie mit den Hinweise auf der Installationsseite weiter fort. Die Latex-Installation brauchen Sie allerdings nicht mehr vornehmen, das hatten wir ja bereits in der ersten Lektion erledigt.

Noch ein Tipp für Mac-User: Es wird auf der Installationseite homebrew als Hilfsprogramm für die Installation empfohlen. Das mag Ihnen umständlich erscheinen, weil Sie höchstwahrscheinlich zuerst dann auch noch homebrew selbst noch installieren müssen. Ich empfehle Ihnen das aber sehr, weil Sie mit homebrew sehr viele andere Programme mit einer einzigen Programmzeile im Terminal installieren können. Homebrew ist ein Packagemanager und kümmert sich dann um alles andere (notwendige Zusatzprogramme, Ort auf Ihrer Festplatte, Verlinkung).

Sie können nach der Installation testen, ob Ihr Rechner nun pandoc erkennt. Geben Sie in Ihr jeweiligen Interface für Kommandozeilen den Befehl

pandoc --version

ein. Was es mit diesem Interface für Kommandozeilen auf sich hat, erkläre ich unter 3. Interface für Kommandozeilen-Eingabe aufrufen.

2. Konversionsbesipiel von Word zu Markdown aus pandoc-Demoseite

Ich fahre nun mit der Erläuterung Ganz unten auf der pandoc-Demo-Seite finden Sie als 35. Beispiel das Kommando für eine Demonstration dieser Konversion:

 

pandoc -s example30.docx -t markdown -o example35.md

Erläuterung (siehe pandoc-Manual)

  • Das Programm pandoc, das wir bereits installiert haben, wird aufgerufen.
  • -s steht für Standalone Programm: sie können auch --standalone schreiben.
  • example30.docx ist das Eingabeprogramm. Sie könnten es auch mit dem Parameter -f (from) bzw. --from kennzeichnen.
  • -t steht für "to", sie können auch --to schreiben

Die obige Zeile ist ein rudimentäres Kommando, das wir noch mit einigen Parametern für unsere Zwecke adapotieren werden. Sie müssen natürlich dann Ihre Word-Datei (inklusive Pfad) einsetzen.

3. Interface für Kommandozeilen-Eingabe aufrufen

Leider ist die Konvertierung von Word zu Markdown nicht als Option in der Online Try pandoc! Seite enthalten. Sie müssen daher Ihre Kommandos – entsprechend Ihrem Betriebssystem – in die jeweilige Shell eingeben. Sie brauchen dazu aber nicht die Shell-Programmiersprache lernen, sondern es genügt, wenn Sie wissen, wie das Interface für die Kommandozeilen-Eingabe – Command Line Interface (CLI) – in Ihrem Betriebssystem aufgerufen werden kann.

7. März 2018: Viel einfacher ist es, wenn Sie das nun bereits in RStudio integrierte Terminal-Fenster verwenden (Reiter "Terminal" im linken unteren Fenster). Damit erübrigt sich der Rest dieses Unterabschnitts!

Ich kann hier nur die MacOS Version mit dem Terminal-Programm zeigen. Für andere Betriebssysteme müssen Sie meine Erklärungen adaptieren.

  • MacOS: Rufen Sie das Terminal-Programm auf. Es befindet sich im Ordner "Dienstprogramme" (/Programme/Dienstprogramme) oder als Tastaturkürzel CMD-SHIFT-U (für Utilities). (Siehe auch How to Open a Terminal Window in Mac.)
  • Windows: Start-Menü aufrufen bzw. Windows-Taste und cmd und Enter eingeben. (Siehe auch die ersten 40 Sekunden des Videos Windows Command Line Tutorial - 1 - Introduction to the Command Prompt.)
  • Ubuntu: Oben links auf das Ubuntu-Icon klicken, "terminal" eingeben und dann das Terminal Programm von der Ergebnisliste auswählen. Oder direkt mit CTRL-ALT-T aurufen (Siehe auch Ask Ubuntu.)

4. Shell Programm ausführen

Sie brauchen jetzt nicht die Shell-Progammierung lernen. Es genügt, wenn Sie sich die entsprechende Programmdatei von meinem Weblog herunterladen und ausführen. Ich habe die grundlegende Struktur des Programm von Arthur Attwell verwendet. Es gibt eine .bat (Windows) und .sh (MacOS) Version. Wobei ich allerdings vermute, das die .sh Version jetzt auch unter Windows lauffähig ist (siehe How to Create and Run Bash Shell Scripts on Windows 10).

Einige Links für Tutorials wie die Shell genutzt wird. Sie können auch im Internet nach entsprechenden Tutorials suchen: 

Weil ich hier Windows nicht abdecken kann, noch allgemeinere Hintergrund-Infos, die für umfassendere Kenntnisse hilfreich sein könnten:

CMP-03a: Shellprogramm herunterladen und inspizieren

CMP-03a: Shell-Programme für Konvertierung von Word.docx zu RMarkdown.Rmd
Shell-Programme für Konvertierung von .docx zu .Rmd Format unter Verwendung von pandoc

Sie können die Programm-Datei für die Konvertierung herunterladen. Sie können entweder beide Versionen gleichzeitig  herunterladen indem Sie auf Download ZIP klicken oder einzeln durch einen Klick auf Raw und anschließendes Copy & Paste. 

Ich habe die Datei gleich so verändert, dass statt einer Markdown-Datei (Endung .md) gleich eine RMarkdown-Datei (Endung .Rmd) erzeugt wird. Das hat den Vorteil, dass wir dann gleich auch alle Sonderbefehle von R und bookdown nutzen können.

Wenn Sie sich die Textdatei ansehen, dann sehen Sie als entscheidendes Kommando, das die Konvertierung organisiert:

pandoc -f docx -t markdown+auto_identifiers -s "$filename".docx -o "$filename".Rmd --atx-headers --wrap=none --extract-media="media"

Erläuterung (siehe pandoc-Manual)

In der Umgangssprache sagt diese Zeile:

Rufe pandoc auf und konvertiert von einer Word-Datei (-f = from) zu (-t = to) einer markdown-Datei. Die Standalone-Datei (-s = Standalone), die dabei konvertiert werden soll, hat den vom Benutzer / von der Benutzerin eingegebenen Dateinamen mit der Endung .docx und soll in eine Markdown-Datei geschrieben werden (-o = Output), die denselben Namen jedoch mit Endung .Rmd hat (und somit eine R-Markdown Datei ist).

Dazu gibt es dann noch zusätzliche Parameter:

  • markdown+auto_identifiers: Überschriften dienen auch als Sprungmarken. Das erleichtert das Erzeugen von Querverweisen.
  • atx-headers: Statt standardmäßig die Überschrift mit = oder - unterstreichen (setext-style headers), verwende stattdessen # Symbole vor der Überschrift 
  • --wrap=none: Code soll nicht umbrochen werden. Das bezieht sich auf Programmcodes in der erzeugten Datei.
  • --extract-media="media": Spiele auch alle Grafiken heraus und speichere sie in einem Ordner mit den Namen media. Auch wenn wir die Grafiken später noch nachbearbeiten müssen, ist es ein großer Vorteil, dass sie bereits nummeriert im Text werden und als Original-Dateien für die Einbindung vorhanden sind.

CMP-03a: Wordfile konvertieren und inspizieren

Rufen Sie Ihr Programm zur Eingabe von Kommando-Zeilen auf. In meinem Fall ist es die Terminal-Applikation. Ich habe dazu einen Video erstellt, der nicht nur zeigt, wie der gesamte Vorgang der Konvertierung abläuft, sondern auch gleich die Einbindung und Überprüfung in RStudio erläutert. Sollten Sie Windows oder Linux verwenden, müsste meine Vorgangweise relativ einfach für Ihr Betriebssystem adaptierbar sein. – Schreiben Sie bitte Ihre Erfahrungen in das Forum zu diesem Beitrag.

Wenn Sie die im Video gezeigte Schritte durchgeführt haben, sollten Sie gleich als nächsten Schritt Ihre große Rmd-Datei in mehrere kleinere Datein – am Besten nach den Kapitel getrennt – aufteilen. Es lässt sich dann damit nicht nur leichter, sondern auch schneller arbeiten. Sie brauchen nicht immer das ganze Buchprojekt kompilieren und können sich auf ein einzelnes Buchkapitel konzentrieren.

Nach der Konversion habe ich die große Audiemus.Rmd-Datei in kleinere Dateien aufgeteilt, die meistens jeweils ein Kapitel enthalten (rechter Kasten). Außerdem habe ich die Index.Rmd auf die Audiemus Daten angepasst (Pfeil)

CMP-03a: Zusammenfassung

Mit dieser Lektion habe ich Ihnen gezeigt, wie Sie eine Word-Datei zu Markdown konvertieren und in RStudio importieren können. Ich glaube, dass diese Methode weit einfacher ist, als die in CMP-03 vorstellte Version mit copy & paste. Aus meiner Sicht gibt es drei offensichtliche Vorteile:

  • Wenn Sie die hier vorgestellte Methode einmal beherrschen, haben Sie in 10 Minuten Ihr Buch in einer ersten Draft-Version importiert!
  • Sie bekommen damit schnell einen Überblick zu Ihrem Buchprojekt.
  • Gegenüber copy & paste werden auch gleich die Grafiken exportiert und an den entsprechenden Stellen nummeriert eingebunden.

Es ist keine allerding immer noch keine ideale Lösung, weil es noch viel Arbeiten gibt, die aufwändig und manuell nachbearbeitet werden müssen. Nach der von mir durchgeführten Umwandlung sind vor allem noch folgende Schritte "manuell" nach zu bearbeiten:

  • Einsetzen der Bildunterschriften und rauschlöschen dieser Passagen aus dem Text.
  • Komplette Überarbeitung von Tabellen (da hat die Konversion nicht funktioniert)
  • Setzen von Sprungmarken für Grafiken. Das erfordert eine andere Vorgangsweise (siehe demnächst: CMP-05).
  • Bearbeitung von Querverweisen für Grafiken, Tabellen und Zitierungen.

Die konvertierte Markdown-Datei ist natürlich nur so gut, wie die Word-Datei dynamische Auszeichnungen (Stylesheets) verwendet. Insgesamt gehört natürlich der gesamte Buchtext vor der Veröffentlichung natürlich sehr detailliert durch gesehen, adaptiert und nachbearbeitet. Aber immerhin ist mit dieser hier vorgestellten Methode mal ein (großer) Anfang getan!

 

Von Peter Baumgartner

Seit mehr als 30 Jahren treiben mich die Themen eLearning/Blended Learning und (Hochschul)-Didaktik um. Als Universitätsprofessor hat sich dieses Interesse in 13 Bücher, knapp über 200 Artikel und 20 betreuten Dissertationen niedergeschlagen. Jetzt in der Pension beschäftige ich mich zunehmend auch mit Open Science und Data Science Education.

9 Antworten auf „CMP-03a: Word-Datei in bookdown einspielen“

Wie immer eine sehr gute Beschreibung. Diesmal bin ich allerdings am Skript gescheitert, das mir im Terminal anstatt der Konvertierung einen Fehler in Zeile 20 meldet. Ich finde ihn allerdings nicht, habe aber einen Screenshot gemacht, den ich per Mail schicke. Vielleicht übersehe ich etwas.

Ich glaube, dass Ihr Shell-Script nicht das Programm pandoc findet. Geben Sie mal im Terminal den Befehl pandoc --version ein.

Hinweise zur Installation von pandoc

ich vermute, dass die Probleme mit dem Script zur Konvertierung damit zusammenhängen, dass Pandoc extra (sozusagen als Standalone-Programm) installiert werden muss. Ich habe dies offensichtlich schon einmal vor grauer Urzeit getan und fälschlicherweise gedacht, dass es mit bookdown installiert ist. (Bookdown bzw. auch RStudio greift sicherlich auf pandoc zu, sonst hätten von Markdown nicht in HTML, ePUB und PDF konvertieren können. Das ist aber offensichtlich eine – andere – integrierte Version.)

Testen Sie mal zuerst im Terminal, ob Ihr Computer pandoc kennt und geben Sie den Befehl

pandoc --version

ein. Wenn das eine Fehlermeldung hervorruft – was ich vermute – dann rufen Sie die Installationsseite von pandoc auf und installieren Sie das Programm.

https://pandoc.org/installing.html

Noch ein Tipp für Mac-User: Es wird dort homebrew zur Installation empfohlen. Das mag Ihnen sehr umständlich erscheinen, weil Sie höchstwahrscheinlich zuerst dann auch noch dieses Programm installieren müssen (href=“https://brew.sh/). Ich empfehle Ihnen das aber sehr, weil Sie mit homebrew SEHR VIELE andere Programme mit einer einzigen Programmzeile im Terminal installieren können. Homebrew ist ein Packagemanager und kümmert sich dann um alles andere (notwendige Zusatzprogramme, Ort auf Ihrer Festplatte, Verlinkung).

Ich habe jetzt die Lektion mit der Installation von pandoc als Standalone-Programm ergänzt.

Unter Windows 7 hat die „pandoc“-Installation klaglos funktioniert und die .docx- ins .Rmd-Format-Konversion grundsätzlich gut funktioniert. Die schon erwähnten manuellen Nachbesserungen sind nötig, aber nichtsdestotrotz: eine Riesenerleichterung!

Nun habe ich es auch hinbekommen. Der Grund war wahrscheinlich, dass ich den Pfad nicht richtig zugeordnet habe. Eine Besonderheit ist dennoch vorhanden, dass bei mir der Ladevorgang sofort fertig ist, ggf. aber nicht alles geladen wird. Vorteilig könnte sein, dass ich zuvor die Arbeit in Pages geschrieben und nicht alles so verschoben ist.
Der Prozess mit pandoc im Terminal zeigt mir beim Schließen an, dass es noch nicht fertig ist – was ich nicht verstehe.

Zeigen Sie mir mit einem Screenshot die Rückmeldung des Terminals.

Vielleicht ist es bloß Endlos-Schleife, die das Batch-Programm hat? Nachdem es mit der Konvertierung fertig ist, verlangt es weitere Dateien und muss „mit irgendeiner Eingabe und abschließendem Return“ abgebrochen werden. Ich habe immer `q + ENTER` (q für Quit) verwendet. Das ist aber egal.

Wenn diese Endlosschleife irritiert, nehme ich sie heraus. Das Programm ist gedacht für die Konversion einer ganzen Reihe von Wordfiles (Kapitel?), die alle auf einmal, hintereinander konvertiert werden. – Aber das ist für unseren Anwendungsfall vielleicht zu kompliziert, weil nicht notwendig.

Mir ist übrigens gerade eingefallen, dass ich mir die Erklärung des Terminals für die verschiedenen Versionen des Betriebssystem ersparen hätte können. RStudio hat ja jetzt das Termin bereits inkludiert: Im linken unteren Fenster gibt es den Reiter „Terminal“.

Danke für die Installationsanleitung zu pandoc. Ich habe den Weg via homebrew gewählt und das hat reibungslos funktioniert. Danach konnte ich mein .docx ohne Probleme ins .rmd einlesen, das dauert keine 5 Sekunden.

Schreiben Sie einen Kommentar

Ihre E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert