Forum: PC-Programmierung Datenformat dokumentieren


Announcement: there is an English version of this forum on EmbDev.net. Posts you create there will be displayed on Mikrocontroller.net and EmbDev.net.
von Oleksandr (Gast)


Lesenswert?

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?

von A. S. (achs)


Lesenswert?

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.

von Peter M. (barrelshifter)


Lesenswert?

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..

von Michael B. (laberkopp)


Lesenswert?

Oleksandr schrieb:
> Kennt ihr vielleicht ein paar öffentlich einsehbare Dokumentationen

https://github.com/pmachapman/helpdeco/blob/master/helpfile.txt

von Schleimfasten (Gast)


Lesenswert?

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.

von DerEinzigeBernd (Gast)


Lesenswert?

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.

von keinLichtAufGing (Gast)


Lesenswert?

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.

von DPA (Gast)


Lesenswert?

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.

von Wühlhase (Gast)


Lesenswert?

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.

von Hans im Glück (Gast)


Lesenswert?

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.

Antwort schreiben

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

Formatierung (mehr Informationen...)

  • [c]C-Code[/c]
  • [code]Code in anderen Sprachen, ASCII-Zeichnungen[/code]
  • [math]Formel in LaTeX-Syntax[/math]
  • [[Titel]] - Link zu Artikel
  • Verweis auf anderen Beitrag einfügen: Rechtsklick auf Beitragstitel,
    "Adresse kopieren", und in den Text einfügen




Bild automatisch verkleinern, falls nötig
Bitte das JPG-Format nur für Fotos und Scans verwenden!
Zeichnungen und Screenshots im PNG- oder
GIF-Format hochladen. Siehe Bildformate.

Mit dem Abschicken bestätigst du, die Nutzungsbedingungen anzuerkennen.