Hinweise zur Generierung von HTML-Seiten im Complang-Stil ========================================================= Web-Seiten im Complang-Stil --------------------------- Eine Web-Seite im Complang-Stil besteht aus folgenden Elementen: - linkes Menue: zeigt aktuellen Ausschnitt aus der hierarchisch strukturierten Sitemap, aktuelle Seite (wenn im Menue vorhanden) in fetter Schrift - rechtes Menue: (kann je Format auch links stehen, wir nennen es trotzdem rechtes Menue), enthaelt Links zu Seite in alternativer Sprache und zu Sitemap, restliche Eintraege als Links oder Ueberschriften frei waehlbar - Statement (optional): frei waehlbarer Text rechts oben (Italics), soll klar machen, wohin die Seite gehoert, kann Links enthalten - Seitenueberschrift:

-Element - Seiteninhalt: sollte nicht leer, aber auch nicht uebermaessig lang sein - letzte Zeile: bestehend aus Referenz auf Seitenanfang (#top), Verweis auf HTML-Format, Datum der letzten Aenderung und Verantwortlicher fuer letzte Aenderung - Dekorelemente: Institutslogo, Fakultaetslogo, TU-Logo, jeweils als Link - -Element: meist nicht sichtbar, wird aber von manchen Browsern unter bestimmten Bedingungen angezeigt und soll Seite moeglichst kontextfrei beschreiben - Start-Seite: Gruppen, Projekte, Mitarbeiter, etc. haben je genau eine eindeutig bestimmte Startseite. Diese wird meist nicht angezeigt, aber manchmal zur Navigation verwendet. Jede Seite (ausser Startseite selbst) soll auf die entsprechende Startseite verweisen. - Sprache: Seiten sind entweder deutsch (de) oder englisch (en). Die Sprache ist im lang-Attribut angegeben. Gibt es einander entsprechende Seiten auf Deutsch und Englisch, so muessen die Seiten sowohl ueber einen Eintrag im rechten Menue als auch eine alternate-Relation (meist nicht direkt sichtbar) aufeinander verweisen. - Verweis auf Stile-Sheet: http://www.complang.tuwien.ac.at/complang.css Zu jeder Startseite soll es eine als "Sitemap" gekennzeichnete Seite geben, die direkte Links auf moeglichst alle Seiten und Resourcen, die der Startseite zuordenbar sind, geben. Diese Sitemap sollte in jener Sprache existieren, die die Seiten verwenden. Wenn deutsche und englische Seiten vorkommen, soll die Sitemap in beiden Sprachen existieren. Der Inhalt einer Sitemap soll aus folgenden Elementen bestehen: - kurzer Hinweis darauf, wer (Gruppe, Projekt, Person) die Web-Seiten betreut (nicht nur, welche Person sie zuletzt geaendert hat) - hierarchische Darstellung der Seiten, die im linken Menue der einzelnen Seiten aufscheinen - weitere Seiten und Dateien, die nicht im linken Menue aufscheinen - eventuell kurze Hinweise zum Umgang mit diesen Seiten Automatisierung und Struktur ---------------------------- Die vielen Elemente verlangen zur besseren Wartbarkeit und Konsistenthaltung eine teilweise Automatisierung bei der Seitenerstellung. Dazu sind Werkzeuge vorhanden, die aber eine bestimmte Organisation der benoetigten Daten voraussetzen. Die Werkzeuge gehen von folgenden Strukturen aus: - Pro Startseite sollte es zumindest ein eigenes Verzeichnis unter /usr/ftp/pub (bzw. /usr/ftp/pub selbst fuer die ganze Gruppe) geben, um Namenskonflikte zwischen verschiedenen Bereichen, die getrennt verwaltet werden, zu vermeiden. - Unter /usr/ftp/pub kann man nur die oeffentlichen Seiten finden, nicht die Daten, aus denen diese Seiten generiert werden. - Pro Startseite gibt es bei demjenigen, der die Startseite verwaltet, ein eigenes privates Verzeichnis mit im Wesentlichen derselben Struktur wie das Verzeichnis unter /usr/ftp/pub. Das private Verzeichnis enthaelt statt der (oder neben den) generierten HTML-Seiten aber die Daten, aus denen die HTML-Seiten generiert werden. - Im privaten Verzeichnis gibt es genau eine Datei (also genau eine pro Startseite) namens "sitemap" mit Informationen ueber Seiten, die im linken Menue aufscheinen. Aufbau dieser Datei siehe unten. Daneben kann es auch genau eine Datei namens "nomaps" geben, die Informationen enthaelt, welche in Sitemaps, aber nicht in linken Menues benoetigt wird. - Im privaten Verzeichnis und jedem dazu gehoerenden Unterverzeichnis gibt es ein "Makefile", das die HTML-Seiten erzeugt und installiert. Das Makefile ist speziell zu adaptieren (wohin sollen HTML-Seiten installiert werden, wer ist fuer Aenderungen verantwortlich, welche Unterverzeichnisse gehoeren dazu, etc.) - Fuer jede zu generierende HTML-Seite (ausser den Sitemaps) gibt es im privaten Verzeichnis eine Datei mit der Endung ".gen", aber dem selben basename wie die generierte Seite. Die gen-Dateien enthalten Informationen, die nicht in "sitemap" stehen. - Generierte Dateinamen enthalten in der Regel keine Endungen (xxx statt xxx.html). Dies entspricht einer Empfehlung des W3C und erlaubt z.B., eine HTML-Datei durch eine PDF-Datei oder ein Verzeichnis zu ersetzen, ohne dass Verweise darauf geaendert werden muessen. Dadurch ist es aber nicht moeglich, dass unterschiedliche Resourcen bis auf die Endungen gleiche Namen haben, z.B. kann es nicht gleichzeitig eine Datei xxx.html und ein Verzeichnis xxx geben. - Alle Seiten, die im linken Menue unter der Startseite aufscheinen, sollten im selben Verzeichnis wie "makefile" liegen. Eine Aufteilung auf mehrere Verzeichnisse fuehrt leicht zu Fehlern, wie die Erfahrung zeigt. Andererseits ist es guenstig, wenn Seiten, die nicht im linken Menue aufscheinen sollen, in einem Unterverzeichnis stehen. Inhalt von "sitemap" und "nomaps" --------------------------------- Die Datei "sitemap" bzw. "nomaps" enthaelt pro Zeile einen Eintrag aus einer Anzahl moeglicher Arten von Eintraegen. Jeder Eintrag beginnt mit dem Namen der Art des Eintrags (dessen erster Buchstabe immer % ist) und hat eine bestimmte Anzahl von durch Space oder Tab getrennten Argumenten. Folgende Arten von Eintraegen werden derzeit unterstuetzt: %altlng uri1 uri2 Dieser Eintrag mit genau zwei Argumenten besagt, dass uri1 und uri2 einander entsprechende Seiten in unterschiedlichen Sprachen sind. Die Argumente sind beliebig gegeneinander austauschbar. Jedes Argument kann ein einfacher Name (= Name der HTML-Datei oder eines Verzeichnisses) oder eine vollstaendige Web-Adresse (uri) sein. Wenn das Argument auch an einer anderen Stelle in der Datei vorkommt (ist meist der Fall), soll es genau so geschrieben sein wie an der anderen Stelle. In deutschsprachigen Seiten wird nur die uri mit Kennzeichnung de in %map (siehe unten) verwendet, in englischen Seiten nur die mit Kennzeichnung en. %map uri lang predecessor short_title long_title ... Dieser Eintrag mit mindestens 5 Argumenten beschreibt einen Eintrag im linken Menue. Dabei bezeichnet uri die Seite, auf die der Menue-Eintrag zeigen soll, lang (mit den moeglichen Werten de und en) die Sprache der Seite, predecessor (ist ein uri oder einer der speziellen Werte - und 0) die uebergeordnete Seite in der Hierarchie (bei - bzw. 0 gibt es keine uebergeordnete Seite), short_title die Bezeichnung des Eintrags im linken Menue, und long_title zusammen mit allen folgenden Argumenten die Seitenueberschrift bzw. das <TITLE>-Element. Ausser bei Eintraegen mit - als predecessor sollte uri die Form name1/name2/.../namenN oder bei Verzeichnissen name1/name2/.../namenN/ haben, da beim Generieren der Seiten auf die Existenz einer entsprechenden gen-Datei oder eines entsprechenden Verzeichnisses geprueft wird. Der Wert - fuer predecessor besagt, dass der Eintrag sich auf etwas ausserhalb der Hierarchie bezieht; z.B. ein Link auf die Institutsseite, wenn die Startseite eine persoenliche Seite ist. Der Wert 0 fuer predecessor kennzeichnet eine Startseite. Es soll nur eine solche Seite pro "sitemap" geben, oder zwei, die durch %altlng zueinander in Beziehung stehen. In short_title duerfen keine Leerzeichen oder Tabs vorkommen; statt dessen soll man   verwenden. Alle folgenden Argumente werden dagegen zusammen als long_title betrachtet, das heisst, Leerzeichen sind hier erlaubt. Der Inhalt von long_title wird sowohl fuer Seitenueberschriften als auch <TITLE>-Elemente verwendet. Ueblicherweise stimmen diese ueberein. Texte in eckigen Klammern (nur Klammern als eigenes Wort, vom Rest durch Leerzeichen getrennt, zaehlen) werden nur im <TITLE>-Element, nicht in Seitenueberschriften verwendet. Teile des Titels, die durch den Kontext klar sind, sollen in eckige Klammern geschrieben werden. Seitenueberschriften scheinen auch in der Sitemap auf und werden daher in "sitemap" benoetigt. Alle %map-Eintraege mussen in der Reihenfolge vorkommen, in der sie im linken Menue aufscheinen sollen. %altlang-Eintraege werden nur beruecksichtigt, wenn sie vor %map-Eintraegen fuer dieselben uri stehen. %nomap uri [lang [long_title ...]] beschreibt einen Eintrag in Sitemaps, der nicht im linken Menue aufscheinen soll. Nur das erste Argument uri ist notwendig. Falls ein Kommentar zum Eintrag gewuenscht wird (long_title und weitere Argumente), muss auch lang angegeben sein. Anders als bei %map kann lang die Werte en, de und - (fuer unbekannt) haben. Ein uri in einer anderen Sprache als die Sitemap wird nicht beruecksichtigt, wenn es dafuer einen entsprechenden %altlng- Eintrag gibt. Die %map-Eintraege werden zum Erzeugen aller Seiten benoetigt, %nomap-Eintraege nur zum Erzeugen von Sitemaps. Daher sollen %map-Eintraege mit den dazu gehoerenden %altlng-Eintraegen in "sitemap" stehen, %nomap-Eintraege mit den entsprechenden %altlng-Eintraegen in "nomaps". Es funktioniert aber auch, wenn alle Eintraege in "sitemap" stehen, wobei aber %map-Eintraege nie nach %nomap-Eintraegen kommen duerfen. %submenu name [text ...] Hat mindestens ein Argument. Definiert einen Menueteil mit Namen "name", der auf einzelnen Seiten im rechten Menue eingeblendet werden kann. Wenn es weitere Argumente gibt, werden diese im rechten Menue (falls eingeblendet) als Ueberschrift des Menueteils angezeigt (wie %rhead, siehe weiter unten). Mehrere %submenu-Eintraege mit demselben Namen koennen zur Erzeugung von mehreren Ueberschriften im Menueteil verwendet werden. %subsel uri name title ... Hat mindestens zwei Argumente und fuegt einen Link zum Menueteil hinzu, der durch ein davor stehendes %submenu definiert ist (wie %rsel - siehe weiter unten - aber fuer Menueteile). Das erste Argument kann eine beliebige uri sein. Das zweite Argument wird im Menue angezeigt und darf keine Leerzeichen enthalten (  statt Leerzeichen verwenden). Weitere Argumente bilden zusammen den Titel des Eintrags, der fuer das (optionale) title-Attribut verwendet wird. Ist kein Titel angegeben und entspricht uri einem Namen eines %map-Eintrags, dann wird der lange Titel im %map-Eintrag als title-Attribut verwendet. gen-Dateien ----------- gen-Dateien koennen aehnliche Eintraege enthalten wie "sitemap": %rsel uri name title ... Hat mindestens zwei Argumente und fuegt einen Link im rechten Menue ein. Das erste Argument kann eine beliebige uri sein. Das zweite Argument wird im Menue angezeigt und darf keine Leerzeichen enthalten (  statt Leerzeichen verwenden). Weitere Argumente bilden zusammen den Titel des Eintrags, der fuer das (optionale) title-Attribut verwendet wird. Ist kein Titel angegeben und entspricht uri einem Namen eines %map-Eintrags, dann wird der lange Titel im %map-Eintrag als title-Attribut verwendet. %rselins [text] Hat maximal ein Argument, das als Text (ohne Leerzeichen) links von allen folgenden %rsel-Eintraegen eingefuegt wird. Ohne Argument wird der Effekt vorangegangener %rselins-Befehle aufgehoben. %rhead text ... Hat mindestens ein Argument. Alle Argumente werden im rechten Menue als Ueberschrift (in der Regel bold) angezeigt. Alle %rsel- und %rhead-Eintraege werden in der Reihenfolge in das rechte Menue eingefuegt, in der sie in der gen-Datei stehen. %addmenu name Hat genau ein Argument. Fuegt einen (meist in "sitemap" definierten) Menueteil des Namens "name" in das rechte Menue ein. Der Name muss mit dem in %submenu definierten Namen uebereinstimmen. %addtitle text ... Hat mindestens ein Argument. Alle Argumente werden sowohl zur Seitenueber- schrift als auch zum <TITLE>-Element hinzugefuegt. Kann zur Unterscheidung von Seiten verwendet werden, fuer die es nur einen gemeinsamen Eintrag im linken Menue gibt (siehe Beispiel weiter unten). %statement text ... Hat mindestens ein Argument. Alle Argumente zusammen definieren das optionale Statement auf der Seite. Zur Vereinfachung kann ein Zeilenumbruch durch das Wort / (Schraegstrich mit Leerzeichen oder Tab davor und dahinter) eingegeben werden. Der Text kann aber zum Beispiel auch HTML-Code zur Darstellung eines Bildes sein. %change date [text ...] Hat mindestens ein Argument. Falls das erste Element ungleich "-" ist, wird es als Datum der letzten Aenderung der Webseite interpretiert und ueberschreibt das von aussen uebergebene aktuelle Datum, das als Default verwendet wird. Ein Datum soll das Format yyyy-mm-tt haben, das wird aber nicht ueberprueft. Der optional folgende Text ist entweder "-" (wird irnoriert) oder gibt den Namen der Person an, die fuer die letzte Aenderung verantwortlich ist. Ist keine Person angegeben, wird der in Makefile spezifizierte Wert (entweder auf Deutsch oder Englisch, je nach Sprache der Seite) verwendet. %content Hat kein Argument. Das ist der letzte derartige Eintrag jeder gen-Seite. Alle danach folgenden Zeilen werden als HTML-Code interpretiert, der den eigentlichen Seiteninhalt ausmacht. Der Seiteninhalt kann beliebiger HTML-4.01-Strict-Code sein. In der automatisch eingebundenen CSS-Datei http://www.complang.tuwien.ac.at/complang.css sind einige wenige Sachen vordefiniert, die hier verwendet werden koennen: <P class="rightquote"> ... </P> Absatz, der wie im Statement rechtsbuendig und Italics dargestellt wird. <TH colspan="..." class="atleft"> ... </TH> Table-Header, der (meist ueber mehrere Spalten) weiter links beginnt als normale Table-Header (siehe z.B. http://www.complang.tuwien.ac.at/leute). <DL class="buttons"><DT> ... <DT> ... ... </DL> Zur Darstellung eines Blocks von Links (eingerueckt, etwas kleinere Schrift). <A class="intext" href= ...> ... </A> Referenz, die auf jeden Fall unterstrichen wird, unabhaengig von Browser- Einstellungen. Sinnvoll fuer Referenzen, die mitten im Text vorkommen (da Hervorhebungen durch Farben je nach Bildschirm nicht ausreichen). Beispiele: ---------- Inhalt von "sitemap": --- %altlng index english %altlng http://www.complang.tuwien.ac.at/ http://www.complang.tuwien.ac.at/english %map http://www.complang.tuwien.ac.at/ de - Complang-Gruppe Die Complang-Gruppe %map http://www.complang.tuwien.ac.at/english en - Complang Group The Complang Group %map index de 0 Nachname Vorname Nachname [ - Homepage ] %map english en 0 Nachname Vorname Nachname [ - Home Page ] %map about en english About Me About Vorname Nachname %map contact en about Contact Contact [ to Vorname Nachname ] %map research en english Research Research [ of Vorname Nachname ] ___ Inhalt von "nomaps": --- %altlng wlp/ wlp/index.engl %nomap papers/ - my online papers %nomap something/ %nomap wlp/ de 11. Workshop Logische Programmierung %nomap wlp/index.engl en 11th Logic Programming Workshop --- Inhalt von "xxx.gen" (irgendeine gen-Datei, englisch): --- %rsel contact Contact %rhead Fast Access: %rsel yyy Something %rsel http://www.irgendwo.at/ SomethingElse %statement Vorname Nachname / TU Vienna %content Some text. <H4>A Small Title:</H4> Some other text. There are useful links: <DL class="buttons"> <DT><A href="yyy">something</A> <DT><A href="http://www.irgendwo.at/">something else</A> </DL> --- Im folgenden Beispiel gibt es fuer die Seiten in einem Unterverzeichnis keine Eintraege im linken Menue (z.B. Abstracts fuer viele Papers - es wuerde zu viele Menueeintraege geben). In "sitemap" steht: %map publications en research Publications Publications [ of ... ] wobei publications eine Seite ist, die auf die einzelnen Abstracts verweist. In "nomaps" steht: %nomap papers/ Im Makefile in papers steht unter anderem: --- prefix = ../ base = /usr/ftp/pub/$(subdir)papers/ me = publications activeme = 1 --- In jeder gen-Datei in papers/ steht: --- %rsel ../contact Contact %addtitle (Author04) %content ... --- Werkzeuge --------- Die wichtigsten Werkzeuge zum Generieren von Web-Seiten sind unter http://www.complang.tuwien.ac.at/franz/genhtml/ zu finden: genindex.awk (awk-Script zum Erzeugen von HTML-Sitemap-Dateien) genpage.awk (awk-Script zum Erzeugen von HTML-Dateien aus gen-Dateien) install (shell-Script zur Installation erzeugter Dateien) MakefileNoSitemap (Makefile fuer Unterverzeichnisse zum Kopieren und Anpassen) MakefileSitemap (Makefile fuer Verzeichn. mit "sitemap" - kopieren und anp.) README (diese Datei) Vorgehensweise beim Erstellen von Seiten: - private Verzeichnisse anlegen, ausserstes davon ist Haupt-Verzeichnis - /usr/ftp/pub/franz/genhtml/MakefileSitemap in privates Haupt-Verzeichnis kopieren, auf "Makefile" umbenennen und entsprechend den Kommentaren im Makefile anpassen - /usr/ftp/pub/franz/genhtml/MakefileNoSitemap in jedes private Verzeichnis (ausser Haupt-Verzeichnis) kopieren, auf "Makefile" umbenennen und entsprechend den Kommentaren im Makefile anpassen - "sitemap" und (wenn noetig) "nomaps" im Haupt-Verzeichnis erstellen - gen-Dateien in allen Verzeichnissen erstellen - im Hauptverzeichnis "make" aufrufen - generiert Seiten in den privaten Verzeichnissen. Warnings ernst nehmen: werden meist nur bei gravierenden Problemen ausgegeben. - Generierte Seiten kontrollieren. Nur wenn alles passt "make install" aufrufen, um Seiten in die oeffentlichen Verzeichnisse zu kopieren. - Weitere, nicht generierte Seiten (z.B. Bilder, pdf-Dateien, etc.) manuell in oeffentliche Verzeichnisse kopieren. Hinweis: /usr/ftp/pub/franz/genhtml/install kopiert eine Seite nur dann in das oeffentliche Verzeichnis, wenn sich die dort bestehende von der zu kopierenden Seite unterscheidet. Unterschiede im Datum der letzten Aenderung und desjenigen, der die letzte Aenderung gemacht hat (diese Daten werden in jede generierte Seite geschrieben) werden dabei ebenso ignoriert wie Unterschiede im White Space. Daher werden z.B. Seiten, die sich nur im Datum von bestehenden Seiten unterscheiden, nicht kopiert. Franz Puntigam