Cara mendokumentasikan spesifikasi format file [tertutup]

Untuk sebuah proyek, saya perlu bekerja dengan berbagai jenis file dari beberapa game lama dan perangkat lunak terkait - file konfigurasi, penyimpanan, arsip sumber daya, dan sebagainya. Sebagian besar dari ini belum didokumentasikan, juga tidak ada alat untuk bekerja dengannya, jadi saya harus merekayasa balik format dan membangun perpustakaan saya sendiri untuk menanganinya.

Meskipun saya tidak mengira ada permintaan besar untuk sebagian besar, saya bermaksud untuk mempublikasikan hasil dari upaya saya. Apakah ada standar yang diterima untuk mendokumentasikan format file? Melihat sekeliling, ada beberapa gaya yang digunakan: beberapa, seperti Spesifikasi Format File ZIP , sangat bertele-tele; yang lain, seperti yang ada di XentaxWiki, jauh lebih singkat - saya menemukan beberapa di antaranya sulit dibaca; yang paling saya sukai adalah deskripsi Sistem File Kartu Memori PlayStation 2 ini , yang mencakup teks deskriptif terperinci dan beberapa 'peta memori' dengan offset dan semacamnya - ini juga sangat cocok dengan kasus penggunaan saya. Ini akan sedikit berbeda untuk format yang berbeda, tetapi tampaknya harus ada beberapa prinsip umum yang harus saya coba ikuti.

Sunting: Saya sepertinya tidak menjelaskan dengan baik apa yang ingin saya lakukan. Biarkan saya membuat contoh.

Saya mungkin memiliki beberapa perangkat lunak lama yang menyimpan konfigurasinya dalam file 'biner' - serangkaian bitfield, integer, string, dan yang lainnya semuanya direkatkan dan dipahami oleh program, tetapi tidak dapat dibaca oleh manusia. Saya menguraikan ini. Saya ingin mendokumentasikan dengan tepat apa format file ini, dengan cara yang dapat dibaca manusia, sebagai spesifikasi untuk mengimplementasikan pustaka untuk mengurai dan memodifikasi file ini. Selain itu, saya ingin ini mudah dimengerti oleh orang lain.

Ada beberapa cara dokumen semacam itu dapat ditulis. Contoh PKZIP di atas sangat bertele-tele dan sebagian besar menggambarkan format file dalam teks bebas. Contoh PS2 memberikan tabel tipe nilai, offset, dan ukuran, dengan komentar luas tentang apa arti semua itu. Banyak yang lain, seperti yang ada di XentaxWiki, hanya mencantumkan jenis dan ukuran variabel, dengan sedikit atau tanpa komentar.

Saya bertanya apakah ada standar, seperti panduan gaya pengkodean, yang memberikan panduan tentang cara menulis dokumentasi semacam ini. Jika tidak, adakah contoh bagus dan terkenal yang harus saya tiru? Jika tidak, adakah yang bisa merangkum beberapa saran bermanfaat?

documentation reverse-engineering

— Sopoforik
sumber

i.stack.imgur.com/4illz.jpg -> stackoverflow.com/a/769443/839601

— agas

Ha! Aku tahu perasaan itu. Satu format yang saya lihat sebenarnya saya punya kode sumber asli yang menulis file. Masalahnya adalah bahwa variabel sedang ditulis dalam urutan yang berbeda dari definisi struct, dengan beberapa hal tambahan yang ditaburi di antaranya. Dan komentarnya salah tentang offset. Itu adalah bagian dari apa yang menginspirasi pertanyaan ini - keinginan kuat untuk TIDAK MELAKUKANNYA.

— Sopoforic

Satu-satunya pengalaman saya dengan tipe file rekayasa balik terdokumentasi adalah dari wiibrew.org. Jika saya ingat dengan benar, mereka mendokumentasikan file tersebut sebagai struct. Itu bekerja dengan cukup baik.

— MetaFight

Saya mungkin salah paham pertanyaannya tetapi sepertinya Anda mencari sesuatu seperti EBNF .

@MattFenwick: BNF adalah untuk menentukan sintaks suatu bahasa; tidak cukup apa yang saya kejar. Saya akan mengedit agar lebih jelas format file apa yang saya maksud.

— Sopoforic

Jawaban:

File biner hanyalah urutan bit yang disusun menjadi unit logis sesuai dengan aturan tertentu . Aturan-aturan ini biasanya disebut tata bahasa . Tata bahasa dapat diklasifikasikan ke dalam empat jenis ( hierarki Chomsky ), dan untuk tata bahasa bebas konteks Anda harus menggunakan Formulir Extended Backus-Naur sebagaimana ditunjukkan oleh Matt Fenwick dalam komentarnya. Interpretasi (atau semantik) dari urutan yang disimpan dalam file dapat dijelaskan secara verbal atau dengan program sampel yang dianotasi dengan baik serialisasi dan deserialisasi informasi.

Untuk mengetahui lebih banyak tentang mendokumentasikan format file biner, sarankan membaca misalnya standar ASN.1 .

— Pemburu rusa
sumber

Secara teknis , sebagian besar file konfigurasi memiliki bahasa bebas konteks, karena mereka memiliki bahasa yang terbatas. Secara praktis, menulis 'himpunan semua string 2-byte' (misalnya untuk file konfigurasi yang hanya 16-bitfield) di EBNF tidak mengajarkan apa pun kepada siapa pun. Penunjuk ke standar ASN.1 adalah hal yang paling dekat dengan jawaban yang saya dapatkan, meskipun sepertinya spesifikasi dalam ASN.1 dimaksudkan untuk dibaca oleh komputer, dan saya ingin informasi untuk menulis dokumentasi untuk manusia. Namun, jika tidak ada yang lebih cocok dengan persyaratan saya muncul, segera, saya akan menerima jawaban ini. Terima kasih atas bantuan anda

— Sopoforic

Itu aneh karena pencarian cepat format file memunculkan artikel Wikipedia (Daftar format file) . Ini juga mencakup beberapa format Data Video Game .

Daftar format file umum data untuk gim video pada sistem yang mendukung sistem file, umumnya gim PC.

Ini juga termasuk banyak pilihan format Media Penyimpanan Game Video .

Daftar ekstensi nama file yang paling umum digunakan ketika gambar ROM atau media penyimpanan gim disalin dari perangkat ROM asli ke memori eksternal seperti hard disk untuk keperluan pencadangan atau untuk membuat game dapat dimainkan dengan emulator. Dalam hal perangkat lunak berbasis-kartrid, jika ekstensi spesifik platform tidak digunakan, maka ekstensi nama file ".rom" atau ".bin" biasanya digunakan untuk memperjelas bahwa file tersebut berisi salinan konten ROM. ROM, disk atau gambar tape biasanya tidak terdiri dari satu file atau ROM, melainkan seluruh file atau struktur ROM yang terkandung dalam satu file pada media cadangan.

Apakah ada standar yang diterima untuk mendokumentasikan format file?

Tidak ada standar "resmi" di mana pun. Karena format file dibuat oleh perusahaan, perusahaan memutuskan format untuk dokumentasi.

— Adam Zuckerman
sumber

Saya pikir Anda telah salah mengerti pertanyaan saya. Tentu saja ada banyak format file yang telah didokumentasikan - Saya menyebutkan XentaxWiki, yang mencakup lebih dari 1500 format. Tetapi file yang saya minati sering tidak didokumentasikan - hal-hal khusus game seperti menyimpan file atau konfigurasi, daripada format wadah umum, biasanya. Situasi saya adalah tidak ada dokumentasi, dan saya bermaksud untuk menulis beberapa - jadi bagaimana ini akan dilakukan?

— Sopoforic

Cara yang sama semua format file lainnya didokumentasikan.

— Robert Harvey

@RobertHarvey: Membingungkan, bertentangan, tidak akurat, dan tidak lengkap? Namun, serius, seperti yang saya sebutkan, saya mencatat beberapa gaya umum yang berbeda digunakan. Saya tidak cukup terbiasa dengan pekerjaan di bidang ini untuk mengetahui apakah ada gaya tertentu yang disukai. Yang ada di XentaxWiki, satu-satunya sumber daya terbesar yang pernah saya lihat, hampir secara eksklusif untuk format wadah, jadi mereka tidak cukup memetakan ke kasus yang lebih umum. Jika saya berpikir bahwa hanya mengambil contoh acak untuk ditiru akan cukup baik, saya tidak akan meminta saran.

— Sopoforic

@Opoforic: Maka Anda harus lebih jelas dalam pertanyaan Anda apa yang Anda inginkan. Apakah Anda serius bertanya kepada kami, "Bagaimana cara saya menulis dokumentasi untuk format file?" Ada seluruh kurikulum pendidikan tentang penulisan teknis yang dikhususkan untuk subjek itu. Temukan format yang memiliki dokumentasi yang jelas dan ditulis dengan baik (sesuai dengan standar pribadi Anda), dan meniru itu. Mereka semua tidak bisa omong kosong. Petunjuk: Contoh penggunaan adalah raja. Kejelasan penjelasan hampir berakhir.

— Robert Harvey

@ RobertTarvey: Ya, seperti halnya pertanyaan tentang bagaimana mengomentari kode Anda atau bagaimana mendokumentasikan suatu fungsi, saya mencari 'panduan gaya' untuk menulis spesifikasi format yang dapat dipahami. Jika saya ingin tahu cara menulis RFC, saya dapat melihat RFC 2223. Jika saya ingin tahu gaya apa yang digunakan dalam kode Python, saya dapat membaca PEP 8. Jika saya ingin tahu Cara Mengajukan Pertanyaan dengan Cara Cerdas, ESR telah melindungi saya. Apakah ada panduan serupa untuk spesifikasi format file? Atau contoh yang sangat baik dari satu? Saya pasti bisa menggunakan penilaian saya sendiri, tetapi jika ada standar, akan masuk akal untuk mengikutinya.

— Sopoforic