Ich habe ein proprietäres Dateiformat analysiert und würde gerne meine
Erkenntnisse dokumentieren. Ich denke ich habe das Dateiformat
vollständig verstanden, zumindest lassen sich selbst generierte Daten
problemlos einlesen.
Ich habe jetzt mal gegoogelt, aber nicht wirklich was gefunden. Kennt
ihr vielleicht ein paar öffentlich einsehbare Dokumentationen an denen
ich mich orientieren könnte, so das auch andere Leute in der Lage wären
kompatible Daten zu erzeugen?
Nimm das, was Du kennst. ASCII, Word, LaTeX, man Pages, Wiki...
Die Info ist 1000x mehr wert als keine Info weil es nicht schön genug
aussieht.
Oder geht es darum, wie man was sinnvoll daratellt? Dann müsstest Du das
"was" näher beschreiben.
Ich würde die Datei zuerst als Struktur darstellen und danach die
einzelnen Elemente textuell beschreiben.
Bsp.:
fileformat {
bla bla,
bla xyz
}
bla: ist irgend etwas.
xyz: noch etwas..
Oleksandr schrieb:> Ich habe jetzt mal gegoogelt, aber nicht wirklich was gefunden. Kennt> ihr vielleicht ein paar öffentlich einsehbare Dokumentationen an denen> ich mich orientieren könnte, so das auch andere Leute in der Lage wären> kompatible Daten zu erzeugen?
Was EBNF-artiges + natürlichsprachliche Beschreibung der einzelnen
Punkte finde ich am lesbarsten, das wird auch meistens in
Datenblättern,... verwendet.
Dann aber nicht nur ne halbgare Besschreibung sondern einmal die
komplette Gramatik und dann jeweils die einzelnen Punkte nochmal einzeln
mit Beschreibung. Nix nervt mehr wenn das unvollständig ist.
Wenn du ganz fleissig sein willst, lieferst du eine Definition als
XML-Schema (DTD reicht oft nicht aus) oder ähnlichem mit, aus dem man
sich einen Parser generieren kann. kaitiai.io ist dafür auch ganz nett.
Kommt halt auf das Dateiformat an. Wenn das eine relativ straff
organisierte Binärstruktur ist, kann schon Pseudocode mit einer
C-Struktur-Beschreibung als Dokumentation hilfreich sein (natürlich mit
Hinweisen auf Byteorder).
Wenn es etwas wie ASN.1 ist, dann wird das ganze natürlich etwas
komplizierter.
Oleksandr schrieb:> Ich habe ein proprietäres Dateiformat analysiert und würde gerne meine> Erkenntnisse dokumentieren.> Kennt ihr vielleicht ein paar öffentlich einsehbare Dokumentationen an denen> ich mich orientieren könnte, so das auch andere Leute in der Lage wären> kompatible Daten zu erzeugen?
erst mal grundsätzlich: Für welche Leute soll die Doku denn sein? Wenn
es für nur für die Kollegen in der Firma sein soll, frage die einfach,
wie sie es gerne hätten.
Wenn Du das Format für alle Welt dokumentieren willst, dann frage doch
mal hier an:
https://www.documentliberation.org/
Die können Dir vermutlich Mustervorlagen zeigen oder Dich
weitervermitteln. Geht ja auch darum, wo die Doku hinterlegt wird. Und
noch viel wichtiger: bei manchen proprietären Dateiformaten sehen die
Hersteller es gar nicht gern, wenn "andere Leute in der Lage wären
kompatible Daten zu erzeugen". Falls es mit diesem Dateiformat schon
Ärger deswegen gab, wissen die liberation-Leute möglicherweise davon.
Ignoriere alles was Schleimfasten vorgeschlagen hat. EBNF, ABNF und co.
sind nur für textformate einigermassen brauchbar. XML Schemas und DTDs
sind auch nur nützlich um XML oder SGML zu beschreiben, aber nicht für
Daten die nicht bereits strukturiert sind.
Ich würde mal diverse RFCs anschauen. TCP, TLS, etc. Textformate wie
z.B. text, markdown, latex, rst, sind immer schön, html ist auch ok.
Versuche einfach genau und verständlich zu sein, und teile es Sinnvoll
auf damit man schnell findet, was man sucht. Keiner liest sich die
Dokumente von oben nach unten durch.
Ich würde es auch mit LaTex machen. Codelistings, auf die man genauso
wie Bilder oder Tabellen verweisen kann, UML und dergleichen sind kein
Problem. Es gibt Werkzeuge, die genau dafür gemacht sind.
Word ginge auch, aber Code damit vernünftig zu formatieren wird nervig.
Ansonsten ist das Wichtigste die PDF, die am Ende beim Dokuleser landet.
Womit du sie gemacht hast, ist zweitrangig.
Such mal nach dem Buch "Dateiformate-Referenz" von Günter Born. Das
müßte im Netz auch sehr schnell in einer PDF-Version zu finden sein. Da
sind verschiedene Dateiformate sehr gut beschrieben. Taugt auf jeden
Fall als Anregung, wie man Daten-Strukturen gut beschreibt.
Die Angabe einer E-Mail-Adresse ist freiwillig. Wenn Sie automatisch per E-Mail über Antworten auf Ihren Beitrag informiert werden möchten, melden Sie sich bitte an.
Wichtige Regeln - erst lesen, dann posten!
Groß- und Kleinschreibung verwenden
Längeren Sourcecode nicht im Text einfügen, sondern als Dateianhang
Announcement: there is an English version of this forum on 
Thread beobachten
Seitenaufteilung abschalten