Befehl: ambhelp
AMBHELP sind die FreeDOS-Hilfedateien im AMB-Format. Um Hilfedateien im
AMB-Format zu lesen, installieren Sie bitte auch den AMB-Reader.
Wie der AMB Container funktioniert:
1. Der AMB Container
2. Der Dokumententitel
3. Das AMA Format
4. Codepage Kodierung
5. Indexdaten
6. Begründung
Details:
1. DER AMB CONTAINER
Die AMB-Datei ist ein Container - man könnte sagen, sie ist ein sehr
einfaches Archivformat. Sie beginnt mit einer 4 Byte langen Format-
Signatur (magischer Wert) "AMB1". Dann folgt eine 2-Byte-Zahl, die
angibt, wie viele Dateien im Container vorhanden sind, gefolgt von der
Liste aller Dateien: jede Datei wird durch einen Dateieintrag be-
schrieben. Alle Werte sind Little-Endian.
Offset
0 Format-Signatur: "AMB1"
4 Anzahl der Dateien (16-Bit-Wert)
6 DATEIEINTRAG #1
DATEIEINTRAG #2
DATEIEINTRAG #3
....
DATEN
Jeder Dateieintrag ist eine 20-Byte-Struktur:
Offset
0 Dateiname, 12 Zeichen, mit Nullen aufgefüllt ("FILE.EXT\0\0\0\0")
12 Offset, an dem diese Datei beginnt (32 Bits)
16 Dateilänge, in Bytes (16 Bits)
18 BSD-Summe (16-Bit) der Datei
Es wird vorausgesetzt, dass das AMB-Archiv eine Reihe von AMA-Dateien
(Ancient Machine Article)-Dateien, sowie optional eine Titeldatei,
ein Index-Wörterbuch und eine Codepage Tabelle enthält.
Ein AMB-Archiv muss mindestens eine AMA-Datei namens "index.ama"
enthalten - das ist die erste Datei, die ein AMB-Reader zu laden
versucht.
Hinweis: Die in einem AMB-Archiv enthaltenen Namen von Dateien werden
nicht nach Groß- und Kleinschreibung verarbeitet und müssen
ausschließlich aus 7-Bit-Zeichen bestehen.
2. DER TITEL DES DOKUMENTS
Der AMB-Titel ist eine Zeichenfolge, die als Haupttitel des Dokuments
angezeigt wird. Um einen solchen Titel festzulegen, muss das AMB-Archiv
eine Datei mit dem einfachen Namen "Title" enthalten, die den Text
enthält. Die Zeichenfolge des Titels sollte nicht länger als 64 Zeichen
sein, da der Reader längere Zeichenfolgen möglicherweise abschneidet.
Der Titel des Dokuments und alle anderen Artikel sollten mit derselben
Codepage codiert sein. Vgl. auch Codepage-Kodierung.
3. DAS AMA FORMAT
DAS AMA Format ist ein textbasiertes Dateiformat. Um die Interopera-
bilität mit alten Maschinen zu gewährleisten, beträgt die maximal
zulässige Größe 65535 Bytes (d. h. 2^16 - 1). Größere Inhalte müssen
in zwei oder mehrere AMA-Dateien aufgeteilt werden.
Ein AMB-Reader kann Inhalte mit einer Breite von 78 Zeichen anzeigen,
daher darf eine AMA-Datei keine Zeile enthalten, die länger ist als
78 anzeigbare Zeichen. Zeilen, die länger als diese Grenze sind,
werden vom Client-Reader abgeschnitten.
AMA-Dateien können Steuercodes enthalten. Ein Steuercode ist ein
Zeichenpaar, wobei das erste ein Prozentzeichen (%) ist. Mögliche
Steuercodes sind:
%t Normaler Text folgt (Standardzustand)
%h Eine Überschrift folgt
%l Ein Link folgt (Dateiname endet mit einem ':', gefolgt
von einer Beschreibung)
%! Hinweis/Warnung folgt
%b Ein langweiliger Text folgt (üblicherweise grau in grau
angezeigt)
%% Zeigt ein Prozentzeichen an (%)
Bitte beachten Sie unbedingt, dass der aktuelle Textmodus am Ende jeder
Zeile auf %t zurückgesetzt wird, daher ist es nicht notwendig, einer
Textzeile ein %t voranzustellen.
Zeilenenden können entweder LF oder CR/LF sein. Da es kompakter ist,
wird Ersteres empfohlen.
TAB-Steuercodes (ASCII-Dezimalwert 9) sind in AMA-Dateien NICHT
zulässig.
Wenn in einer AMA-Datei eine externe URL steht (z. B. ein Link zu einer
Webseite, einer FTP-Ressource oder einem Gopher Hole), empfiehlt es
sich, diese zwischen <>-Zeichen einzuschließen. Beispiel:
<http://amb.osdn.io>.
Das ist nur eine auf RFC 3986 basierende Satzempfehlung, sie ist nicht
Teil der AMA-Spezifikation. Wenn man sie befolgt, ist es für moderne
AMB-Reader jedoch viel einfacher, solche Links automatisch zu erkennen
und anklickbar zu machen.
4. DIE CODEPAGE KODIERUNG
Da alte Computer aufgrund des Designs früherer Grafikkarten Texte als
8-Bit-Zeichen anzeigen, wird auch von AMA-Dateien erwartet, dass sie
ebenfalls 8-Bit-Text enthalten. Die genaue Codepage ist in dieser
Formatdefinition nicht festgelegt und hängt von der Zielgruppe des
Dokuments ab.
Um die Anzeige von AMB-Büchern auf modernen (Unicode-fähigen) Platt-
formen zu erleichtern, SOLLTE jede AMB-Datei, die andere Zeichen als
7-Bit enthält, auch eine Datei mit dem Namen "unicode.map" enthalten.
Diese Datei enthält eine Folge von 128 16-Bit-Werten, die Bytes im
Bereich 128..255 in Unicode-Datenpunktwerten abbilden. Eine solche
Datei kann problemlos mit dem https://utf8tocp.sourceforge.net
utf8tocp-Programm ausgegeben werden.
5. INDEX DATEN
Zusätzlich zu den AMA-Dateien kann das AMB-Archiv eine Datei mit dem
Namen DICT.IDX enthalten.
Diese Datei enthält, sofern vorhanden, Indexmetadaten, mit denen der
Client schnelle und effiziente Volltextsuchen im AMB-Buch durchführen
kann.
Die Indexdatei enthält eine Hash-Tabelle: eine Reihe von 256 16-Bit-
Indizes, wobei jeder Index auf einen Bereich der Indexstruktur ver-
weist, der eine Liste von Wörtern (LoW) enthält. Der Index (0..255)
selbst ist ein 8-Bit-Hash, der auf der Länge des Wortes und seiner
Zeichen basiert. Die Prüfsumme besteht aus zwei Nibbles: LC. Das
höchste Nibble (L) ist die Länge des Wortes minus 2, während das
niedrigste Nibble (C) eine einfache Prüfsumme aller Zeichen des
Wortes ist, die per XOR verknüpft sind. Dieser Algorithmus kann wie
folgt formalisiert werden:
((wordlen - 2) << 4) | ((a & 15) XOR (b & 15) XOR (...))
Zum Beispiel würde das Wort "Disk" letztendlich unter dem Wert 0x25
indexiert werden, weil:
((4 - 2) << 4) | ((D & 15) XOR (i & 15) XOR (s & 15) XOR
(k & 15))
übersetzt zu: (2 << 4) | (4 XOR 9 XOR 3 XOR 11)
was führt zu: 32 | 5
ergibt : 37 = 0x25
Nach dem Index können wir den Pointer zur Wortliste finden. Ein Zeiger
ist ein 16-Bit-Datei-Offset vom Beginn der Indextruktur.
Es ist zu beachten, dass Wörter mit weniger als 2 Zeichen und mehr als
17 Zeichen nicht indiziert werden können. Der vorgestellte Algorithmus
hat auch den interessanten Nebeneffekt, dass er niedrige und hohe
Obergrenzen der Bereiche a..z und A..Z identisch indiziert. Eine
wichtige Einschränkung ist die Tatsache, dass die Liste der Wörter
(LoW) durch den 16-Bit-Adressierungsoffset eingeschränkt ist, was
bedeutet, dass alle LoWs an einem Offset innerhalb der ersten 64 KiB
der Datei beginnen müssen.
Da wir nun den Offset kennen, mit dem unser LoW beginnt, können wir die
Wörter lesen. Gehen Sie zunächst zum Offset und lesen Sie ein einzelnes
16-Bit-Wort. Sein Wert enthält die Anzahl der Wörter in der Liste.
Lesen Sie dann die Wörter eines nach dem anderen (beachten Sie, dass
alle Wörter in der Liste die gleiche Länge haben, und Sie kennen diese
Länge bereits). Die Wörter werden immer in Kleinbuchstaben geschrieben.
Nach jedem Wort folgt ein 1-Byte-Wert, der angibt, in wie vielen
Dateien das Wort gefunden wurde. Dann folgen diese vielen 32-Bit-Datei-
kennungen.
Index Format:
* Liste der Wörter
xx Anzahl der Wörter in der Liste
? Wort
x In wievielen Dateien kommt das Wort vor
xxxx Dateibezeichner 1
xxxx Dateibezeichner 2
...
xxxx Dateibezeichner n
(es folgen 255 weitere Wortlisten)
* Hashtabelle
xx Offset des LoW für Wörter, die mit Hash 0x00 übereinstimmen
xx Offset des LoW für Wörter, die mit Hash 0x01 übereinstimmen
...
xx Offset des LoW für Wörter, die mit Hash 0xff übereinstimmen
6. BEGRÜNDUNG
Das AMB-Format ist konstruktionsbedingt mit mehreren Einschränkungen
behaftet. Diese Einschränkungen könnten als Mängel missverstanden
werden, während das Hauptziel des AMB-Formats darin besteht, so
primitiv wie möglich zu bleiben - damit es von Software einfach (und
schnell) analysiert und angezeigt werden kann. Im Folgenden sind
einige dieser Einschränkungen aufgelistet, mit Erklärungen zu den
Gründen, die zu ihnen geführt haben.
* Begrenzung der Zeilenlänge auf 78 Zeichen
Die fest codierte Begrenzung auf 78 Zeichen soll sicherstellen, dass
sich der Reader keine Gedanken über Zeilenumbrüche machen muss, was den
Code des Readers stark vereinfacht und somit eine schnellere Verar-
beitung ermöglicht und potenzielle Fehler minimiert.
Außerdem soll es dem Inhaltsersteller ermöglichen, seine Bildschirme
deterministisch zu gestalten – das heißt, ohne das Risiko, dass seine
semigrafischen Tabellen, ASCII-Zeichnungen oder die allgemeine Bild-
schirmanordnung durch einen Reader beschädigt werden, der versucht,
den Text in einer unvorhersehbaren Breite neu zu umbrechen.
Die Breite von 80 Spalten war seit Anfang der 80er Jahre allgegenwärtig
und scheint eine vernünftige Grunderwartung zu sein, und eine Begren-
zung auf 78 Zeichen ermöglicht es dem Leser, zwei Spalten für seine
eigenen Zwecke zu verwenden (vertikaler Cursor, Rahmen usw.).
* Keine Kontrolle über den auf den Text angewendeten Stil (Farben)
Das AMB-Format definiert eine Reihe semantischer Tags (wie "%h"
für "Überschrift"). Es erlaubt keine Kontrolle über die genauen Farben
oder Attribute, die vom Ausgabegerät zum Rendern des Dokuments verwen-
det werden. Dies ist absichtlich so vorgesehen: AMB-Dokumente sollten
auch auf monochromen Geräten angezeigt werden können. Es kann auch
Geräte geben, die Textattribute wie "unterstrichen", "fett" usw. zu-
lassen – es liegt am AMB-Reader, sicherzustellen, dass die semantischen
Tags in Farb-/Schattierungs-/Attributkombinationen übersetzt werden,
die auf der Zielhardware gut wiedergegeben werden.
* Dateigrößenbeschränkung von 64 KiB
Eine einzelne Datei (AMA-Datei) ist auf eine maximale Länge von 64 KiB
(minus ein Byte) beschränkt. Diese Beschränkung erleichtert MS-DOS-
Readern das Laden des Inhalts: In Real-Mode-Speichermodellen von Intel
ist ein einzelnes Speichersegment über 16-Bit-Offsets adressierbar,
daher wird die Verarbeitung von Inhalten, die größer als 64 KiB sind,
schwierig, da dabei Speichersegmentgrenzen überschritten werden müssen
oder einige Kludges wie "riesige" Speicherzeiger (langsam) oder Teile
der Datei dynamisch von der Festplatte nachgeladen werden müssen (sehr
langsam). 64 KiB ermöglichen immer noch mehr als 30 Seiten gepackten
Text im Format 80 x 25, was selbst für sehr komplexe Themen mehr als
ausreichend sein sollte (und größere Inhalte sollten einfach in zwei
oder mehr verschiedene Dateien aufgeteilt werden, was der Lesbarkeit
nur förderlich sein kann).
* Maximale Anzahl von 65535 Artikeln (Dateien)
Ein AMB-Buch kann bis zu 65535 Artikel enthalten und keinen einzigen
mehr, da die Anzahl der Artikel als 16-Bit-Ganzzahl im Header der Datei
geschrieben wird.
Dadurch kann die AMB-Software 16-Bit-Ganzzahlen verwenden, um die
Artikel anzusprechen, was für Plattformen mit 16-Bit-CPUs sehr prak-
tisch (und schnell) ist. Und mal ehrlich – ist das wirklich eine
Einschränkung? Selbst die gesamte Bibel hat "nur" 1189 Kapitel oder
31103 Verse.
* Nur kurze Dateinamen + Zeichen aus dem unteren ASCII-Bereich
Dateinamen in einem AMB-Container sind auf 12 (8+3) Zeichen begrenzt,
damit ein AMB-Container auf einem alten MS-DOS-System entpackt werden
kann.
Die Dateinamen dürfen nur Zeichen aus dem unteren ASCII-Bereich (7 Bit)
enthalten – und zwar aus zwei Gründen:
Damit es möglich ist, einen AMB-Container auf jedem Dateisystem zu ent-
packen, unabhängig von der Codepage, auf die sich das jeweilige Datei-
system stützt, und eine zuverlässige Groß-/Kleinschreibungsunabhängige
Übereinstimmung von Dateinamen zu erhalten.
Beispiel:
- keines -
Kommentar:
- keiner -
Siehe auch:
amb
ambpack
apropos
fasthelp/fdhelp/fsuite/fsuite04
help/htmlhelp
Wie man die Hilfe verwendet
Newbies01
Newbies02
utf8tocp
whatis
Copyright © 2020 Mateusz Viste, aktualisiert 2024 von W. Spiegl.
Diese Datei ist abgeleitet vom FreeDOS Spezifikationen-HOWTO.
Vgl. auch die Datei H2Cpying bezüglich der Kopierbedingungen.