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).

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: 

• MacOS: Suche nach maxos wie verwende ich terminal bzw. maxos how to use terminal, z.B. How to use Terminal on Mac oder Einführung ins Terminal von OS X. Oder auch der oben bereits erwähnte Video.
• Windows: windows wie verwende ich kommandozeile bzw. windows how to use command line, z.B. Windows 10: Eingabeaufforderung öffnen und nutzen - So geht's bzw. How to use the Windows command line (DOS).
• Ubuntu: z.B. What is a terminal and how do I open and use it?

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

• Guide to Windows Batch Scripting, 
• How to Create and Run Bash Shell Scripts on Windows 10
• Umfassendes PDF-Tutorial für Batch Scripting von TutorialsPoint

CMP-03a: Shellprogramm herunterladen und inspizieren

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.

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!