Per un progetto, ho bisogno di lavorare con vari tipi di file da alcuni vecchi giochi e software correlati: file di configurazione, salvataggi, archivi di risorse e così via. La maggior parte di questi non è ancora stata documentata, né esistono strumenti per lavorare con loro, quindi devo decodificare i formati e creare le mie librerie per gestirli.
Anche se non credo che ci sia una grande richiesta per la maggior parte, ho intenzione di pubblicare i risultati dei miei sforzi. Esistono standard accettati per la documentazione dei formati di file? Guardandoti intorno, ci sono diversi stili in uso: alcuni, come la .ZIP File Format Specification , sono molto prolisso; altri, come quelli su XentaxWiki, sono molto più concisi - trovo che alcuni di essi sono difficili da leggere; quello che personalmente mi piace di più è questa descrizione del file system della scheda di memoria PlayStation 2 , che include sia il testo descrittivo dettagliato che varie "mappe della memoria" con offset e simili - anche il più fedelmente corrisponde al mio caso d'uso. Varia un po 'per i diversi formati, ma sembra che ci dovrebbero essere alcuni principi generali che dovrei provare a seguire.
Modifica: sembra che non abbia spiegato molto bene cosa voglio fare. Consentitemi di costruire un esempio.
Potrei avere qualche vecchio software che memorizza la sua configurazione in un file 'binario' - una serie di bitfield, interi, stringhe e quant'altro tutti incollati e compresi dal programma, ma non leggibili dall'uomo. Io decifro questo. Desidero documentare esattamente qual è il formato di questo file, in un modo leggibile dall'uomo, come una specifica per l'implementazione di una libreria per analizzare e modificare questo file. Inoltre, mi piacerebbe che fosse facilmente comprensibile da altre persone.
Ci sono diversi modi in cui un tale documento potrebbe essere scritto. L'esempio di PKZIP sopra è molto verboso e descrive principalmente il formato del file in testo libero. L'esempio PS2 fornisce tabelle di tipi di valore, offset e dimensioni, con ampi commenti su cosa significano tutti. Molti altri, come quelli su XentaxWiki, elencano solo i tipi e le dimensioni delle variabili, con commenti piccoli o assenti.
Chiedo se esiste uno standard, simile a una guida allo stile di codifica, che fornisce indicazioni su come scrivere questo tipo di documentazione. In caso contrario, c'è qualche eccellente esempio noto che dovrei emulare? Se no, qualcuno può almeno riassumere qualche consiglio utile?