NanoBlogger User Manual

# NanoBlogger Benutzerhandbuch

## von n1xt3r (Kevin Wood)
Deutsche Übersetzung von Sven Bergner

Dieses Dokument beschreibt die Installation und den Gebrauch von NanoBlogger.

## 1. Einleitung

NanoBlogger ist eine kleine Weblog Engine die in Form eines Bash Skriptes für die Kommandozeile. Es benutzt allgemeine UNIX-Tools, wie z.B. cat, grep und sed um damit statische HTML-Seiten zu erzeugen. Es steht unter der GNU General Public License und kann somit frei benutzt und modifiziert werden.

Übersicht

    nb [-b blog_dir] [options]

## 2. Merkmale

- Intuitive Kommandozeilen Schnittstelle
- Vielfältig konfigurierbar und skriptfähig :)
- Einfaches entwerfen, bearbeiten und verwalten von Einträgen
- Archivierung unter Kategorie, Jahr, Monat und Eintrag
- Seitenumbruch
- Dauerhafte und Navigations Links
- Vorlagen und CSS Style Sheets zur vollen Kontrolle des Layouts
- Platzhalter für einfache Vorlagenbearbeitung
- Unterstützung für beliebig viele Weblogs
- Unterstützung für beliebig viele Kategorien
- Unterstützung für relative und absolute Links
- Unterstützung von Datumsänderungen von Einträgen
- Atom Syndikation (im 1.0 Format)
- RSS Syndikation (im RSS 2.0 und 1.0 Format)
- Plugins für Kalender, aktuelle Einträge, Weblog-Status, etc.
- Plugins zur Textformatierung (z.B. Zeilenumbrüche übersetzen in HTML)
- Globale (nb.conf) und Pro-Weblog (blog.conf) Konfiguration
- Intelligentes Aktualisierungssystem - nur geänderte Dateien werden aktualisiert
- Einfaches Cache System für verbesserte Effizienz
- Benötigt kein Java-Skript oder Server-seitige Skripte (wie z.B. PHP)
- Benötigt keine externe Datenbank (Daten werden in Textdateien gespeichert)
- Unterstützung für beliebige Sprachen
- Multi-Plattform portabel (nur die Bash und die verwendeten Kommandos werden benötigt)

## 3. Installation

Um nanoblogger zu installieren:

          1. das tar.gzip Archiv von der Web-Seite[1] herunterladen
          2. das tar.gzip Archiv entpacken (wobei "XX" der
             Versionnummer entspricht):  tar xzf nanoblogger-XX.tar.gz

Aktualisieren

WICHTIG: Bitte vorher die Dokumentation und das Changelog lesen um zu sehen, was geändert wurde. Alle Unterschiede zwischen zwei Setups müssen per Hand behoben werden. Einfach nur die Vorlagen und die Konfiguration zu kopieren, wird nur zu Problemen führen. Der einfachste Weg zum Aktualisieren wird weiter unten beschrieben.

Drei einfache Schritte zur Aktualisierung(auf der Kommandozeile):

          1. ein neues Weblog-Verzeichnis mit nanoblogger erzeugen (die Konfiguration überspringen):
            nb -b [new_blog_dir] -a

          2. das alte Daten-Verzeichnis in das neue Weblog-Verzeichnis kopieren:
            cp -r [old_blog_dir]/data [new_blog_dir]

          3. das neue blog.conf an die eigenen Bedürfnisse anzupassen und
            dann das Weblog neu erstellen:
            nb -b [new_blog_dir] --configure -u all

## 4. Anforderungen

Programme:

Bash (mindestens v2.05), cat, cp, cut, dirname, date*, expr, grep, mkdir, mv, read, rm, sed, sort, touch, trap

* = GNU version empfohlen, aber nicht notwendig

## 5. Einführung

Ein neues Weblog erzeugen

Um ein neues Weblog zu erzeugen(von der Kommandozeile):

        cd [nb_dir]
        ./nb --blogdir [myblog_dir] --add

wobei nb_dir der Pfad zum Installationsverzeichnis von NanoBlogger und myblog_dir ein nichtexistentes Verzeichnis ist. Dieser Befehl erzeugt ein neues Verzeichnis, kopiert die Standarddateien hinein und fragt dann nach der Konfiguration des Weblogs. Beliebig viele Weblogs können auf diese Art und Weise erzeugt werden. Wird das gleiche Kommando nochmal auf ein bereits bestehendes Verzeichnis angewendet, dann wird ein neuer Eintrag erzeugt.

Zum schnellen und einfachen Aufrufen kann man "nb" in den Pfad oder zu den Aliasen der verwendeten Shell hinzugefügt werden (näheres bitte dem Handbuch der Shell entnehmen).

Um ein Standard Weblog-Verzeichnis zu setzen:

        1. editiere entweder nb.conf oder $HOME/.nb.conf.
        2. setze BLOG_DIR auf das gewünschte Weblog-Verzeichnis:
            BLOG_DIR="$HOME/public_html/[myblog_dir]"

## 6. Einstellungen und Konfiguration

Um die Konfiguration des Weblog zu ändern:

        nb --blogdir [myblog_dir] --configure -u all

Dieses Kommando öffnet blog.conf aus dem Weblog-Verzeichnis zum Editieren und Aktualisieren des kompletten Weblogs.

Einstellen des Browsers

Als Standardbrowser wird der benutzt, der in der Variablen BROWSER der Bash eingetragen ist, aber falls keine BROWSER Variable gesetzt ist wird "lynx" benutzt. Ein anderer Browser kann ausgewählt werden in dem BROWSER in blog.conf oder die BROWSER Variable der Bash umgesetzt wird. Unter Mac OS X sollte diese Variable vorzugsweise auf "open" gesetzt werden.

Einstellen des Editors

Als Standardeditor wird der benutzt, der in der Variablen EDITOR der bash eingetragen ist, aber falls keine EDITOR Variable gesetzt ist wird "vi" benutzt. Ein anderer Editor kann ausgewählt werden in dem EDITOR in blog.conf oder die EDITOR Variable der Bash umgesetzt wird.

Einstellen des Datumformats für neue Einträge

Die Variable DATE_FORMAT spezifiziert das Datumsformat, das für neue Einträge verwendet werden soll. Das Standardformat ist die Ausgabe des date Kommandos. Außerdem kann die Lokalisierung angegeben werden, die das date-Kommando benutzen soll (siehe Variable DATE_LOCALE). Zusätzliche Kommandozeilenparameter können durch die Variable DATE_ARGS angegeben werden, nützlich zum Angeben der Zeit in UTC. Allerdings haben diese Änderungen keine Auswirkung auf bereits existierende Einträge. Für mehr Informationen zum date-Kommando und die Konfigurationsmöglichkeiten bitte in der man-page des date-Kommando nachlesen.

Beispiele:

        DATE_FORMAT="%m.%d.%Y %H:%M"
        DATE_LOCALE="$LANG"
        DATE_ARGS="-u"

Einstellen der Zeitzone für die Syndikationen

BLOG_TZD setzt die Zeitzone für die Syndikation des Weblog. Standardmäßig wird `"%z"`, eine nicht standardisierte Erweiterung des date-Kommandos verwendet. Wenn das date-Kommando des Systems diese Erweiterung nicht unterstützt muss dieses Variable manuell gesetzt werden. Vielleicht kann der Systemadministrator GNU date installieren.

Beispiel:

    BLOG_TZD="-0:500"

Einstellen des Zeichensatzes

BLOG_CHARSET setzt den zu verwendenden Zeichensatz für das Weblog.

Beispiel:

    BLOG_CHARSET="iso-8859-1"

WARNUNG: Wenn das Tidy Plugin verwendet wird, wird diese Einstellung von Tidy überschrieben. Wie man bei Tidy den Zeichensatz einstellt, ist bitte der Beschreibung von Tidy zu entnehmen.

Setzen des Mimetype

BLOG_MIMETYPE setzt den Mimetype der für das Weblog verwendet werden soll.

Beispiel:

    BLOG_MIMETYPE="text/html"

Setzen der Web-Adresse

BLOG_URL sollte auf die komplette URL des Weblog ohne die Index-Datei und abschließendem "/" gesetzt werden. Diese Einstellung wird für alle absoluten Links und die Syndikations-Feeds benötigt.

Beispiel:

    BLOG_URL="http://my-site.com/weblog"

Setzen des Style Sheet

BLOG_CSS setzt das Style Sheet, das vom Weblog verwendet werden soll. Style sheets befinden sich im styles Verzeichnis.

Beispiel:

    BLOG_CSS="styles/nb_rusted.css"

Setzen des Favoriten Icons

BLOG_ICON setzt das Favoritenicon, das für das Weblog benutzt werden soll. Favoritenicons befinden sich im images Verzeichnis.

Beispiel:

    BLOG_ICON="images/favicon.ico"

Einstellen ob absolute Links verwendet werden

ABSOLUTE_LINKS schaltet das Erzeugen von absoluten Links ein. Der Standardwert ist "0", deaktiviert.

Setzen des Link für ein Verzeichnis-Index

NB_INDEX legt fest wie auf ein Verzeichnis-Index zugegriffen wird.Der Standardwert ist leer.

Beispiel:

    NB_INDEX="index.html"

Setzen des Namens des Autors

BLOG_AUTHOR kann benutzt werden um dem Namen des Autors zu setzten. Standardmäßig wird der Name aus der Variablen USER genommen. Durch das Setzen der Variablen BLOG_AUTHOR wird dieses Verhalten übersteuert.

Setzen der Anzahl der maximal auf der Hauptseite angezeigten Einträge

MAX_ENTRIES setzt die maximale Anzahl von Einträgen, die auf der Hauptseite angezeigt werden. Standardwert ist "10".

Setzen der maximalen Anzahl von Einträgen pro Seite

MAX_PAGE_ENTRIES setzt die maximale Anzahl von Einträgen die auf einer Seite angezeigt werden. Standardwert ist "$MAX_ENTRIES".

Setzen der Standard-Textformatierung

ENTRY_FORMAT specifies the default text formatting to use for an entry. Defaults to "raw".

Umschalten der Anzeige von permanenten Links

PERMALINKS schaltet die Anzeige von permanenten Links für Einträge um. Standardmäßig werden permanente Links angezeigt.

Umschalten der Erzeugung von Archiven von Einträgen

Durch das Setzen der Variablen ENTRY_ARCHIVES auf "1", aktiviert die Erzeugung von Eintragsarchiven und ändert die Linkeinstellungen in der Form, dass die Links der Einträge auf die Archivseiten zeigen. Hinweis: Diese Einstellung führt zu einer längeren Aktualisierungsdauer, da mehr Seiten erzeugt werden müssen.

Spezielle Voreinstellungen zur Archivierung von Kategorien

CATARCH_DATATYPE ermittelt die Daten, die für das Kategorie-Archiv geladen werden müssen. Es gibt zwei Arten von Daten, die angegeben werden können, "ALL" und "NOBODY"

          ALL = alle Metadaten eines Eintrags (langsam und großer Cache)
          NOBODY = alle Metadaten außer dem Body (schneller und kleinerer Cache)

WICHTIG: Bitte die Datei category_entry.htm entsprechend anpassen.

Setzen der chronologischen Sortierung

CHRON_ORDER gibt die chronologische Sortierung des Weblogarchiv an - 0/1 = normal/invers. Standardwert ist "1", inverse Sortierung.

Setzen der Befehle für die Vorschau und zum Veröffentlichen

BLOG_PREVIEW_CMD und BLOG_PUBLISH_CMD können beide auf ein beliebiges Kommando gesetzt werden, das ausgeführt wird wenn die dazugehörige Option --preview oder --publish angegeben wurde.

Setzen der Cache Einstellungen

MAX_CACHE_ENTRIES setzt die maximale Anzahl von Einträgen, die im Cache gespeichert werden. Standardwert ist "$MAX_ENTRIES".

Wird BLOG_CACHEMNG auf "0" gesetzt, dann wird der automatische Cache abgeschaltet. Der Cache kann manuell durch die Kommandozeilenoption `--update-cache` verwaltet werden.

Umschalten des interaktiven Modus

BLOG_INTERACTIVE schaltet den interaktiven Modus für das Weblog ein bzw. aus und hat den gleichen Effekt wie die Kommandozeilenoption `--interactive`. Der Standardwert ist "0" und die Option damit abgeschaltet, durch setzen auf "1" wird die Option aktiviert.

Ändern des Dateityps

NB_FILETYPE spezifiziert den Dateityp oder besser gesagt das Suffix der generierten Dateien. Der Standardwert ist "html".

Ändern des Standard Abfrage Modus

QUERY_MODE spezifiziert den Standard Abfrage Modus beim Auflisten der Eintrage und beim Anzeigen auf der Hauptseite. Standardwert ist "$MAX_ENTRIES".

Plugin Einstellungen

PLUGINS_DIR spezifiziert das Verzeichnis, in dem die Plugins installiert sind. Der Standardpfad lautet $NB_BASE_DIR/plugins. Hinweis: Wenn PLUGINS_DIR gesetzt wurde, wird vorausgesetzt, dass einige Unterverzeichnisse existieren. Deshalb kann es einfacher sein, das vorgegebene Pluginverzeichnis mit den Unterverzeichnissen an die gewünschte Stelle zu kopieren.

Global Einstellungen

NanoBlogger hat eine eigene Konfigurationsdatei $NB_BASE_DIR/nb.conf, die die Optionen enthält, die für alle Weblogs gelten sollen. Diese globale Konfiguration wird als erstes eingelesen. Das bedeutet, dass die lokalen Einstellungen eines Weblogs die globalen in $NB_BASE_DIR/nb.conf überschreiben. Diese Datei kann sich auch unter $HOME/.nb.conf befinden.

Ändern der Standardsprache von NanoBlogger

NB_LANG ist eine globale Konfigurationsvariable und setzt die zu ladende Sprachdefinition. Der Standardwert ist "en" für Englisch. Für deutsche Meldungen muss der Wert auf "de" geändert werden.

Beispiel:

    NB_LANG="de"

## 7. Verwalten von Einträgen und Kategorien

Kommandos zum Verwalten von Einträgen und Kategorien.

### Verwalten von Einträgen

Eintrag IDs

Der Eintrag, der als letzter hinzugefügt wurde bekommt immer die ID "1". Alle Einträge, die davor hinzugefügt wurden haben entsprechend höhere IDs. Ein Eintrag kann in jeder Kategorie zu der er gehört eine andere ID haben. Wenn ein Eintrag aus einer Kategorie modifiziert werden soll, müssen die IDs für die Kategorie und den Eintrag angegeben werden.

Einträge entwerfen

Erzeugen eines neuen Entwurfs:

    nb [-b blog_dir] --draft draft.txt

Importieren eines Entwurfs als neuer Eintrag:

    nb [-b blog_dir] --file draft.txt -a

Erzeugen eines Eintrags

Hinzufügen eines neuen Eintrags:

    nb [-b blog_dir] -a

Hinzufügen eines Eintrags zu einer Kategorie:

    nb [-b blog_dir] -c 1 -a

Setzen von Titel und Autors für einen neuen Eintrag:

    nb [-b blog_dir] -t "New Entry" -n [entry_author] -a

Setzenvon Titel, Autor und Text eines neuen Eintrags:

    nb [-b blog_dir] -t "New Entry" -n [entry_author] -T "This is my message." -a

Importieren eines neuen Eintrags aus einer Datei:

    nb [-b blog_dir] --file draft.txt -a

Listing Entries

Anzeigen der aktuellsten Einträge:

    nb [-b blog_dir] -l

Auflisten aller Einträge:

    nb [-b blog_dir] -l all

Auflisten der Einträge einer Kategorie:

    nb [-b blog_dir] -c 1 -l

Bearbeiten von Einträgen

Bearbeiten des zuletzt erzeugten Eintrags:

    nb [-b blog_dir] -e 1

Bearbeiten eines Eintrags einer Kategorie:

    nb [-b blog_dir] -c 1 -e 1

Bearbeiten mehrerer Einträge:

    nb [-b blog_dir] -e 1,2,3

Verschieben von Einträgen

Verschieben eines Eintrags in eine Kategorie:

    nb [-b blog_dir] -c 1 -m 1

Verschieben eines Eintrags in mehrerer Kategorien:

    nb [-b blog_dir] -c 1,2,3 -m 1

Verschieben mehrerer Einträge in eine Kategorie:

    nb [-b blog_dir] -c 1 -m 1,2,3

Einträge löschen

Einträge dauerhaft löschen:

    nb [-b blog_dir] -d 1

Mehrere Einträge dauerhaft löschen:

    nb [-b blog_dir] -d 1,2,3

Einen Eintrag aus einer Kategorie löschen:

    nb [-b blog_dir] -c 1 -d 1

Datum eines Eintrags ändern

Spezifizieren des Datums für einen neuen Eintrag mit dem TIMESTAMP Metatag:

    nb [-b blog_dir] --tag TIMESTAMP --tag-text "YYYY-MM-DD HH:MM:SS" -a

Ändern des Datums eines alten Eintrags:

    nb [-b blog_dir] --tag TIMESTAMP --tag-text "YYYY-MM-DD HH:MM:SS" -e 2

Das Datum eines Eintrags manuell ändern:

        1. nb [-b blog_dir] -e 2
        2. TIMESTAMP: YYYY-MM-DD HH:MM:SS

Das date Kommando muss die "`-d`" Option unterstützen, damit date das Format verwendet, das mit "`$DATE_FORMAT`" gesetzt wurde.

### Verwalten von Kategorien

Kategorie IDs

Kategorie IDs werden von "1" an hochgezählt. Eine Kategorie ID behält ihren Wert, bis sie gelöscht wird. Wenn eine Kategorie gelöscht wird, wird deren ID freifür die nächste Kategorie die angelegt wird.

Kategorie Kommandos

Erzeugen einer neuen Kategorie:

    nb [-b blog_dir] -c new -a

Setting the title for a new category:

    nb [-b blog_dir] -t "New Category" -c new -a

Verfügbare Kategorien auflisten:

    nb [-b blog_dir] -l cat

Bearbeiten eines Kategorietitel:

    nb [-b blog_dir] -c 1 -t "News" -e cat

Löschen einer Kategorie:

    nb [-b blog_dir] -c 1 -d cat

## 8. Vorlagen

Vorlagen befinden sich im Weblog Unterverzeichnis "templates".

Spezielle Zeichen für Vorlagen

WICHTIG: Maskieren dieser Zeichen verhindert, dass sie geändert werden.

Spezielle Zeichen, die einfluss auf eine Vorlage haben:
Zeichen | Beschreibung | Hinweise
--- | --- | ---
$ | Dollar Symbol | Um ein Dollar Symbol zu erhalten muss ein Backslash davorgeschrieben werden, z.B. "\$"
` | Rückwärtsgerichtetes einfaches Anführungszeichen (back quote) | Art der Kommandoersetzung, Backslash zum maskieren davorschreiben, z.B. "\`"
$( | Dollar Symbol und runde Klammer auf | Art der Kommandoersetzung, Backslash zum maskieren davorschreiben, z.B. "\$("

Standard Vorlagen

Das Aussehen des Weblog wird durch die folgenden Vorlagen gesteuert:
Vorlage | Beschreibung
--- | ---
category_archive.htm | Steuert das Aussehen der Kategorieseiten
main_index.htm | Steuert das Aussehen der Weblog Hauptseite
main_links.htm* | Enthält benutzerdefinierte Links
makepage.htm | Enthält die Standardvorlage, die von der Option makepage benutzt wird
month_archive.htm | Steuert das Aussehen der Monats-Archivseite
permalink.htm | Steuert das Aussehen eines Eintrags in der Archivseite
entry.htm | Steuert das Standardaussehen eines Archiveintrags
category_entry.htm | Steuert das Aussehen eines Kategorieeintrags
permalink_entry.htm | Steuert das Aussehen der permanenten Archiveinträge
weblog_status.htm | Steuert das Aussehen des Weblog Status
year_archive.htm | Steuert das Aussehen der jährlichen Archiv Seiten
entry.metadata | Steuert das Format der Eintrags Metadatei
file.metadata | Steuert das Format einer Metadatei

## 9. Über Plugins

### Gerüst für Plugins (Framework)

Standard Plugins: plugins

Diese Plugins werden immer initialisiert.

Archiv Plugins: plugins/archive

Diese Plugins werden initialisiert wenn das Archiv aktualisiert wird.

Monats Plugins: plugins/archive/month

Diese Plugins werden für jedes monatliche Archiv initialisiert, das aktualisiert wird.

Jahres Plugins: plugins/archive/year

Diese Plugins werden für jedes jährliche Archiv initialisiert, das aktualisiert wird.

Eintrags Plugins: plugins/entry

Diese Plugins werden immer für jeden aktualisierten Eintrag initialisiert.

Plugins für modifizierte Einträge: plugins/entry/mod

Diese Plugins werden für jeden modifizierten Eintrag initialisiert.

Eintrag Formatierungs Plugins: plugins/entry/format

Diese Plugins werden bei jedem geänderten Eintrag abhängig vom FORMAT Metadatenfeld initialisiert. Es können mehrere Formate durch Komma oder Leerzeichen getrennt angegeben werden.

Seiten Plugins: plugins/page

Diese Plugins werden immer initialisiert, bevor eine Seite aktualisiert wird.

Seitenformatierungs Plugins: plugins/page/format

Diese Plugins werden für jede aktualisierte Seite abhängig vom FORMAT Metadaten Feld initialisiert. Mehrere Formate können mit Komma oder Leerzeichen getrennt angegeben werden.

Seitenerstellungs Plugins: plugins/makepage

Diese Plugins werden immer nach jeder aktualisierten Seite initialisiert.

Post Plugins: plugins/post

Post Plugins werden immer für Post-Weblog Aufgaben initialisiert.

Die meisten Plugins arbeiten unter ihren eigenen Bedingungen nachdem sie initialisiert wurden.

Standard Plugins

Standard Plugins (die meisten sind standardmäßig aktiviert):
Plugins | Beschreibung | Variablen | Ziele | Hinweise
--- | --- | --- | --- | ---
archive/master_index.sh | erzeugt die Hauptindexseite eine Archivs | keine | $ARCHIVES_DIR/index.$NB_FILETYPE | benötigt die makepage.htm Vorlage
archive/month/month_calendar.sh | generiert einen Kalender mit Links für jeden aktiven Tag | keine | $NB_MonthlyCalendar | benötigt cal
archives/year/year_index.sh | generiert jährliche Indizes für die Archive | keine | $ARCHIVES_DIR/$yearn/index.$NB_FILETYPE | benötigt die makepage.htm Vorlage
articles_meta.sh* | generiert Artikel aus Metadateien aus dem "articles" Verzeichnis | ARTICLE_DIRS, ARTICLE_FORMAT | $NB_ArticleLinks | benötigt die makepage.htm Vorlage, dieses Plugin muss als letztes geladen werden
articles_text.sh* | generiert Artikel aus Textdateien aus dem "articles" Verzeichnis | ARTICLE_DIRS, ARTICLE_FORMAT | $NB_ArticleLinks | benötigt die makepage.htm Vorlage, dieses Plugin muss als letztes geladen werden
atom.sh | fügt einen Atom-Feed hinzu | LIMIT_ITEMS, ATOM_CATFEEDS, BLOG_FEED_LANG | $NB_AtomVer, $NB_AtomFile, index-atom.$NB_SYND_FILETYPE | keine
calendar.sh | generiert einen Kalender mit Links für jeden aktiven Tag | CAL_CMD, CAL_ARGS | $NB_Calendar | benötigt cal
entry/category_links.sh | generiert Kategorie-Links | keine | $NB_EntryCategories | keine
entry/excerpt.sh* | erzeugt einen Auszug des Eintragtextes | keine | $NB_EntryExcerpt | endet nach der ersten entdeckten doppelten Zeilenende (Leerzeile)
entry/format/autobr.sh | konvertiert Leerzeilen in HTML Paragraphen | keine | $NB_MetaBody, $NB_EntryBody | FORMAT: autobr
entry/format/markdown.sh | verwendet Markdown für die Formatierungen | keine | $NB_MetaBody, $NB_EntryBody | FORMAT: markdown
entry/mod/base_url.sh | hilft beim Setzen von relativen Links | %base_url% | $NB_EntryBody | Beispiel: <img src="%base_url%images/pic.png" />
entry/mod/moods.sh | konvertiert Stimmungsvariablen in Smiley-Icons | MOODS_URL | $NB_EntryBody | das moods Verzeichnis muss in das Weblog-Verzeichnis kopiert werden
fortune.sh | generiert ein zufälliges Zitat | FORTUNE_FILE | $NB_Fortune | benötigt fortune
makepage/tidy.sh | überprüft HTML/XML Code | TIDY_HTML_ARGS, TIDY_XML_ARGS | $NB_Tidy, $BLOG_DIR/tidy.log | benötigt HTML Tidy, tidy überschreibt $BLOG_CHARSET
mymood.sh* | fügt die Möglichkeit hinzu die Stimmung an zu zeigen | MOODS_URL | $NB_MyMood | das moods Verzeichnis muss in das Weblog-Verzeichnis kopiert werden
page/feed_links.sh | generiert alt Links für die Feeds | keine | $NB_AtomAltLink, $NB_RSS2AltLink, $NB_RSSAltLink | benötigt eines der Plugins: atom.sh, rss.sh, or rss2.sh
page/page_links.sh | aktualisiert die Links zum Einbinden in andere Seiten | keine | $NB_MainLinks, $NB_RecentEntries, $NB_CategoryLinks, $NB_MonthLinks, etc. | benötigt eines der Plugins: weblog_links.sh oder recent_entries.sh
page/format/autobr.sh | konvertiert Leerzeilen in HTML Paragraphen | keine | $NB_MetaBody, $NB_EntryBody | FORMAT: autobr
page/format/markdown.sh | verwendet Markdown für die Formatierung | keine | $NB_MetaBody, $NB_EntryBody | FORMAT: markdown
page/format/moods.sh | konvertiert Stimmungs-Variablen in Smiley-Icons | MOODS_URL | $NB_MetaBody, $NB_EntryBody | kann mit anderen kombiniert werden, wie z.B. "FORMAT: moods, markdown"
recent_entries.sh | generiert Links zu aktuellen und alten Einträgen | LIST_N, LIST_OFFSET | $NB_RecentEntries, $NB_OlderEntries | keine
rss2.sh | fügt RSS 2.0 Feeds hinzu | LIMIT_ITEMS, RSS2_CATFEEDS, BLOG_FEED_LANG | $NB_RSS2File, index-rss.$NB_SYND_FILETYPE | keine
rss.sh | fügt RSS 1.0 Feeds | LIMIT_ITEMS, RSS_CATFEEDS, BLOG_FEED_LANG | $NB_RSSFile, index.$NB_SYND_FILETYPE | keine
weblog_links.sh | generiert einige nützliche Links | ALL_YEARLINKS, MAX_YEARLINKS, ALL_MONTHLINKS, MAX_MONTHLINKS | $NB_MainLinks, $NB_MonthLinks, $NB_CategoryLinks | benötigt die main_links.htm Vorlage
weblog_status.sh | generiert einige Statistiken | keine | $NB_BlogStatus | benötigt das weblog_status.htm Template

* = der eigentliche Name kann abweichen.

Um ein einzelnes Plugin zu deaktivieren, muss lediglich die Endung von ".sh" in ".off" umbenannt werden.

## Plugins schreiben

### Tools zum Entwickeln von Plugins

Plugins funktionieren im Allgemeinen so, dass Platzhalter für die Vorlagen erzeugt werden, aber darauf sind Plugins in keiner weise beschränkt. Die Platzhalter erlauben eine große Kontrolle über die Platzierung der Ausgaben der Plugins in einer Vorlage. Bei einigen Plugins muss man eventuell selbst herausfinden, welche speziellen Platzhalter verwendet werden um diese Dann zu den Vorlagen manuell hinzu zufügen.

Um ein Plugin zu schreiben, sollte man damit beginnen eine Textdatei mit der Endung ".sh" zu erzeugen. Plugins sind im Grunde Shell-Skripte, die geladen werden abhängig davon, ob sich das Skript im Plugin-Verzeichnis oder in einem Plugin-Unterverzeichnis befindet. Vielleicht ist es eine gute Idee erst einmal mit einem einfachen Skript, wie z.B. fortune.sh zu beginnen um eine Idee davon zu bekommen, wie Plugins funktionieren. Wenn ein neues Plugin gespeichert wird, muss es die passenden Leserechte besitzen, damit es von NanoBlogger geladen werden kann. Rechte zum Ausführen sind für Plugins nicht notwendig.

Nachfolgend kommt eine Sammlung von Tools, die nützliche beim Entwickeln von eigenen Plugins sein können.

Plugin API

API zum Schreiben von Plugins.
Kommando | Beschreibung | Variablen | Ziele | Hinweise
--- | --- | --- | --- | ---
die | beendet mit einer Fehlermeldung | $@ | console | liefert Exit Status 1 zurück
nb_msg | bevorzugte Methode zum Ausgeben von Meldungen | $@ | console | sollte wenn möglich anstelle von echo verwendet werden
confirm_action | fragt den Anwender nach einer Bestätigung für eine Aktion | keine | console | kann mit $BLOG_INTERACTIVE verwendet werden
chg_suffix | ändert die Endung einer Datei | filename=$1, suffix=$2 | file | kann $NB_FILETYPE, $NB_SYND_FILETYPE als Dateiendung angeben
query_db | Anfrage an die Datenbank | db_query=$1, db_catquery=$2, db_setlimit=$3 db_limit=$4, db_offset=$5 | $DB_RESULTS | Beispiel (liefert die Einträge 1 bis 10): "query_db all nocat limit 10 1"
lookup_entryid | sucht eine Eintrag-ID aus der Hauptdatenbank | $1, $2 | console oder redirect | Beispiel: lookup_entryid 2005-12-14T00_00_00.$NB_DATATYPE "$MASTER_DB_RESULTS"
lookup_monthid | sucht eine Monats-ID aus dem "months" Abfragetyp | $1, $2 | console oder redirect | Beispiel: query_db months; lookup_monthid 2005-12 "$MONTH_DB_RESULTS"
set_title2link | Wandelt Text für die Verwendung in Links um | $1 | console oder redirect | keine
set_baseurl | hilft beim Setzen von relativen Links | node_var=$1, base_dir=$2 | $BASE_URL, $ARCHIVES_PATH | es sollte nur entweder node_var oder base_dir angegeben werden
set_catlink | setzt einen Verweis und die Datei für die angegebene Kategorie | $1 | $category_file, $category_link | Die Kategorie sollte in der Form, cat_N.$NB_DBTYPE angegeben werden
set_monthlink | setzt einen Verweis und die Datei für den angegebenen Monat | $1 | $month_file, $month_link | der Monat sollte in der Form YYYY-MM angegeben werden
set_entryid | setzt den Anchor/ID für den angegebenen Eintrag | $1 | console oder redirect | der Eintrag sollte in der Form YYYY-MM-DDTHH_MM_SS.$NB_DATATYPE angegeben werden
set_entrylink | setzt einen Verweis und die Datei für den angegebenen Eintrag | $1 | $entry_dir, $permalink_file, $NB_EntryPermalink | der Eintrag sollte in der Form YYYY-MM-DDTHH_MM_SS.$NB_DATATYPE angegeben werden
update_cache | erstellt eine Liste oder entfernt gecachte Einträge | cache_update=$1, cache_def=$2, CACHEUPDATE_LIST=$3 | $CACHE_LIST | wird im Allgemeinen dazu verwendet veraltete gecachte Daten zu löschen
load_template | lädt eine Vorlage aus einer Datei | TEMPLATE_FILE=$1 | $TEMPLATE_DATA | die Daten einer Vorlage niemals mehr als einmal laden, denn make_page ruft load_template
write_metadata | schreibt Metadaten in eine Datei | MTAG=$1, METADATA=$2, META_FILE=$3 | $META_FILE | Beispiel: "write_metadata UPDATED "`date`" $metafile"
read_metadata | extrahiert Metadaten aus einem Eintrag/einer Datei | MTAG=$1, META_FILE=$2 | $METADATA | Ein gutes Beispiel dafür ist das Plugin recent_entries.sh
write_tag | erzeugt/modifiziert ein Anwender Metadatenfeld | WRITE_MTAG=$1, WRITE_MTAGTEXT=$2, WRITEMETATAG_FILE=$3 | $WRITEMETATAG_FILE | Beispiel: write_tag MODTIME "$(date)"
loop_archive | läuft in einer Schleife durch die Archive und führt Anweisungen pro Jahr oder Monat aus | looparch_list=$1, looparch_type=$2, looparch_exec=$3 | ermittelt durch $looparch_exec | Beispiel: "query_db max; loop_archive "$DB_RESULTS" months make_monthlink"
load_entry | lädt Eintragsdaten für die Verwendung in Vorlagen | ENTRY_FILE=$1, ENTRY_DATATYPE=$2, ENTRY_CACHETYPE=$3 | $NB_EntryTitle, $NB_EntryBody, ... | das Plugin atom.sh ist ein gutes Beispiel für die Verwendung
make_page | erzeugt eine Weblogseite aus einer Textdatei | MKPAGE_SRCFILE=$1, MKPAGE_TMPLFILE=$2, MKPAGE_OUTFILE=$3 | $MKPAGE_CONTENT, $NB_MetaBody | das Plugin articles.sh ist ein gutes Beispiel für die Anwendung
weblog_page | erzeugt eine Weblogseite aus einer Metadatei | BLOGPAGE_SRCFILE=$1, BLOGPAGE_TEMPLATE=$2, $BLOGPAGE_OUTFILE=$3 | $MKPAGE_CONTENT, $NB_MetaBody | das Plugin articles_meta.sh ist ein gutes Beispiel für die Anwendung

## 11. Veröffnetlichen

Setzen des Publish-Kommando

Die BLOG_PUBLISH_CMD Variable erlaubt es ein Kommando zum Veröffentlichen des Weblog anzugeben. Dies kann ein einfaches Kommando zum Hochladen via FTP sein oder eine komplexe Folge von Anweisungen in Form eines Skriptes.

Im Netz veröffentlichen

FTP, SSH (scp, sftp, etc.), RSYNC oder WebDAV, sind alles Methoden diw verwendet werden können um das Weblog zu veröffentlichen.

Beispiel: automatisches Veröffentlichen mit ftp und .netrc.

blog.conf:

    BLOG_PUBLISH_CMD="ftp example.weblog.com"

. netrc:

    machine example.weblog.com login foo password
    RIGHT!
    macdef init
    passive on
    prompt off
    lcd ~/public_html/blog
    mput *.*
    cd archives
    lcd archives
    mput *

Lokal veröffentlichen

Wenn lokal veröffentlicht werden soll, kann das Kommando zum Veröffentlichen deaktiviert werden. Dazu wird BLOG_PUBLISH_CMD auf Null gesetzt. z.B. BLOG_PUBLISH_CMD=""

## 12. Unterstützung für Kommentare hinzufügen

Für die Unterstützung von Kommentaren eignet sich das PHP-Skript NanoBlogger Comments [2]. Es ist einfach, bietet Unterstützung für Accounts und ist einfach zu installieren.

Um ein Kommentarsystem in das Weblog zu integrieren, müssen die entsprechenden Vorlagen angepasst werden. Bitte nach Beispielen in der blog.conf und den Vorlagen sehen.

## 13. Importieren von Einträgen auf die harte Tour

Um Einträge auf die harte Tour zu importieren, müssen die Daten zuerst in das NanoBlogger Format konvertiert werden.

Das Format eines Eintrags

Der Dateiname eines Eintrags hat das Format:

    YYYY-MM-DDTHH_MM_SS.txt

Ein typischer Dateiname eines Eintrags sieht somit z.B. so aus:

    2004-06-25T22_24_37.txt

Das Format eines Eintrags besteht aus Metadaten. Jeder Teil dieser Metadaten ist in der Form Schlüssel: Wert(KEY: VALUE), gefolgt von einem Zeilenende (carriage return), das die einzelnen Teile voneinander trennt. Die Reihenfolge der Metadaten ist nicht wichtig.

Beispiel zum Format eines Eintrags:

        TITLE: Ein neuer Eintrag
        AUTHOR: foo
        DATE: January 30 2004, 12:00 PM
        DESC: Schlüsselworte oder eine kurze einzeilige Zusammenfassung
        FORMAT: raw
        -----
        BODY:
        Dies ist mein neuer Eintrag ...
        END-----

Konvertieren von Einträgen

Bevor Einträge importiert werden können, müssen sie in das richtige Format konvertiert werden.

Schritte zum Konvertieren von Einträgen:

        1. Konvertiere jeden Eintrag so, dass er jedes der folgenden
        Metadaten enthält: TITLE, AUTHOR, DATE, DESC, FORMAT, BODY
        2. Der BODY mit "END-----" beendet werden.
        3. Jede Eintragsdatei entsprechend der passenden Zeit und Datum umbenennen.

Wenn es sich dabei um mehrere Einträge handelt, dann macht es vielleicht Sinn die Konvertierung durch ein Skript zu automatisieren.

Aktualisieren des Datenverzeichnises des Weblog

Die importierten Einträge müssen in das data Verzeichnis des Weblog kopiert werden.
Dann wird das Weblog mit seinen neuen Einträgen aktualisiert:

    nb [-b blog_dir] -u all

## 14. Tipps und Tricks

Nützliche Kommandos zum Schreiben von Einträgen

Erzeugen einer neuen Metadatei:

    nb [-b blogdir] --makefile somefile.txt

Importieren einer Metadatei als neuer Weblogeintrag:

    nb [-b blogdir] --file somefile.txt --add

oder exportieren der Metadatei als neue Weblogseite:

    nb [-b blogdir] --makepage somefile.txt somefile.html

Hinweis: Um diese Funktionalität zu bieten, muss der Editor in irgendeiner Art Sub-Shells unterstützen. Oder man suspendiert den Editor in der aktuellen Shell(vorausgesetzt da ist eine).

Schreiben Metatags auf der Kommandozeile

Metatags können auch auf der Kommandozeile angegeben werden. z.B., Textformatierungen können über die Kommandozeile angegeben werden.

    nb [-b blogdir] --tag FORMAT --tag-text "markdown" --makepage
        somefile.txt somefile.html

Setzen eines Standard-Weblog-Verzeichnis

Standardmäßig muss das Weblog-Verzeichnis durch das Setzen von BLOG_DIR angegeben werden, aber das ist nicht zwingend notwendig. In der Datei nb.conf oder $HOME/.nb.conf kann das Verzeichnis angegeben werden:

    BLOG_DIR="/path/to/weblog"

Shell-Skripte in die Vorlagen einbauen

Es ist möglich Kommandoersetzung in den Vorlagen in einer der folgenden Formen zu verwenden:

    $(command) oder `command`

Eine Einleitung zum Weblog hinzufügen

Dazu muss sich eine Datei mit dem Namen "intro.txt" im Weblog-Verzeichnis befinden. Diese kann beliebigen Text und HTML-Tags enthalten. Dann muss nur noch die folgende Zeile in die Hauptvorlage des Weblog kopiert werden:

    $(< "$BLOG_DIR/intro.txt")

Teile des Weblogs in eine andere Seite integrieren

Viele Teile des Weblogs werden in dem parts Verzeichnis gespeichert. Sagen wir, es gibt bereits eine komplette Webseite voll von selbstgemachten Server-Side Scripts/Includes. Das ist der Punkt, an dem die "parts/index.html" Datei ins Spiel kommt. Sie beinhaltet alle aktuellen Einträge und somit ist das hinzufügen einer News/Diary/Blog Sektion nur eine Frage von Code, der "parts/index.html" in die Seite integriert. Danach hat man eine einfache weblogartige Seite, die immer aktualisiert wird, wenn sich index.html ändert.

Andere clevere Anwender kombinieren die statischen Ausgaben von NanoBlogger mit PHP oder Perl. Zum Beispiel, wenn man so raffinierte Verknüpfungen, wie die aktuellen Einträge oder Archive mit PHP benutzen möchte, dann setzt man NB_FILETYPE auf PHP und modifiziert die entsprechenden Vorlagen und fügt den PHP-Code ein, der die Daten auf dem parts-Verzeichnis extrahiert. Einer der Hauptvorteile ist, dass es nicht notwendig ist, das komplette Weblog neu gebaut werden muss, man muss nur die Verknüpfungen aktuell halten.

Einbetten von Variablen in die Vorlagen

Alle Zeichen die Shellvariablen oder Kommandoersetzungszeichen entsprechen müssen maskiert werden, damit sie in einer Vorlage verwendet werden können.

Beispiel zur Verwendung von Variablen im PHP code:

        <?php
        \$VAR = array ();
        echo "\\\$VAR=\$VAR";
        php?>

## 15. Credits

Vielen Dank an Adrien "ze" Urban, Paul Drain, Pavel Janik, und O.R.Senthil Kumaran für alle Beiträge und Vorschläge. Vielen Dank an Bowie J. Poag, dem Autor von MicroBlogger [3], für die Inspiration zu diesem Projekt.

1. http://nanoblogger.sf.net/downloads/
2. http://nhw.pl/blg/articles/nbcom/
3. http://freshmeat.net/projects/microblogger

Copyright © 2003-2006 Kevin Wood. All Rights Reserved.