So passen Sie das Plone Benutzerhandbuch Ihren Bedürfnissen an

Das Plone Benutzerhandbuch steht unter einer Creative Commons Lizenz, die eine nicht kommerzielle Nutzung und Anpassung des Handbuch erlaubt. Auf dieser Seite wird beschrieben, wie Sie die Quelltexte des Handbuchs herunterladen und anpassen können.

Voraussetzungen

Um das Plone-Benutzerhandbuch den eigenen Bedürfnissen anzupassen, benötigen Sie eine Reihe von Programmen. Glücklicherweise sind alle benötigten Systeme Open-Source-Software und können in der Regell schnell installiert werden.

Sphinx

Das Plone-Benutzerhandbuch wird mit dem Dokumentationswerkzeug Sphinx erstellt. Falls Sie mindestens Python 2.4 und setuptools installiert haben, können Sie Sphinx mit folgendem Befehl installieren.

easy_install -U Sphinx

Nach der Installation steht Ihnen der Befehl sphinx-quickstart zur Verfügung, mit dem Sie ein eigenes Sphinx-Projekt erstellen können. Lesen Sie dazu die Erläuterungen auf der Sphinx-Homepage. Damit können Sie testen, ob Ihre Sphinx-Installation korrekt arbeitet.

TeX

Wenn Sie die PDF-Version des Handbuchs erstellen möchten, benötigen Sie eine TeX-Installation. Falls TeX bei Ihnen noch nicht installiert ist, können Sie es unter Linux mit Ihrem Paketmanager installieren. Unter Windows können Sie MiKTeX oder proTeXt und unter Mac OS X MacTeX installieren.

Bazaar

Der Quelltext des Benutzerhandbuchs wird auf der Software-Entwicklungsplattform Launchpad gepflegt. Launchpad arbeitet mit der dezentralen Versionsmanagement-Software Bazaar,die Sie hier herunterladen können.

Sie können das Benutzerhandbuch natürlich auch ohne ein Versionsmanagement anpassen. Da es jedoch noch keine Release des Benutzerhandbuchs gibt, die Sie als Archiv herunterladen könnten, benötigen Sie Bazaar zumindest, um sich einen lokalen Branch des Handbuchs anzulegen. Danach können Sie entweder eine andere Versionierungssoftware nutzen oder ganz auf die Versionierung verzichten. Von Letzterem rate ich jedoch dringend ab.

Erzeugung eines lokalen Branches\

Nach der Installation von Bazaar können Sie den Quelltext des Benutzerhandbuchs für die aktuelle Version von Plone (zurzeit 4.0) mit diesem Befehl herunterladen:

bzr branch lp:plone-benutzerhandbuch

Falls Sie das Benutzerhandbuch für die Version 3.3.5 benutzen möchten, geben Sie bitte diesen Befehl ein:

bzr branch lp:plone-benutzerhandbuch/3.3.5

Sie erzeugen mit diesem Befehl einen lokalen Branch des Plone-Benutzerhandbuchs auf Ihrem Rechner. Aufgrund der zahlreichen Screenshots ist das Projekt recht groß. Sie benötigen knapp 150 MB freien Speicherplatz auf Ihrer Festplatte.

Anpassung des Handbuchs

Der Quelltext des Handbuchs ist in einer thematisch gegliederten Ordnerstruktur organisiert.

Im Ordner ›_build‹ befinden sich in Unterordnern die jeweiligen Ausgabeformate.

In den Ordnern ›_static‹, ›_template‹ und ›plone_org_theme‹ befinden sich Dateien, mit denen das Layout der HTML-Fassung beeinflusst wird.

In der Datei ›conf.py‹ werden globale Variablen festgelegt. Lesen Sie dazu die Dokumentation von Sphinx.

Im Ordner ›images‹ befinden sich die Abbildungen, die für das Benutzerhandbuch benötigt werden. Abbildungen, die sich auf Erweiterungen von Plone beziehen, befinden sich im Ordner der Dokumentation selbst.

Alle anderen Ordner spiegeln die thematische Gliederung wider. Sie enthalten Textdateien im Restructured-Test-Format. Auf der obersten Ebene finden Sie ebenfalls einige Textdateien mit der Endung .rst, die zum Beispiel das Inhaltsverzeichnis, das Glossar oder das Literaturverzeichnis enthalten.

In vielen Fällen wird es ausreichen, wenn Sie die Abbildungen im Ordner ›images‹ durch Screenshots von Ihrer Plone-Website ersetzen. Speichern Sie die Screenshots dabei unter dem gleichen Namen wie die Originale.

Die Textdateien lassen sich in jedem Texteditor, der UTF-8-Encoding beherrscht, editieren. Was Sie beim Editieren beachten müssen, erfahren Sie in der Sphinx-Dokumentation.

Ihre Änderungen können Sie mit dem Befehl

bzr commit

in Ihrem lokalen Branch einchecken.

Erzeugung der Output-Formate

Mit Hilfe der Datei Makefile (bzw. make.bat unter Windows) können Sie die HTML-, PDF- und ePub-Version des Handbuchs mit folgenden Befehlen erstellen.

make html

make latexpdf

make epub

Sie können auch alle drei Formate mit einem Befehl erstellen:

make latexpdf epub html

Die Reihenfolge (latexpdf, epub, html) sollte eingehalten werden, da bei der Erzeugung der HTML-Version die PDF und ePub-Versionen bereits verfügbar sein sollten.

Die HTML-Version des Benutzerhandbuchs finden Sie anschließend im Ordner _build/html. Die Startseite lautet:

_build/html/index.html

Das PDF mit dem Handbuch für Plone 4.0 finden Sie unter dem Pfad _build/latex:

_build/latex/Plone-Benutzerhandbuch-4.0.pdf

Falls Sie mit dem Handbuch für die Version 3.3.5 arbeiten, lautet der Pfad entsprechend:

_build/latex/Plone-Benutzerhandbuch-3.3.5.pdf

Das eBook befindet sich im Ordner _build/epub:

_build/epub/Plone-Benutzerhandbuch40.epub

bzw.

_build/epub/Plone-Benutzerhandbuch335.epub

Serviceleistungen von hasecke.com

hasecke.com bietet Ihnen folgende Serviceleistungen an.

1. Anpassung des Benutzerhandbuchs an Ihre individuellen Bedürfnisse: Austausch von Screenshots und kleinere Umformulierungen.
2. Erweiterung des Handbuchs um spezielle Kapitel zum Beispiel zur Dokumentation von Erweiterungen, die Sie auf Ihrer Website einsetzen. Aufgrund der Lizenz können diese Erweiterungen wieder in das generische Handbuch einfließen und so der gesamten Community zugute kommen.
3. Schulung Ihrer Mitarbeiter in der Benutzung von Sphinx.

Referenzen

Das Plone-Benutzerhandbuch wird als PDF und eBook von der Universität Bonn eingesetzt.