Jak udokumentować specyfikację formatu pliku [zamknięte]

12

W przypadku projektu muszę pracować z różnymi typami plików z niektórych starych gier i pokrewnego oprogramowania - plikami konfiguracyjnymi, zapisami, archiwami zasobów i tak dalej. Większość z nich nie jest jeszcze udokumentowana, nie istnieją też narzędzia do ich obsługi, więc muszę ponownie zaprojektować formaty i zbudować własne biblioteki, aby sobie z nimi poradzić.

Chociaż nie sądzę, że istnieje duże zapotrzebowanie na większość z nich, zamierzam opublikować wyniki moich wysiłków. Czy są akceptowane standardy dokumentowania formatów plików? Rozglądając się, istnieje kilka stylów: niektóre, takie jak Specyfikacja formatu pliku .ZIP , są bardzo nieporadne; inne, jak te na XentaxWiki, są znacznie bardziej zwięzłe - niektóre z nich są trudne do odczytania; ten, który osobiście najbardziej mi się podoba, to ten opis systemu plików karty pamięci PlayStation 2 , który zawiera zarówno szczegółowy opisowy tekst, jak i kilka „map pamięci” z przesunięciami i tym podobne - również najbardziej pasuje do mojego przypadku użycia. Różnią się one nieco dla różnych formatów, ale wydaje się, że powinny istnieć pewne ogólne zasady, których powinienem przestrzegać.

Edycja: Wydaje mi się, że nie wyjaśniłem zbyt dobrze, co chcę zrobić. Pozwól mi zbudować przykład.

Mogę mieć jakieś stare oprogramowanie, które przechowuje swoją konfigurację w pliku „binarnym” - serię pól bitowych, liczb całkowitych, ciągów znaków i co nie wszystko sklejonych ze sobą i zrozumianych przez program, ale nie do odczytania przez człowieka. Rozszyfrowuję to. Chcę udokumentować dokładnie, jaki jest format tego pliku, w sposób czytelny dla człowieka, jako specyfikację implementacji biblioteki do analizowania i modyfikowania tego pliku. Ponadto chciałbym, aby inni ludzie z łatwością to zrozumieli.

Istnieje kilka sposobów napisania takiego dokumentu. Powyższy przykład PKZIP jest bardzo pracochłonny i opisuje głównie format pliku w postaci dowolnego tekstu. Przykład PS2 podaje tabele typów wartości, przesunięć i rozmiarów, wraz z obszernymi komentarzami na temat ich znaczenia. Wiele innych, takich jak te na XentaxWiki, wyświetla tylko typy i rozmiary zmiennych, z niewielkim komentarzem lub bez komentarza.

Pytam, czy istnieje jakiś standard, podobny do przewodnika stylu kodowania, który zawiera wskazówki, jak pisać tego rodzaju dokumentację. Jeśli nie, to czy istnieje jakikolwiek znany doskonały przykład, który powinienem naśladować? Jeśli nie, czy ktoś może przynajmniej streścić kilka przydatnych porad?

Sopoforic
źródło
Ha! Znam to uczucie. W jednym formacie, na który patrzyłem, faktycznie miałem oryginalny kod źródłowy, który napisał plik. Problem polegał na tym, że zmienne były zapisywane w innej kolejności niż w definicji struktury, a pomiędzy nimi było kilka dodatkowych rzeczy. Komentarze były błędne na temat przesunięć. Jest to część tego, co zainspirowało to pytanie - silne pragnienie, aby tego nie robić.
Sopoforic
1
Moje jedyne doświadczenie z udokumentowanymi typami plików inżynierii wstecznej pochodzi z wiibrew.org. Jeśli dobrze pamiętam, dokumentowali plik jako struct. Działa całkiem dobrze.
MetaFight,
1
Być może nie rozumiem pytania, ale wygląda na to, że szukasz czegoś takiego jak EBNF .
@MattFenwick: BNF służy do określania składni języka; nie do końca to, o co mi chodzi. Będę edytować, aby wyjaśnić, jaki rodzaj formatu pliku mam na myśli.
Sopoforic

Odpowiedzi:

4

Plik binarny jest tylko sekwencją bitów ułożonych w jednostki logiczne zgodnie z pewnymi regułami . Reguły te są zwykle nazywane gramatyką . Gramatyka można podzielić na cztery typy (The hierarchii Chomsky ), a dla bezkontekstowych gramatyk należy użyć Rozszerzona Notacja BNF jak podkreślił Matt Fenwick w swoim komentarzu. Interpretację (lub semantykę) sekwencji przechowywanej w pliku można opisać ustnie lub za pomocą dobrze opisanych programów przykładowych serializujących i deserializujących informacje.

Aby dowiedzieć się więcej na temat dokumentowania formatów plików binarnych, sugerujemy przeczytanie np . W standardzie ASN.1 .

Łowca jeleni
źródło
Technicznie większość plików konfiguracyjnych ma język bezkontekstowy, ponieważ mają one język skończony. Praktycznie, pisanie „zestawu wszystkich 2-bajtowych ciągów” (np. Dla pliku konfiguracyjnego, który jest tylko 16-elementowym polem bitowym) w EBNF niczego nie uczy. Wskaźnik do standardu ASN.1 jest najbliższą odpowiedzią, jaką otrzymałem, chociaż wydaje się, że specyfikacja w ASN.1 ma być czytana przez komputery i chciałem informacji do pisania dokumentacji dla ludzi. Jeśli jednak wkrótce nie pojawi się nic bardziej pasującego do moich wymagań, zaakceptuję tę odpowiedź. Dziękuję za Twoją pomoc.
Sopoforic
2

To dziwne, ponieważ szybkie wyszukiwanie formatów plików wywołało artykuł w Wikipedii (Lista formatów plików) . Zawiera także kilka formatów danych gier wideo.

Lista popularnych formatów plików danych gier wideo w systemach obsługujących systemy plików, najczęściej gier na komputery PC.

Zawiera także duży wybór formatów nośników pamięci gier wideo.

Lista najczęstszych rozszerzeń plików używanych podczas kopiowania obrazu ROM gry lub nośnika pamięci z oryginalnego urządzenia ROM do pamięci zewnętrznej, takiej jak dysk twardy, w celu wykonania kopii zapasowej lub w celu umożliwienia gry w emulator. W przypadku oprogramowania opartego na kartridżach, jeśli nie jest używane rozszerzenie specyficzne dla platformy, wówczas rozszerzenia plików „.rom” lub „.bin” są zwykle używane w celu wyjaśnienia, że ​​plik zawiera kopię zawartości pamięci ROM. Obrazy ROM, dyskowe lub taśmowe zwykle nie składają się z jednego pliku lub pamięci ROM, a raczej z całej struktury pliku lub pamięci ROM zawartej w jednym pliku na nośniku kopii zapasowej.


Czy są akceptowane standardy dokumentowania formatów plików?

Nigdzie nie ma „oficjalnego” standardu. Ponieważ formaty plików są tworzone przez firmę, firma decyduje o formacie dokumentacji.

Adam Zuckerman
źródło
2
Myślę, że źle zrozumiałeś moje pytanie. Oczywiście istnieje wiele udokumentowanych formatów plików - wspomniałem o XentaxWiki, które zawierają ponad 1500 nad nimi. Ale pliki, które mnie interesują, często nie są dokumentowane - zwykle są to rzeczy specyficzne dla gry, takie jak zapisywanie plików lub konfiguracja, a nie ogólne formaty kontenerów. Moja sytuacja jest taka, że ​​nie istnieje żadna dokumentacja i zamierzam ją napisać - więc jak to zrobić?
Sopoforic
W ten sam sposób udokumentowano wszystkie inne formaty plików.
Robert Harvey,
4
@RobertHarvey: Mylące, sprzeczne, niedokładne i niekompletne? Poważnie jednak, jak wspomniałem, zauważyłem kilka różnych ogólnych stylów w użyciu. Nie znam się na pracy w tej dziedzinie, aby wiedzieć, czy preferować jakiś konkretny styl. Te na XentaxWiki, jednym z największych zasobów, jakie widziałem, są prawie wyłącznie dla formatów kontenerów, więc nie do końca odwzorowują bardziej ogólny przypadek. Gdybym myślał, że wybranie przypadkowego przykładu do naśladowania byłoby wystarczające, nie prosiłbym o radę.
Sopoforic
@Sopoforic: W tym pytaniu musisz wyjaśnić, czego chcesz. Czy poważnie nas pytasz „Jak napisać dokumentację dotyczącą formatu pliku?” Istnieją całe programy edukacyjne na temat pisania technicznego poświęcone temu tematowi. Znajdź format, który ma przejrzystą, dobrze napisaną dokumentację (zgodnie z Twoimi osobistymi standardami) i naśladuj go. Nie wszyscy mogą być gównem. Wskazówka: przykłady użycia są królem. Wyjaśnienie wyjaśnień jest bliskie sekundy.
Robert Harvey,
1
@RobertHarvey: Tak, podobnie jak pytania na temat komentowania kodu lub dokumentowania funkcji, szukam „przewodnika po stylu” do napisania zrozumiałej specyfikacji formatu. Jeśli chcę wiedzieć, jak napisać RFC, mogę spojrzeć na RFC 2223. Jeśli chcę wiedzieć, jakiego stylu użyć w kodzie Python, mogę przeczytać PEP 8. Jeśli chcę wiedzieć, jak zadawać pytania w sposób inteligentny, ESR mnie obejmuje. Czy istnieją jakieś podobne wytyczne dotyczące specyfikacji formatu pliku? Lub dobrze znany doskonały przykład takiego? Z pewnością mogę użyć własnego osądu, ale jeśli istnieje standard, rozsądnie byłoby go zastosować.
Sopoforic