So dokumentieren Sie eine Dateiformatspezifikation [geschlossen]

12

Für ein Projekt muss ich mit verschiedenen Dateitypen aus einigen alten Spielen und verwandter Software arbeiten - Konfigurationsdateien, Speicherungen, Ressourcenarchive usw. Der Großteil davon ist noch nicht dokumentiert, und es gibt auch keine Tools, mit denen ich arbeiten kann. Daher muss ich die Formate zurückentwickeln und meine eigenen Bibliotheken erstellen, um sie zu verarbeiten.

Obwohl ich nicht annehme, dass das meiste davon stark nachgefragt wird, beabsichtige ich, die Ergebnisse meiner Bemühungen zu veröffentlichen. Gibt es akzeptierte Standards für die Dokumentation von Dateiformaten? Wenn Sie sich umschauen , werden verschiedene Stile verwendet: Einige, wie die .ZIP-Dateiformatspezifikation , sind sehr wortreich; andere, wie die auf XentaxWiki, sind viel knapper - ich finde einige schwer zu lesen; Das, was mir persönlich am besten gefällt, ist diese Beschreibung des PlayStation 2-Speicherkartendateisystems , die sowohl detaillierten Beschreibungstext als auch mehrere 'Speicherkarten' mit Offsets und dergleichen enthält - sie passt auch am besten zu meinem Anwendungsfall. Es wird für verschiedene Formate ein wenig variieren, aber es scheint, dass es einige allgemeine Prinzipien geben sollte, denen ich folgen sollte.

Edit: Ich habe anscheinend nicht sehr gut erklärt, was ich tun möchte. Lassen Sie mich ein Beispiel konstruieren.

Möglicherweise habe ich eine alte Software, die ihre Konfiguration in einer 'binären' Datei speichert - eine Reihe von Bitfeldern, Ganzzahlen, Zeichenfolgen und so weiter, die vom Programm zusammengeklebt und verstanden werden, aber nicht für Menschen lesbar sind. Ich entschlüssele das. Ich möchte genau das Format dieser Datei auf lesbare Weise als Spezifikation für die Implementierung einer Bibliothek zum Parsen und Ändern dieser Datei dokumentieren. Außerdem möchte ich, dass dies für andere leicht verständlich ist.

Es gibt verschiedene Möglichkeiten, wie ein solches Dokument geschrieben werden kann. Das obige PKZIP-Beispiel ist sehr wortreich und beschreibt das Dateiformat hauptsächlich im Freitext. Das PS2-Beispiel enthält Tabellen mit Werttypen, Offsets und Größen mit ausführlichen Kommentaren zu deren Bedeutung. Viele andere, wie die in XentaxWiki, listen nur die Variablentypen und -größen mit wenig oder keinem Kommentar auf.

Ich frage, ob es einen Standard gibt, der einem Coding Style Guide ähnelt und Anleitungen zum Schreiben dieser Art von Dokumentation enthält. Wenn nicht, gibt es ein bekanntes hervorragendes Beispiel, das ich emulieren sollte? Wenn nicht, kann jemand zumindest einige nützliche Ratschläge zusammenfassen?

Sopoforic
quelle
Ha! Ich kenne dieses Gefühl. Bei einem Format, das ich mir angesehen habe, hatte ich tatsächlich den ursprünglichen Quellcode, der die Datei geschrieben hat. Das Problem war, dass die Variablen in einer anderen Reihenfolge als in der Strukturdefinition geschrieben wurden, mit einigen zusätzlichen Dingen dazwischen. Und die Kommentare zu den Offsets waren falsch. Es ist Teil dessen, was diese Frage inspiriert hat - ein starker Wunsch, DAS NICHT ZU TUN.
Sopoforic
1
Meine einzige Erfahrung mit dokumentierten Reverse Engineered-Dateitypen stammt von wiibrew.org. Wenn ich mich richtig erinnere, haben sie die Datei als dokumentiert struct. Es hat ganz gut funktioniert.
MetaFight
1
Ich verstehe die Frage vielleicht falsch, aber es scheint, als ob Sie nach etwas wie EBNF suchen .
@MattFenwick: BNF dient zum Festlegen der Syntax einer Sprache. nicht ganz das, wonach ich suche. Ich werde bearbeiten, um klarer zu machen, welche Art von Dateiformat ich meine.
Sopoforic

Antworten:

4

Eine Binärdatei ist nur eine Folge von Bits, die nach bestimmten Regeln in logischen Einheiten angeordnet sind . Diese Regeln werden normalerweise als Grammatik bezeichnet . Die Grammatik kann in vier Typen eingeteilt werden (die Chomsky-Hierarchie ). Für kontextfreie Grammatiken sollten Sie die erweiterte Backus-Naur-Form verwenden , auf die Matt Fenwick in seinem Kommentar hingewiesen hat. Die Interpretation (oder Semantik) der in der Datei gespeicherten Sequenz kann mündlich oder mit gut kommentierten Beispielprogrammen beschrieben werden, die die Informationen serialisieren und deserialisieren.

Um mehr über die Dokumentation von Binärdateiformaten zu erfahren, empfehlen wir Ihnen, sich über den ASN.1-Standard zu informieren .

Hirschjäger
quelle
Technisch gesehen haben die meisten Konfigurationsdateien eine kontextfreie Sprache, da sie eine endliche Sprache haben. Praktisch lehrt das Schreiben von 'der Menge aller 2-Byte-Zeichenfolgen' (z. B. für eine Konfigurationsdatei, die nur ein Bitfeld mit 16 Elementen ist) in EBNF niemandem etwas. Der Zeiger auf den ASN.1-Standard kommt einer Antwort, die ich erhalten habe, am nächsten, obwohl es den Anschein hat, dass eine Spezifikation in ASN.1 von Computern gelesen werden soll, und ich wollte Informationen zum Schreiben von Dokumentation für Menschen. Wenn jedoch in Kürze nichts besser zu meinen Anforderungen passt, werde ich diese Antwort akzeptieren. Danke für deine Hilfe.
Sopoforic
2

Das ist seltsam, weil eine schnelle Suche nach Dateiformaten einen Wikipedia-Artikel (Liste der Dateiformate) hervorbrachte . Es enthält auch verschiedene Videospieldatenformate .

Liste der gängigen Dateiformate von Daten für Videospiele auf Systemen, die Dateisysteme unterstützen, am häufigsten PC-Spiele.

Es enthält auch eine große Auswahl an Videospiel-Speichermedienformaten .

Liste der am häufigsten verwendeten Dateinamenerweiterungen, die verwendet werden, wenn das ROM-Image oder Speichermedium eines Spiels von einem Original-ROM-Gerät auf einen externen Speicher wie eine Festplatte kopiert wird, um das Spiel zu sichern oder um das Spiel mit einem Emulator spielbar zu machen. Wenn bei kartuschenbasierter Software die plattformspezifische Erweiterung nicht verwendet wird, werden normalerweise die Dateinamenerweiterungen ".rom" oder ".bin" verwendet, um zu verdeutlichen, dass die Datei eine Kopie eines Inhalts eines ROM enthält. ROM-, Festplatten- oder Bandabbilder bestehen normalerweise nicht aus einer einzelnen Datei oder einem ROM, sondern aus einer gesamten Datei- oder ROM-Struktur, die in einer einzelnen Datei auf dem Sicherungsmedium enthalten ist.


Gibt es akzeptierte Standards für die Dokumentation von Dateiformaten?

Es gibt nirgendwo einen "offiziellen" Standard. Da die Dateiformate von einem Unternehmen erstellt werden, entscheidet das Unternehmen über das Format für die Dokumentation.

Adam Zuckerman
quelle
2
Ich denke, Sie haben meine Frage falsch verstanden. Natürlich gibt es viele Dateiformate, die dokumentiert wurden - ich habe XentaxWiki erwähnt, das über 1500 darüber enthält. Aber die Dateien, an denen ich interessiert bin, sind oft nicht dokumentiert - spielspezifische Dinge wie das Speichern von Dateien oder die Konfiguration, normalerweise keine allgemeinen Containerformate. Meine Situation ist, dass keine Dokumentation existiert und ich beabsichtige, einige zu schreiben - wie soll das gemacht werden?
Sopoforic
Auf die gleiche Weise wurden alle anderen Dateiformate dokumentiert.
Robert Harvey
4
@ RobertHarvey: Verwirrend, widersprüchlich, ungenau und unvollständig? Im Ernst, wie ich bereits erwähnte, bemerkte ich verschiedene allgemeine Stile im Gebrauch. Ich bin mit der Arbeit in diesem Bereich nicht vertraut genug, um zu wissen, ob ein bestimmter Stil bevorzugt werden soll. Die auf XentaxWiki, der größten Ressource, die ich je gesehen habe, sind fast ausschließlich für Containerformate vorgesehen, sodass sie nicht ganz dem allgemeineren Fall zugeordnet werden können. Wenn ich der Meinung wäre, dass es gut genug wäre, nur ein zufälliges Beispiel zum Emulieren auszuwählen, würde ich nicht um Rat fragen.
Sopoforic
@Sopoforic: Dann müssen Sie in Ihrer Frage klarer sein, was Sie wollen. Fragen Sie uns ernsthaft: "Wie schreibe ich Dokumentation für ein Dateiformat?" Es gibt ganze Lehrpläne zum technischen Schreiben, die diesem Thema gewidmet sind. Suchen Sie ein Format mit einer klaren, gut geschriebenen Dokumentation (gemäß Ihren persönlichen Standards) und emulieren Sie dieses Format. Sie können nicht alle Mist sein. Hinweis: Anwendungsbeispiele sind König. Die Klarheit der Erklärung kommt an zweiter Stelle.
Robert Harvey
1
@RobertHarvey: Ja, ähnlich wie bei Fragen zum Kommentieren Ihres Codes oder zum Dokumentieren einer Funktion suche ich nach einem 'Style Guide' zum Schreiben einer verständlichen Formatspezifikation. Wenn ich wissen möchte, wie man einen RFC schreibt, kann ich mir RFC 2223 ansehen. Wenn ich wissen möchte, welchen Stil ich in Python-Code verwenden soll, kann ich PEP 8 lesen. Wenn ich wissen möchte, wie man Fragen auf intelligente Weise stellt, ESR hat mich abgedeckt. Gibt es ähnliche Anleitungen für Dateiformatspezifikationen? Oder ein bekanntes hervorragendes Beispiel dafür? Ich kann sicherlich mein eigenes Urteilsvermögen verwenden, aber wenn ein Standard existiert, wäre es sinnvoll, ihm zu folgen.
Sopoforic