Thema: GeSHI mit eigenen Zeilennummern

Zurzeit arbeite ich an einer Webseitendokumentation, die mit Joomla (1.5.9) umgesetzt werden soll. Dabei fiel mir auf, dass man bei dem integrierten GeSHI-Plugin nur zwei Parameter zur Verfügung hat (language und lines). Da ich aber Änderungen an einigen Dateien dokumentieren möchte, benötige ich eine Möglichkeit, die Zeilennummern selbst zu bestimmen (um etwa Änderungen ab Zeile 203 zu zeigen).

GeSHI kann dies (auch schon in der in Joomla 1.5.9 integrierten Version).
Wie man diese Funktion nachrüstet möchte ich nun in diesem kleinen HowTo darlegen.
Am Ende dieser Anleitung ist auch noch beschrieben, wie man die in Joomla 1.5 vorhandene Version von GeSHI um weitere Sprachen erweitert. So ist auch ein Update möglich.

1. Anpassen der Datei /plugins/content/geshi.php (das Plugin)
Nach Zeile 60:

PHP-Code:

    $lines    = JArrayHelper::getValue( $args, 'lines', 'false' ); 


folgendes einfügen:

PHP-Code:

    $number    = JArrayHelper::getValue( $args, 'number', '0' ); 


Und nach Zeile 83:

PHP-Code:

        $geshi->enable_line_numbers( GESHI_NORMAL_LINE_NUMBERS ); 


folgendes einfügen:

PHP-Code:

    if ($number > 0) {
        $geshi->start_line_numbers_at( $number );
    } 


Dadurch kann ein dritter Parameter number als Integer übergeben werden.
Wird dieser übergeben und ist größer als 0 (muss laut GeSHI-Spezifikation so sein), wird dieser als Ausgangs-Zeilennummmer verwendet.

2. GeSHI Im Plugin Manager des Backendes aktivieren
Dazu im Backend einloggen und unter Extensions > Plugin Manager das Plugin Content - Code Hightlighter (GeSHi) aktivieren.

3. Im Artikel (wo GeSHI verwendet werden soll)
Statt (zum Beispiel):

HTML-Code:

<pre xml:lang="php" lines="true">[...]</pre>

dies verwenden:

HTML-Code:

<pre xml:lang="php" lines="true" number="5">[...]</pre>

Das erzeugt eine GeSHI Formatierung in PHP mit Zeilennummern, die ab der Zeile 5 beginnnen.

Hinweise:
1. Mit dieser Methode (start_line_numbers_at) wird das "Start"-Attribut auf den <ol>-Tag, der für die Zeilennumerierung verwendet wird, angewendet. Dies ist kein gültiges XHTML strict Verfahren. Also keine XHTML strict Validierung, wenn number angegeben wurde. Jedoch ist dieses Verfahren XHTML transitional valide.

2. Um den Parameter number nutzen zu können, muss er mindestens 1 oder höher sein und der Parameter lines muss true sein.


4. Optional: GeSHI um weitere Sprachen erweitern
Die in Joomla 1.5.9 integrierte GeSHI Version beherrst nur die Sprachen: css, diff, html4strict, ini, javascript, mysql, php-brief, php, sql und xml.
Um diese zu aktuelisieren, ober um neue Sprachen hinzu zufügen, muss eine aktuelle GeSHI Version (zurzeit 1.0.8.2) heruntergeladen weden (http://qbnz.com/highlighter/).
Das heruntergeladene Archiv entpacken und den Inhalt (bzw. die gewünswchten Sprachen) aus dem Unterverzeichnis /geshi/geshi/ in das Joomla Verzeichnis /libraries/geshi/geshi/ kopieren. So sind auch Sprachen wie Ruby oder Prolog möglich.

5. Optional: GeSHI aktualisieren
Um GeSHI zu aktualisieren, muss eine aktuelle GeSHI Version (zurzeit 1.0.8.2) heruntergeladen weden (http://qbnz.com/highlighter/).
Das heruntergeladene Archiv entpacken, die Datei geshi.php aus dem Unterverzeichnis /geshi/ in das Joomla Verzeichnis /libraries/geshi/ kopieren und die vorhandene Datei übershreiben.

Hinweis:
Ich habe die Sprache PHP aktualisiert. Danach bekam ich einen Anzeigefehler. Um diesen zu beheben, die aktualisierte Datei /libraries/geshi/geshi/php.php öffnen und alle Vorkommen von FNAMEL in FNAME ändern.
Zeile 564:

PHP-Code:

        3 => 'http://www.php.net/{FNAMEL}' 


ändern in:

PHP-Code:

        3 => 'http://www.php.net/{FNAME}' 


Nachtrag (28.03.2009):
Anstatt der oben beschriebenen Änderung an /libraries/geshi/geshi/php.php kann auch die Datei /libraries/geshi/geshi.php aktualisiert werden. Hier empfiehlt es sich dann aber, ebenfalls alle installierten Sprachen im Unterverzeichnis /libraries/geshi/geshi/ zu aktualisieren.

Optional: 6. Zeilenumbrüche
Damit GeSHI die Codesnippsel unter Joomla richtig darstellen kann, müssen diese mit einem <PRE>-Tag verkleidet sein. Dies führt jedoch zu einigen Problemen, da <Pre>-Tags konsequent die CSS-Definitionen des Templates ignorieren und so die Zeilen bei langen Codezeilen sehr weit nach rechts hinaus ragen können.
Abhilfe schafft eine spezielle CSS-Definition der <Pre>-Tags.
Dazu die für das Template zuständige CSS-Datei öffnen und um folgendes ergänzen:

Code:

pre {
	white-space: pre-wrap; /* css-3 */
	white-space: -moz-pre-wrap !important; /* Mozilla, seit 1999 */
	white-space: -pre-wrap; /* Opera 4-6 */
	white-space: -o-pre-wrap; /* Opera 7 */
	word-wrap: break-word; /* Internet Explorer 5.5+ */
	width: 99%;
}

Nachtrag (28.03.2009):
Bekannte Fehler
Mir ist im Lauf der Zeit im Umgang mit GeSHI aufgefallen, dass nicht alles korrekt ausgegeben wird! So werden bei mir zum Beispiel XHTML konforme Zeilenumbrüche (<br />) unter der Sprache PHP nicht angezeigt und stattdessen der Tag interpretiert (also ausgeführt und ein Zeilenumbruch innerhalb der Code-Auflistung erzeugt).
Nachtrag (30.04.2009):
Der obige Fehler wurde behoben.

Ich hoffe, ihr könnt damit was anfangen.
Grinse

Behobener Fehler:

Nachtrag (28.03.2009):
Bekannte Fehler
Mir ist im Lauf der Zeit im Umgang mit GeSHI aufgefallen, dass nicht alles korrekt ausgegeben wird! So werden bei mir zum Beispiel XHTML konforme Zeilenumbrüche (<br />) unter der Sprache PHP nicht angezeigt und stattdessen der Tag interpretiert (also ausgeführt und ein Zeilenumbruch innerhalb der Code-Auflistung erzeugt).

Das Interpretieren von einigen Tags (etwa dem XHTML konformen <br />-Tag) liegt nicht an GeSHI selbst, sondern an dem verwendeten Joomla! Plugin.
Um die <br />-Tags auch in einem GeSHI-Code-Block korrekt auszugeben muss dazu das Joomla Plugin modifiziert werden.

1. Anpassen der Datei /plugins/content/geshi.php (das Plugin)
Zeile 63:

PHP-Code:

    $html_entities_match = array( "|\<br \/\>|", "#<#", "#>#", "|'|", '#&quot;#', '#&nbsp;#' ); 


ändern in:

PHP-Code:

    $html_entities_match = array( "#<#", "#>#", "|'|", '#&quot;#', '#&nbsp;#' ); 


Und Zeile 64:

PHP-Code:

    $html_entities_replace = array( "\n", '<', '>', "'", '"', ' ' ); 


ändern in:

PHP-Code:

    $html_entities_replace = array( '<', '>', "'", '"', ' ' );