ROSA -- Die Dokumentation Wie schreibe ich Dokumente mit dem "Redaktionssystem Ohne Sinnvollen Akronym" :documentation:: /n./ The multiple kilograms of macerated, pounded, steamed, bleached, and pressed trees that accompany most modern software or hardware products (see also tree-killer). Hackers seldom read paper documentation and (too) often resist writing it; they prefer theirs to be terse and on-line. A common comment on this predilection is "You can't grep dead trees". See drool-proof paper, verbiage, treeware. -- The Hackers' Jargon File 1. ROSA-Dokumente schreiben mit dem WWW-Interface Am einfachsten und bequemsten ist es sicherlich, wenn man das WWW-Interface benutzt, um ROSA-Dokumente zu erstellen. Die Felder, die für den Dokumentenkopf auszufüllen sind, sind dabei schon vorgegeben, d.h. einfach die Daten für den Titel, den Namen des Referenten, möglicherweise seine/ihre E-Mail-Adresse und Homepage (wenn diese Informationen zum Thema des Vortrags enthält) einfügen, sowie den eigenen Namen (unter Autorname) und die eigene E-Mail-Adresse. Bei Titel ist noch die ID des Artikels einzutragen. Diese ID setzt sich folgendermaßen zusammen: Der erste Teil der ID ist das Datum, an dem der Vortrag stattfindet (z.B. 27121998 für den 27. Dezember 1998), danach kommt ein festgelegter Code für die Veranstaltung. Andy legt für jede Veranstaltung einen eindeutigen Code fest (die Chaos-ID oder "Andy-Nummer"). Ob wir die benutzen, müssen wir mal sehen, auf jeden Fall wird aus der Titel-ID auch der eindeutige Dateiname generiert. Bei den Formularfeldern sind einige zwingend einzutragen, andere sind optional. Es betrifft folgende Felder: - Titel und ID sind Pfilcht (Veranstaltungen ohne Titel gibt es nicht) - Name des Referenten ist Pflicht. Wenn es mehere Referenten gibt (Podiumsdiskussion etc), sind die Namen durch Kommata zu trennen. Der Name sollte daher immer in der Form "Arthur Dent" udn nicht "Dent, Arthur" eingetragen werden. - E-Mail-Adresse des Referenten ist optional (nicht jeder hat eine E-Mail-Adresse) - Homepage des Referenten ist optional (nur wenn da weitere Infos zur Veranstaltung sind, sollte die URL eingetragen werden) - Name des Autors ist Pflicht - E-Mail-Adresse des Autors ist optional (aber wer von uns hat keine E-Mail? Und für Rückfragen ist dieses Feld SEHR sinnvoll) Was dann folgt, ist der Textteil, der eigentliche Artikel. Im Textteil solltet Ihr dann sogenannte Tags benutzen. Um z.B. ein Wort fett zu markieren schreibt Ihr das so: Hier ist normaler Text. Dieser Teil ist fettgedruckt. Dieser Teil ist wieder normal. Ihr habt auch die Möglichkeit etwas kursiv zu setzen (mit dem -Tag) oder z.B. einen Text in einer Programmiersprache in der "computerigen" Schreibmaschinenschrift zu setzen (mit ), z.B.: Um eine FTP-Session zu starten, gibt man das Kommando ftp ftp.ccc.de ein. Für längere Zitate gibt es den -Tag. Das sieht dann so aus: Im Emacs-Manual gibt James Gosling schließlich selbst zu: This manual is organized in a rather haphazard manner. The first several sections were written hastily in an attempt to provide a general introduction to the commands in Emacs and to try to show the method in the madness that is the Emacs command structure. So ein Artikel besteht aus mehreren Absätzen. Ein Absatz wird normalerweise von eingeleitet und von beendet. Da das bei einem Wort wie "Absatz" dann doch lästig werden kann, gibt es bei ROSA mehrere Vereinfachungen bei der Mark-Up-Eingabe. Der -Tag kann weggelassen (in SGML-Sprech "minimiert") werden, wenn die Absätze durch eine Leerzeile getrennt sind. Das sind dann so aus: Statt Erster Absatz. Zweiter Absatz kann ich auch schreiben: Erster Absatz. Zweiter Absatz. was doch um einiges angenehmer ist. Übrigens gibt es eine ähnliche Minimierung auch für andere Tags: schließt z.B. immer den zuletzt geöffneten Tag. Beispiel: Dies ist fett. Schließlich gibt es noch zwei besondere Tags: und . Beide müssen ein sogenanntes Attribut haben, das SRC heißt. Mit kann ich eine Grafik in den Artikel einfügen, das Attribut SRC enmthält den Dateinamen des Bildes. Alles, was vor kommt, ist die Bildunterschrift. Beispiel: Ein lustiges Bild. ist für URLs, also z.B. WWW-Adressen. Dieser Tag ist IMMER leer. Auch hier muß SRC gesetzt seins: Am Schluß noch ein Wort zu Umlauten. In HTML sollten diese codiert werden (ä als ä etc). In ROSA ist das nicht notwendig. Schreibt einfach Umlaute. 2. ROSA-Dokumente auf die harte Tour Normalerweise gibt es das praktische WWW-Interface, das einem einen Teil der Arbeit abnimmt. Sollte man allerdings aus irgendeinem Grund einmal ein ROSA-Dokument "zu Fuß" erstellen müssen, geht das auch. Los geht es mit der sogenannten SGML-Deklaration: Danach folgen die Start-Tags und , sowie der , der das Attribut ID verlangt: Der Artikel, der aus der Zukunft kam Als nächstes gibt es den -Block, der die Tags , und enthalten kann: R. Funden nobody@nowhere.universe http://www.funden.org/zukunft/ Dann folgt ziemlich logisch der -Block. Hier gilt entsprechend das gleiche, allerdings gibt es keinen -Tag oder ähnliches: Susanne Klickerklacker susanne@sesamstrasse.de Jetzt machen wir den zu. Es beginnt der -Teil. Die erlaubten Tags im Textteil sind oben zu genüge beschrieben. Schreibt jetzt einfach wie gewohnt den Artikel und schließt ihn mit der Sequenz Fertig! Unten findet Ihr ein "RealLife"-Beispiel (vom 96er Congress), das in ein gültiges ROSA-Dokument konvertiert wurde. Viel Spaß. Anhang 1: Die ROSA-DTD im Überblick ------------------------------------------------------------------------------ ROSA ------------------------------------------------------------------------------ ROSA |_((kopf), | |_((titel), | | |_(#PCDATA) | | | |__(referent)+, | | |_((refname), | | | |_(#PCDATA) | | | | | |__(refemail)?, | | | |_(#PCDATA) | | | | | |__(refwww)?) | | |_(#PCDATA) | | | | | |__(autor)) | |_((autname), | | |_(#PCDATA) | | | |__(autemail)?) | |_(#PCDATA) | | | |__(text)) |_((absatz)+) |_((#PCDATA | |___bild | | |_(#PCDATA) | |___zitat | | |_(#PCDATA) | |___url | | |_EMPTY | |___fett | | |_(#PCDATA) | |___kursiv | | |_(#PCDATA) | |___code)*) |_(#PCDATA) Anhang 2: Beispiel für ein gültiges ROSA-Dokument Behörden und Organisationen mit Sicherheitsaufgaben und ihre Funkfrequenzen Henning Heedfield henning@heedfield.de http://www.heedfield.de/ Jens Ohlig jo@devcon.net =Über die sogenannten BOS-Frequenzen wurde auf dem Chaos Communication Congress im Rahmen eines Workshops gesprochen. BOS, das sind Behörden und Organisationen mit Sicherheitsaufgaben, also z.B. das LKA, die Feuerwehr, das Rote Kreuz, der Verfassungsschutz oder die Polizeidienststelle um die Ecke. Seitdem Funkempfänger ohne festgelegten Frequenzbereich (sogenannte Scanner) auch in Deutschland betrieben werden dürfen, sofern sie zumindest einen für die Allgemeinheit gedachten Dienst (Fernsehen, Radio, CB-Funk, Amateurfunk und Wetterfunk) empfangen können, kann es schon mal passieren, das man versehentlich und ohne Vorsatz BOS-Sendungen mithört. Es versteht sich von selbst, daß man den Inhalt solcher Sendungen nicht anderen, vermutlich noch nicht einmal der Elite der Funkamateure zugehörigen, Menschen zugänglich macht. Zu Dokumentationszwecken gibt es für Interessierte zwei Bücher, die Frequenzlisten, Rufzeichen (etwa "OSNING" für die Polizei in Bielefeld) und allgemeine technische Richtlinien (die von den Innenministerien erstellten BOS-TR) enthalten. Hierin wird u.a. auch der derzeit einzig (von paging und reiner Daten/Text-Übertragung abgesehen) angewendete "digitale Dienst" "FMS" (FahrzeugMeldeSystem) erläutert. Dieser Dienst war auch der Aufhänger des Workshop. Bei FMS handelt es sich um im normalen Sprachband übermittelte, kurze Datentelegramme, die (repräsentiert durch Ziffern 0-9) lediglich den aktuellen Einsatz-Status des Fahrzeugs beschreiben. (Notruf, Einsatzbereit auf Streife; auf Wache, Auftrag übernommen, am Einsatzort eingetroffen etc.). Zusätzlich wird natürlich die Kennung des Fahrzeugs sowie bei Feuerwehr oder Rettungsdiensten die Art des KFz (RTW, MTW, Drehleiter, usw.) übertragen. Die Besatzungen der Fahrzeuge machen die (von sich aus über keine FMS-Kennung verfügenden) Funkgeräte durch ID-"Stecker" identifizierbar, so daß bei Fahrzeugwechsel nicht das Funkgerät ausgebaut, sondern lediglich der Stecker mitgenommen werden braucht. Am Handgerät befindet sich eine Zehnertastatur, über die der Status eingegeben wird. Die Übertragung wird von der Leitstelle automatisch quittiert; geht diese Quittung verloren, wiederholt das Fahrzeug-Funkgerät solange, bis einwandfreie Übermittlung erfolgt ist. Audiomäßig sind FMS-Telegramme an den charakteristischen "Quietschern" zu erkennen. In der Leitstelle sind so alle im Einsatz befindlichen Fahrzeuge samt Status auf einen Blick auf dem Bildschirm zu überschauen. Nach der detailierten Erklärung von FMS tauschten sich die Teilnehmer in plauschiger Workshopatmospäre über zukünftige oder experimentelle BOS-Dienste aus. Der Einsatz von GPS, dem Global Positioning System, bietet sich natürlich an und wird auch schon verschiedentlich in Feldversuchen erprobt. So laufen Experimente mit GPS in den Einsatzwagen, die Daten über GSM (also D-Netz-Technik) übertragen. Beim Einsatz von GSM muß man nicht auf die Verabschiedung von BOS-Richtlinien warten, es kann gleich erprobt werden, da die BOS-TR nur für BOS-Frequenzen gelten. Die Zukunft wird spannend. Es gibt sicherlich auf den BOS-Frequenzen für den ambitionierten Funkforscher eine Menge zu entdecken. Aber bitte nur mit Zulassung und ohne Vorsatz :)