Rüdiger Huß

POV-Ray 3.7 for UNIX/Linux – NEWS
There is NO binary release with this version of POV-Ray … it is a source code release only.¹⁾

Die Notwendigkeit unter Linux Software aus den Quellen selbst übersetzen zu müssen ist in den letzten Jahren erheblich gesunken. Alle großen Linux-Distributionen halten fertige Pakete für nahezu alle erdenklichen Anwendungen vor und die Installation selbst dauert meist nur wenige Mausklicks oder Befehlseingaben im Terminal. Ganz im Gegensatz hierzu benötigt man auf dem Weg zum eigenen Compilat viel Zeit und Nerven. Meist ist es nicht mit dem simplen Dreiklang ./configure && make && make install getan. Das Studium der mitgelieferten README und INSTALL Dateien ist dabei noch das Geringste. Da der Autor der Software zum Zeitpunkt der Fertigstellung nicht wissen kann auf welchem Zielsystem übersetzt werden soll, können Angaben bezüglich der erforderlichen Libraries oder Compiler-Optionen abweichen. Entscheidend in dem Prozeß der Konfiguration (./configure) ist es die guten von den schlechten Warnmeldungen unterscheiden zu können und entsprechend zu handeln. Am Ende kann man sich dann immer noch nicht sicher sein, ob man einen sklerotischen Binärkörper erzeugt hat.

Da es z. B. für Linux Mint 17.2 und Ubuntu 14.04 kein fertiges Installationspaket für POV-Ray 3.7 gibt, muß aus den Quellen übersetzt werden. Der Source Code kommt von hier:
https://github.com/POV-Ray/povray/tree/3.7-stable

Mit dem Entpacken der Zip-Datei entsteht das Verzeichnis ./povray-3.7-stable. Hierin sollte die Datei ./povray-3.7-stable/unix/README.md beachtet werden. Die erforderlichen Voraussetzungen und weiteren Verarbeitungsschritte auf dem Weg zur Binärdatei werden dort sehr gut beschrieben. Abweichend davon ist folgendes festzuhalten:
• In der Auflistung der erwarteten Libraries fehlt das libsdl1.2-dev Entwicklerpaket. Ohne diese Library würde während des Render-Vorgangs kein Fenster geöffnet werden, das den Render-Fortschritt darstellen kann. Die aktuellere Version libsdl2-dev funktioniert hier nicht.
• Die Warnmeldungen des Konfigurationsschritts zeigt, daß noch zwei Änderungen in den Dateien prebuild.sh und configure.ac erforderlich sind. So sollten die beiden Einträge anschließend aussehen:

$ sed -n '727p' ./povray-3.7-stable/unix/prebuild.sh
automake --add-missing --warnings=all ###--ignore-deps

$ sed -n '169p' ./povray-3.7-stable/unix/configure.ac
AM_INIT_AUTOMAKE([1.9 dist-bzip2 subdir-objects])

Mehr zum Thema automake dem Makefile-Generator findet man hier:
https://www.gnu.org/software/automake/manual/html_node

Wurden alle Libraries – soweit erforderlich – nachgeladen und die beiden Konfigurationsdateien angepaßt würde sich der anschließende Ablauf so darstellen:

$ cd ./povray-3.7-stable/unix
$ ./prebuild.sh
...
$ cd ..
$ ./configure COMPILED_BY="Dein Name " \
  LIBS="-lboost_system -lboost_thread"
...
$ sudo make install
...
$ povray --version
POV-Ray 3.7.0.unofficial

This is an unofficial version compiled by:
Dein Name 
The POV-Ray Team is not responsible for supporting this version.
...

Als Standard erfolgt die Installation der Binärdatei, Daten-, Dokumentations- und Konfigurations-Dateien im Verzeichnisbereich /usr/local/... Im Home-Verzeichnis ./.povray/3.7 wurden die beiden Config-Files povray.conf und povray.ini erzeugt und sollten noch der Entwicklungsumgebung entsprechend angepaßt werden.
rh2016-01-001

¹⁾ Quelle: https://github.com/POV-Ray/povray/tree/3.7-stable/unix

Wer nach längerer Zeit oder auch erstmalig einen Blick in das Mediathek-Verzeichnis seiner WordPress Installation wirft, mag eine Überraschung erleben. Jedes jemals hochgeladene Bild ist dort in unterschiedlichen Größen mehrfach hinterlegt. Einige entstammen der WordPress Voreinstellung, Vorschaubilder (150 × 150) und mittelgroße Bilder (300 × 300), andere sind Themen spezifisch. Die WordPress Voreinstellungen findet man unter dem Menüpunkt Einstellungen/Medien nebst der Regler für die Anpassung der Bildgrößen.
Das Thema Twentyfifteen selbst erzeugt einen eigenen Crop in der Größenvorgabe 825 × 510 zusätzlich. Sollte das Original zum Beispiel in der Größe 800 × 800 vorliegen, dann wird durch Zuschnitt eine Kopie im Format 800 × 510 erzeugt. Da wahrscheinlich niemand etwas sinnvolles damit anfangen kann, sollte die regelmäßige Produktion einer solchen Kopie von vornherein unterbunden werden. Leider läßt sich das nur durch den Eingriff in den Themen spezifischen PHP-Code erreichen

Zunächst kann man die PHP-Module absuchen nach einer Zeichenkette, die die Angaben »825« und »510« enthalten, etwas davor, vielleicht dazwischen und danach auch:

$ find ./wordpress -type f -print0 | xargs -0 grep -n '^.*825.*510.*$'
./wordpress/wp-content/themes/twentyfifteen/functions.php:81:
	set_post_thumbnail_size( 825, 510, true );
...

In Zeile 81 der Datei wordpress/wp-content/themes/twentyfifteen/functions.php wird demnach die zusätzliche Kopie definiert. Durch einfaches auskommentieren der Zeile kann die zukünftige Kopiebildung unterbunden werden. Die Zeile 81 in der functions.php sieht anschließend dann so aus:

$ sed -n '75,87p' ./wordpress/wp-content/themes/twentyfifteen/functions.php
	/*
	 * Enable support for Post Thumbnails on posts and pages.
	 *
	 * See: https://codex.wordpress.org/Function_Reference/add_theme_support#Post_Thumbnails
	 */
	add_theme_support( 'post-thumbnails' );
	//set_post_thumbnail_size( 825, 510, true );

	// This theme uses wp_nav_menu() in two locations.
	register_nav_menus( array(
		'primary' => __( 'Primary Menu',      'twentyfifteen' ),
		'social'  => __( 'Social Links Menu', 'twentyfifteen' ),
	) );

Diese Manipulationen am PHP-Quellcode sind überaus problematisch. Zum einen kann man Fehler machen, überblickt unter Umständen nicht die Gesamtzusammenhänge, zum anderen funktionieren vielleicht PlugIns anschließend nicht mehr. Dennoch baut die Vielfalt des Systems WordPress auf genau solchen Modifikationen auf. Da zukünftige WordPress Updates die selbst vorgenommmenen Veränderungen wieder überschreiben, sollte man sich genau die Positionen merken, die es nach einem Update erneut zu überprüfen gilt. Das ganze wird dann schnell zu einer Sisyphusarbeit. Die schlechteste Lösung wäre es aber aus Bequemlichkeit an nachfolgenden Patches und Weiterentwicklungen nicht mehr partizipieren zu wollen.
rh2015-12-003

Es gibt Begriffe, die scheinen aus dem Präteritum des deutschen Sprachschatzes zu kommen. Der Begriff »Stolz«, der zudem noch vielfältig und höchst unterschiedlich aufgeladen ist – von Hochmut bis Hochachtung ist alles dabei – gehört mit Sicherheit dazu. Im Footer des WordPress Themas Twentyfifteen ist es mal wieder so weit. Dort ist der Link zu WordPress mit dem Halbsatz »Stolz präsentiert von WordPress« belegt. Eine wohl eher gedankenlose direkte Übersetzung aus dem Englischen.
Daß diese Begrifflichkeit viele deutschsprachige WordPress-User stört, belegen die zahlreichen Anfragen auf Beseitigung im Netz. Das kann nun zweierlei bedeuten. Entweder das vollständige Entfernen des Links aus dem Footer oder die Abänderung des darauf hinterlegten Textes. Unabhängig von lizenzrechtlichen Imponderabilien würde sich das vollständige Löschen aus moralischen Gründen verbieten. Schließlich leistet WordPress hier hervorragende Arbeit, die auch entsprechend gewürdigt werden muß. Die zweite Variante sollte (ungeprüft) möglich sein, wenn man von der Aussage her nah am Original bleibt.
Ich betrachte diesen sprachlichen Ausrutscher ähnlich wie einen Rechtschreibfehler, den es zu korrigieren gilt und zwar direkt dort, wo er entsteht, in der zuständigen Sprachdatei. Eine fehlerträchtige Manipulation des PHP-Codes wäre damit nicht erforderlich.

Wer die nächsten Schritte nicht versteht oder unsicher ist, sollte sich andere Lösungswege suchen. Die Kenntnis um eine Datensicherung und die sichere Beherrschung einer Rücksicherung im Schadensfall, wird hier ohnehin unterstellt.

Der erste Schritt ist für die Maßnahme selbst nicht erforderlich, kann aber die Prozedur erhellen. Wenn man sich per ssh mit dem betreffenden Server verbindet und sich in das WordPress-Verzeichnis begibt, läßt sich prüfen in welchen Dateien der Begriff »Stolz« enthalten ist:

$ find . -type f -print0 | xargs -0 grep 'Stolz'
Binary file ./wp-content/languages/themes/twentythirteen-de_DE.mo matches
./wp-content/languages/themes/twentyfifteen-de_DE.po:msgstr "Stolz präsentiert von %s"
Binary file ./wp-content/languages/themes/twentyfourteen-de_DE.mo matches
./wp-content/languages/themes/twentyfourteen-de_DE.po:msgstr "Stolz präsentiert von %s"
Binary file ./wp-content/languages/themes/twentyfifteen-de_DE.mo matches
./wp-content/languages/themes/twentythirteen-de_DE.po:msgstr "Stolz präsentiert von %s"

Der gesuchte String befindet sich also in den Themen begleitenden Sprachdateien (.po-files = Portable Object) und den daraus übersetzten Binärdateien (.mo-files = Machine Object). Zudem haben wir jetzt die genaue Pfadangabe zu diesen Dateien. Die .po-Dateien sind reine Textdateien, die mit jedem beliebigen Text-Editor bearbeitet werden können. Die Übersetzung in eine binäre .mo-Datei erfolgt unter Linux beispielsweise im Terminal mit dem Programm msgfmt:

$ msgfmt -c -v -o twentyfifteen-de_DE.mo twentyfifteen-de_DE.po

Aber der Reihe nach. Für das hier betreffende Thema Twentyfifteen wird zunächst die Datei ./wp-content/languages/themes/twentyfifteen-de_DE.po per FileZilla oder ähnlichem auf den Client gezogen. Dann werden die beiden auf dem Server befindlichen .po- und .mo-Dateien durch Umbenennung gesichert (twentyfifteen.po.bak oder ähnlich). Auch das läßt sich per FileZilla durchführen.
Die lokale .po-Datei wird in einem Editor geöffnet. Ab der Zeile 179 ist folgendes zu lesen:

#: footer.php:25
msgid "Proudly powered by %s"
msgstr "Stolz präsentiert von %s"
...

Das macht die Entscheidung leicht. Einfach bei dem entschärften Original bleiben und den String »Stolz präsentiert von« durch »Powered by« ersetzen. Das sieht dann so aus:

#: footer.php:25
msgid "Proudly powered by %s"
msgstr "Powered by %s"
...

Jetzt muß die Übersetzung der .po-Datei in eine binäre .mo-Datei erfolgen. Das Programm PoEdit (hier unter Mac OS X) kann das, aber jede Linux Umgebung kann das auch (siehe oben [viel besser]).

Abschließend bleibt nur noch die beiden Sprachdateien wieder auf den Server in ihr angestammtes Verzeichnis ./wordpress/wp-content/languages/themes/ hochzuladen. Es ist klar, daß diese Anpassung das nächste Themen-Update nicht überleben wird. Das ist bei den PHP-Code Modifikationen aber auch nicht anders. Dennoch ist es meines Erachtens sauberer die Störung direkt an der Quelle zu beheben als nur ihr Auftreten zu verhindern.
rh2015-12-002

Daß sich das Dokumentationswerkzeug Sphinx nicht ausschließlich für den Einsatz innerhalb von Python oder C/C++ Projekten eignet, mag allgemein bekannt sein. Aufgrund seiner Leistungs- und Anpassungsfähigkeit ist es durchaus auch verwendbar für die Entwicklung und Nutzung von Dokumentationsthemen außerhalb des IT-Bereichs. Mit ein paar Anpassungen lassen sich intelligente und attraktive HTML-Seiten generieren, die sich anschließend über jeden Web-Server veröffentlichen lassen. Aber nicht nur die Darstellung im Netz ist so möglich. Im Zusammenspiel mit einer LaTeX-Maschine¹⁾ lassen sich – zum Beispiel für begleitende Handouts – zusätzlich hochwertige PDF-Dateien gleichen Inhalts erzeugen.
Die folgenden Beispiele entstanden auf einem iMac mit OS X Version 10.10.5, also Yosemite. Sphinx wurde in der Version 1.3.1 installiert.

Make HTML

Für ein neues Dokumentationsprojekt muß im Wesentlichen die Datei conf.py angepaßt und ggf. eine zum gewählten Sphinx-Thema passende, aber alternative CSS-Datei erstellt werden. Bei der Konfigurationsdatei conf.py handelt es sich übrigens um eine echte Python-Datei und folgt somit den normierten Regeln der Python Syntax. Allzu große Formulierungsfreiheiten hat man also nicht.
Welche Sphinx-Version ist gegenwärtig installiert?

$ python
Python 2.7.10 (default, Jul 14 2015, 19:46:27) 
[GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.39)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import sphinx
>>> print sphinx.__version__
1.3.1
>>> quit()

Oder auch so:

$ sphinx-quickstart --version
Sphinx v1.3.1

Um ein neues Projekt zu starten reichen im Quiet-Modus zunächst drei Daten: Autor, Projektname und Versionsnummer

$ sphinx-quickstart -q -a "Rüdiger Huß" -p "Projekt Lorem Ipsum" -v 1 -l de
Creating file ./conf.py.
Creating file ./index.rst.
Creating file ./Makefile.
Creating file ./make.bat.
...

In den weiteren Schritten wird die zentrale, gerade eben erzeugte Konfigurationsdatei conf.py angepaßt. Einen Überblick über die bereits gesetzten Parameter erhält man auf diesem Weg:

$ cat conf.py | grep "^[^#].*"
import sys
import os
import shlex
extensions = []
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = u'Projekt Lorem Ipsum'
copyright = u'2015, Rüdiger Huß'
author = u'Rüdiger Huß'
version = '1'
release = '1'
language = 'de'
exclude_patterns = ['_build']
pygments_style = 'sphinx'
todo_include_todos = False
html_theme = 'alabaster'
html_static_path = ['_static']
htmlhelp_basename = 'ProjektLoremIpsumdoc'
latex_elements = {
}
latex_documents = [
  (master_doc, 'ProjektLoremIpsum.tex', u'Projekt Lorem Ipsum Documentation',
   u'Rüdiger Huß', 'manual'),
]
man_pages = [
    (master_doc, 'projektloremipsum', u'Projekt Lorem Ipsum Documentation',
     [author], 1)
]
texinfo_documents = [
  (master_doc, 'ProjektLoremIpsum', u'Projekt Lorem Ipsum Documentation',
   author, 'ProjektLoremIpsum', 'One line description of project.',
   'Miscellaneous'),
]

Die anderen, zur Zeit noch auskommentierten Parameter ließen sich zum Beispiel so auflisten:

$ cat conf.py | grep "^#[a-z].*"
#sys.path.insert(0, os.path.abspath('.'))
#needs_sphinx = '1.0'
#source_encoding = 'utf-8-sig'
#today = ''
#today_fmt = '%B %d, %Y'
#default_role = None
#add_function_parentheses = True
#add_module_names = True
#show_authors = False
#modindex_common_prefix = []
...

Sollte man einmal den Überblick über die Projektdateien verloren haben, kann man nach Begriffen oder Textpassagen innerhalb der Dateien suchen:

$ find . -type f -print0 | xargs -0 grep -n "tocdepth"
Binary file ./_build/doctrees/environment.pickle matches
./_build/latex/ProjektLoremIpsum.tex:19:\setcounter{tocdepth}{2}
./_build/latex/sphinxmanual.cls:31:\setcounter{tocdepth}{1}
./conf.py:218:'preamble': '\setcounter{tocdepth}{2}',

Das Standard-Thema der Sphinx-Version 1.3 ist Alabaster, dennoch kann es innerhalb der Konfigurationsdatei explizit herangezogen werden:

import alabaster
extensions = ['alabaster']
html_theme = 'alabaster'

Möchte man auf den Link zur Quellcode-Anzeige in der Sidebar verzichten, muß diese Anpassung in der Datei conf.py vorgenommen werden:

html_show_sourcelink = False

Ein Logo links oben in der SideBar: Das Logo wird als png-Datei im Unterverzeichnis _static abgelegt und sollte nicht größer als 200 Pixel im Quadrat sein.

html_static_path = ['_static']
html_logo = '_static/rh-logo-blau-200.png'

CSS-Anpassungen

Um das Thema Alabaster auf die eigenen Vorstellungen anpassen zu können wird eine weitere CSS-Datei benötigt, die die Voreinstellungen des Themas während der Übersetzung überschreibt. Dazu muß im Projekt-Verzeichnis _templates

templates_path = ['_templates']

eine Datei layout.html mit folgendem Inhalt erzeugt werden:

$ cat ./_templates/layout.html
{# layout.html #}
{# Import the theme's layout. #}
{% extends "!layout.html" %}
{% set css_files = css_files + ['_static/style.css'] %}

Damit ist dem System die Existenz der alternativen CSS-Datei style.css in dem lokalen Projekt-Verzeichnis _static bekannt gemacht worden. In dem Beispiel wurde der Textabstand der H1-Überschriften nach unten vergrößert und die Farbe der Headlines H2 bis H6 individualisiert:

$ cat ./_static/style.css
/*

  Stilanpassungen

*/

/* -- body styles ------------------------------------------------------ */

div.body h1 {
    margin-top: 0;
    padding-top: 0;
    padding-bottom: 20px;
    font-size: 240%;
}
div.body h2 { font-size: 180%; color: #6D4100; }
div.body h3 { font-size: 150%; color: #6D4100; }
div.body h4 { font-size: 130%; color: #6D4100; }
div.body h5 { font-size: 100%; color: #6D4100; }
div.body h6 { font-size: 100%; color: #6D4100; }

Make LaTeX

Um nun aus der gleichen Quelle per LaTeX gestaltete PDF-Dokumente zu erhalten, kann die Konfigurations-Datei conf.py noch in den nachfolgenden Punkten Anpassungen erhalten.

latex_elements = {
'papersize': 'a4paper',
'pointsize': '11pt',
'preamble': '\setcounter{tocdepth}{2}',
'classoptions': ',openany,oneside', 
'babel' : '\\usepackage[ngerman]{babel}'
}
latex_documents = [
  (master_doc, 'ProjektLoremIpsum.tex', u'Lorem Ipsum Dokumentation',
   u'Rüdiger Huß', 'manual'),
]
latex_logo = '_static/rh-logo-blau-500.png'

LaTeX wird ein Dokument vom Typ »report« in der Größe A4 und 11 Punkt Schriftgröße erstellen. Das Inhaltsverzeichnis soll auf jeden Fall bis zur dritten Ebene (subsection) aufgegliedert werden. Es wird auf Leerseiten verzichtet und der Report wird nicht gebunden, er ist also einseitig. Außerdem wird noch ein Logo auf der ersten Seite oben eingefügt, das aber etwas größer sein sollte als jenes in der HTML-Version (Sidebar oben). Dieses Logo wird ebenfalls als png-Datei in dem Verzeichnis _static abgespeichert. Die Übersetzung der Dokumentation erfolgt so:

$ make clean
$ make html
$ make latex
$ cd ./_build/latex
$ make

Alternativ kann man statt make latex auch make latexpdf eingeben. Damit erspart man sich den Verzeichniswechsel und das anschließende make zum erzeugen der PDF-Datei. Um die Ergebnisse des Prozesses besser analysieren zu können, kann der Output in eine Datei zur anschließenden Text-Analyse abgezweigt werden.

$ make | tee tellme.txt
$ cat tellme.txt | grep -i 'warn'
$ cat tellme.txt | grep -i ' not '
...

Mittels Sphinx ist es vergleichsweise einfach sowohl ansprechende, komplexe Online-Dokumentationen als auch hochwertige Offline-Druckwerke zu erstellen. Wenngleich die Auszeichnungssprache von Sphinx relativ schnell erlernbar ist, so ist die diesbezügliche Lernkurve bei LaTeX (pdfLaTeX) doch erheblich steiler.
rh2015-12-001

¹⁾ LaTeX im Sinne des Artikels ist auch pdfLaTeX, XeLaTeX, usw.