Dokumentation von stz2html

von Helmut Richter

Dokumentation eines Perl-Scripts zur Erstellung von HTML-Tabellen aus dem übersichtlicheren Stanza-Format

Einführung

Das Schreiben von HTML-Text für Tabellen von Hand kann sehr mühsam sein. Um das zu erleichtern, dient das Script stz2html, das nicht als Ersatz für bequemere Tools zum Schreiben von HTML gedacht ist, sondern als Ersatz für das Von-Hand-Schreiben. Einsatzbereiche sind z.B.:

die Herstellung von mehreren Tabellen (unterschiedlich sortiert oder mit unterschiedlicher Auswahl der darzustellenden Information) aus einer einzigen Quelle, wenn die Gesamtmenge der Information die Anlage einer Datenbank nicht rechtfertigt
die Übersetzung automatisch generierter Statistiken in HTML
die Herstellung kleiner Tabellen durch Benutzer, denen die Benutzung von Publikationswerkzeugen unsympathisch ist, solange sie mit der Zusammenstellung der Sachinformation und nicht mit deren Publikation beschäftigt sind.

stz2html steht für "Stanza to HTML". Ausgangsformat ist also das Stanza-Format, in welchem jedes Tabellenelement durch eine Zeile des Formats "Überschrift: Wert" dargestellt wird. Mit einer optionalen zusätzlichen Beschreibungsdatei läßt sich das Aussehen der generierten Tabelle weiter variieren. Siehe dazu das Beispiel.

Aufruf

Das Kommando befindet sich im Pfad /afs/lrz/home/a/a282244/pub/bin.

Für den Aufruf gibt es zwei mögliche Formate. Entweder

stz2html filename

oder

stz2html input-file descr-file output-file

wobei die erste Form eine Abkürzung ist für

stz2html filename.stz filename.stzdfilename.html

Das erste Format wird verwendet, wenn genau ein Parameter angegeben ist und die Datei filename.stz existiert.

Inhalt der Eingabedatei xxx.stz

Jede Tabellenzeile bildet eine "Stanza" (Strophe), die von den benachbarten durch eine Leerzeile getrennt ist. Jedes Tabellenelement hat die Form "Überschrift: Wert", muß also mindestens einen Doppelpunkt enthalten - der erste davon wird verwendet. Wenn die Überschrift selbst einen Doppelpunkt enthält, muß dieser als "&colon;" geschrieben werde, damit er nicht erkannt wird.

Die Titelzeile(n) der Tabellenspalten erscheinen nirgends explizit; sie ergeben sich aus den jeweiligen Überschriften der Tabellenelemente. Eine Überschrift kann auch der leere String sein; das ist aber nur für die erste (evtl. auch für die letzte) Spalte der Tabelle sinnvoll.

Enthält die Überschrift die Zeichenfolge ">>", so wird dadurch eine doppelte Überschrift markiert; haben mehrere aufeinanderfolgende solche doppelten Überschriften denselben ersten Teil, so wird dieser in der Ausgabe nur einmal über beide gesetzt (siehe Beispiel in der Einführung). Das läßt sich nach Belieben auch tiefer schachteln.

Kommt innerhalb einer Stanza eine Überschrift mehr als einmal vor, so werden die Werte mit "<BR>"miteinander verbunden; es entsteht also ein einziges mehrzeiliges Tabellenelement.

Inhalt der Beschreibungsdatei xxx.stzd

Fehlt die Beschreibungsdatei oder fehlt in ihr eine Angabe, so tritt jeweils das unten unter Voreinstellung gesagte in Kraft.

In der Beschreibungsdatei wird jede Zeile ignoriert, die entweder nur unsichtbare Zeichen ("white space") enthält oder deren erstes sichtbares Zeichen "#" ist.

Die Beschreibungsdatei beginnt mit null oder mehr Zeilen, die das sog. "Präludium" enthalten: Text, der vor der Tabelle stehen soll oder deren Anfang bildet. Beginnt die erste Zeile nicht mit "<", so wird angenommen, daß dieser Teil fehlt. Andernfalls gehören zum Präludium:

alle Zeilen bis zu einer, in der sich der Text "<TABLE" (Groß- und Kleinschreibung irrelevant) befindet, sowie
alle daran anschließenden Zeilen, solange sie alle mit "<" beginnen.

Das Präludium wird in die Ausgabe übernommen; am Ende der Tabelle werden TABLE-, BODY- und HTML-Tags geschlossen, soweit sie im Präludium eröffnet wurden.

Voreinstellung: Gibt es keine Beschreibungdatei oder gibt es in ihr kein Präludium, so wird so verfahren, als hätte das Präludium

<HTML><BODY> <TABLE ALIGN=CENTER BORDER=1 CELLPADDING=4>

gelautet. Diese Voreinstellung ist zum Testen nützlich, da die Ausgabe komplett genug für jeden Browser sein dürfte; für eine Publikation im WWW fehlen jedoch die wichtigen Angaben im Kopf der Seite.

Danach kommen pro Ausgabespalte eine Zeile des Formats

Überschrift : Attribute

wobei Überschrift die in der Ausgabe zu verwendende Spaltenüberschrift ist, die nicht unbedingt mit der Überschrift in der Eingabedatei übereinstimmen muß. Die Menge der Attribute kann auch leer sein; in diesem Fall darf der Doppelpunkt auch weggelassen werden. Die Attribute sind untereinander durch Zwischenräume getrennt; die Attribute, die durch geschweifte (alte Überschrift, s.u.) oder eckige (Optionen für das TH- bzw. TD-Tag, s.u.) gekennzeichnet sind, dürfen selbst Zwischenräume enthalten.

Voreinstellung: Gibt es überhaupt eine Beschreibungsdatei, so müssen die gewünschten Ausgabespalten in ihr aufgelistet sein. Gibt es keine, so erscheinen alle Ausgabespalten, und zwar in der Reihenfolge, in der sie in der Eingabedatei erstmals vorkommen.

Mögliche Attribute sind:

{Überschrift in der Eingabedatei}

Damit kann eine von der Eingabedatei abweichende Überschrift gewählt werden, etwa in einer anderen Sprache oder ohne eine Unterteilung, z.B. "Größe: {Größe>>neu}", wenn die Spalte "Größe>>alt" weggelassen wird.

Voreinstellung: dieselbe Überschrift in der Ein- und Ausgabe

Typ

Eine der Angaben "num" (für Zahlen), "int" (für ganze Zahlen), "name" (für Namen und ähnliche Bezeichnungen) oder "text" (für beliebige Texte. Diese Angabe hat Einfluß auf die Sortierreihenfolge und auf die Voreinstellung der horizontalen Textausrichtung (siehe unten).

Voreinstellung: "num" bzw. "int", falls alle Werte bis auf ein gemeinsames Suffix (die Benennung) Zahlen sind, "name", falls keiner der Werte Zwischenräume enthält, "text" sonst.

sort

Die Zeilen sollen nach den Werten in dieser Spalte sortiert werden. Soll absteigend sortiert werden, so ist "sortd" anstelle von "sort" anzugeben. Die Sortierung ist je nach Typ verschieden:

Typ "num": nach numerischem Wert; dabei wird auch ein Skalenfaktor bei der Benennung (also ein einleitender Buchstabe E, P, T, G, M, K, k, h, d, c, m, µ, n, p, f oder a) mit berücksichtigt. Wenn die Benennung "B" heißt, werden die Skalenfaktoren E, P, T, G, M und K nicht als Potenzen von 1000, sondern von 1024 aufgefaßt.
Typ "int": nach numerischem Wert, nachdem alle Zeichen entfernt wurden, die sich störend bemerkbar machen könnten, einschließlich aller Punkte und Kommas, von denen man ja nicht wissen kann, ob sie zur Abtrennung der Tausender oder als Dezimalpunkt bzw. -komma gemeint sind. Dezimalzahlen werden also nur dann korrekt berücksichtigt, wenn sie alle die gleiche Anzahl von Stellen hinter dem Komma aufweisen. Wegen dieser skurrilen Regeln ist, wenn immer es geht, der Typ "num" vorzuziehen.
Typ "name": Eine vernünftige Sortierreihenfolge, bei der Umlaute wie die Basisvokale einsortiert werden und die Groß- und Kleinschreibung nicht beachtet wird. Gruppen von Ziffern werden primär nach ihrer Länge und erst dann nach ihrem Wert sortiert, z.B. "abc8, abc9, abc10, abc11" im Gegensatz zu alphabetischer Sortierung. Dieser Typ eignet sich daher auch für Dezimalklassifizierungen wie "1.1, 1.2, 2.1, 2.2, ..., 2.10, 2.11" oder für numerische Internet-Adressen.
Typ "text": Es wird nach der Zeichencodierung alphabetisch sortiert, was selten sinnvoll ist.

Werden mehrere Spalten zur Sortierung vorgemerkt, so kann man durch Anfügen einer Ziffer (also "sort1", "sort2", . . .) deren Priorität festlegen.

Voreinstellung: keine Sortierung; Reihenfolge der Zeilen wie in der Eingabedatei

coal

(steht für "coalesce", darf auch ausgeschrieben werden): Tabellenelemente in mehreren aufeinanderfolgenden Zeilen, die in dieser Spalte den gleichen Wert haben, werden zu einem mehrzeiligen Tabellenelement zusammengefaßt. Es gibt jedoch nur eine solche Zusammenfassung: Ändert sich von einer der Zeile zur nächsten nur ein Teil der Werte in den mit "coal"markierten Spalten, so wird trotzdem der Aufbau der mehrzeiligen Tabellenelemente in allen diesen Spalten beendet. Diese Angabe ist eigentlich nur in Verbindung mit einer "sort"-Angabe hoher Priorität sinnvoll, da "coal" die gleichen Werte nicht von sich aus zusammensortiert.

Voreinstellung: keine Zusammenfassung von Tabellenelementen

[Optionen für das TD- bzw. TH-Tag]

Damit können Angaben wie "ALIGN=LEFT" für das TD- bzw. TH-Tag gemacht werden; auch die Angabe "TH" (für die Spalte mit Zeilenüberschriften) oder "TD" (für andere Spalten) ist hier möglich.

Voreinstellung: "TH", falls die Überschrift der leere String ist, sonst "TD". "ALIGN=RIGHT" für Zahlen, "ALIGN=CENTER" für Namen und "ALIGN=LEFT" für Texte.

Schwachstellen ("Bugs")

Seit der konsequenten Einführung von Benennungen, die zu der etwas schrägen Differenzierung zwischen num und int geführt hat, ist dieser Bereich noch nie gründlich getestet worden. Bis auf weiteres ist mit dem Auftreten von Inkonsistenzen zu rechnen, die ich zu berichten bitte.
Die Präfixe für die Benennungen, wie sie tatsächlich ausgewertet werden, entsprechen noch nicht der Tabelle, die gleichzeitig das Beispiel darstellt. Vielmehr werden, wie im laufenden Text erklärt, Bytes anders behandelt als andere Einheiten, also 1 MB = 1 MiB, wobei letzteres eben gerade noch nicht als 2²⁰ verstanden wird.

Alle auftretenden Fehler und Ungereimtheiten bitte ich mir zu melden.

Beispiel

Ohne Beschreibungsdatei wird aus der folgenden Eingabedatei mit Stanzas:

: exbi-
Präfix: Ei
Faktor>>Potenz: 2<SUP>60</SUP>
Faktor>>numerischer Wert: 1152921504606846976

: exa-
Präfix: E
Faktor>>Potenz: 10<SUP>18</SUP>
Faktor>>numerischer Wert: 1000000000000000000

: pebi-
Präfix: Pi
Faktor>>Potenz: 2<SUP>50</SUP>
Faktor>>numerischer Wert: 1125899906842624

: peta-
Präfix: P
Faktor>>Potenz: 10<SUP>15</SUP>
Faktor>>numerischer Wert: 1000000000000000

: tebi-
Präfix: Ti
Faktor>>Potenz: 2<SUP>40</SUP>
Faktor>>numerischer Wert: 1099511627776

: tera-
Präfix: T
Faktor>>Potenz: 10<SUP>12</SUP>
Faktor>>numerischer Wert: 1000000000000

: gibi-
Präfix: Gi
Faktor>>Potenz: 2<SUP>30</SUP>
Faktor>>numerischer Wert: 1073741824

: giga-
Präfix: G
Faktor>>Potenz: 10<SUP>9</SUP>
Faktor>>numerischer Wert: 1000000000

: mebi-
Präfix: Mi
Faktor>>Potenz: 2<SUP>20</SUP>
Faktor>>numerischer Wert: 1048576

: mega-
Präfix: M
Faktor>>Potenz: 10<SUP>6</SUP>
Faktor>>numerischer Wert: 1000000

: kibi-
Präfix: Ki
Faktor>>Potenz: 2<SUP>10</SUP>
Faktor>>numerischer Wert: 1024

: kilo-
Präfix: k
Faktor>>Potenz: 10<SUP>3</SUP>
Faktor>>numerischer Wert: 1000

: hekto- (hecto-)
Präfix: h
Faktor>>Potenz: 10<SUP>2</SUP>
Faktor>>numerischer Wert: 100

: dezi- (deci-)
Präfix: d
Faktor>>Potenz: 10<SUP>-1</SUP>
Faktor>>numerischer Wert: 0.1

: zenti- (centi-)
Präfix: c
Faktor>>Potenz: 10<SUP>-2</SUP>
Faktor>>numerischer Wert: 0.01

: milli-
Präfix: m
Faktor>>Potenz: 10<SUP>-3</SUP>
Faktor>>numerischer Wert: 0.001

: mikro- (micro-)
Präfix: µ
Faktor>>Potenz: 10<SUP>-6</SUP>
Faktor>>numerischer Wert: 0.000001

: nano-
Präfix: n
Faktor>>Potenz: 10<SUP>-9</SUP>
Faktor>>numerischer Wert: 0.000000001

: pico-
Präfix: p
Faktor>>Potenz: 10<SUP>-12</SUP>
Faktor>>numerischer Wert: 0.000000000001

: femto-
Präfix: f
Faktor>>Potenz: 10<SUP>-15</SUP>
Faktor>>numerischer Wert: 0.000000000000001

: atto-
Präfix: a
Faktor>>Potenz: 10<SUP>-18</SUP>
Faktor>>numerischer Wert: 0.000000000000000001

die folgende Tabelle generiert:

	Präfix	Faktor
	Präfix	Potenz	numerischer Wert
exbi-	Ei	2⁶⁰	1152921504606846976
exa-	E	10¹⁸	1000000000000000000
pebi-	Pi	2⁵⁰	1125899906842624
peta-	P	10¹⁵	1000000000000000
tebi-	Ti	2⁴⁰	1099511627776
tera-	T	10¹²	1000000000000
gibi-	Gi	2³⁰	1073741824
giga-	G	10⁹	1000000000
mebi-	Mi	2²⁰	1048576
mega-	M	10⁶	1000000
kibi-	Ki	2¹⁰	1024
kilo-	k	10³	1000
hekto- (hecto-)	h	10²	100
dezi- (deci-)	d	10^-1	0.1
zenti- (centi-)	c	10^-2	0.01
milli-	m	10^-3	0.001
mikro- (micro-)	µ	10^-6	0.000001
nano-	n	10^-9	0.000000001
pico-	p	10^-12	0.000000000001
femto-	f	10^-15	0.000000000000001
atto-	a	10^-18	0.000000000000000001

Dazu ein Ausschnitt des erzeugten HTML-Textes:

<TABLE ALIGN=CENTER BORDER=1 CELLPADDING=4>
<TR>
<TH ALIGN=CENTER></TH>
<TH ALIGN=CENTER ROWSPAN=2>Präfix</TH>
<TH ALIGN=CENTER COLSPAN=2>Faktor</TH>
</TR>
<TH ALIGN=CENTER></TH>
<TH ALIGN=CENTER ROWSPAN=1>Potenz</TH>
<TH ALIGN=CENTER ROWSPAN=1>numerischer Wert</TH>
</TR>
<TR>
<TH ALIGN=LEFT>exbi-</TH>
<TD ALIGN=CENTER>Ei</TD>
<TD ALIGN=CENTER>2<SUP>60</SUP></TD>
<TD ALIGN=RIGHT>1152921504606846976</TD>
</TR>
...
<TR>
<TH ALIGN=LEFT>atto-</TH>
<TD ALIGN=CENTER>a</TD>
<TD ALIGN=CENTER>10<SUP>-18</SUP></TD>
<TD ALIGN=RIGHT>0.000000000000000001</TD>
</TR>
</TABLE>

Wird hingegen eine Beschreibungsdatei folgenden Inhalts benutzt:

<TABLE>
<CAPTION>Tabelle sortiert nach Namen</CAPTION>
Name: {} sort [BGCOLOR="green"]
Wert: {Faktor>>numerischer Wert}

so bekommt die Tabelle folgendes Aussehen:

Tabelle sortiert nach Namen
		Name	Wert
		atto-	0.000000000000000001
		dezi- (deci-)	0.1
		exa-	1000000000000000000
		exbi-	1152921504606846976
		femto-	0.000000000000001
		gibi-	1073741824
		giga-	1000000000
		hekto- (hecto-)	100
		kibi-	1024
		kilo-	1000
		mebi-	1048576
		mega-	1000000
		mikro- (micro-)	0.000001
		milli-	0.001
		nano-	0.000000001
		pebi-	1125899906842624
		peta-	1000000000000000
		pico-	0.000000000001
		tebi-	1099511627776
		tera-	1000000000000
		zenti- (centi-)	0.01