Cómo documentar una especificación de formato de archivo [cerrado]

Para un proyecto, necesito trabajar con diferentes tipos de archivos de algunos juegos antiguos y software relacionado: archivos de configuración, archivos guardados, archivos de recursos, etc. La mayor parte de estos aún no están documentados, ni existen herramientas para trabajar con ellos, por lo que debo realizar ingeniería inversa de los formatos y construir mis propias bibliotecas para manejarlos.

Aunque no creo que haya una gran demanda para la mayoría, tengo la intención de publicar los resultados de mis esfuerzos. ¿Existen estándares aceptados para documentar formatos de archivo? Mirando a su alrededor, hay varios estilos en uso: algunos, como la especificación de formato de archivo .ZIP , son muy prolíficos; otros, como los de XentaxWiki, son mucho más concisos: algunos de ellos son difíciles de leer; La que más me gusta personalmente es esta descripción del sistema de archivos de la tarjeta de memoria de PlayStation 2 , que incluye texto descriptivo detallado y varios 'mapas de memoria' con compensaciones y demás: también coincide con mi caso de uso. Varía un poco para los diferentes formatos, pero parece que debería haber algunos principios generales que debería tratar de seguir.

Editar: parece que no he explicado muy bien lo que quiero hacer. Déjame construir un ejemplo.

Es posible que tenga algún software antiguo que almacene su configuración en un archivo 'binario': una serie de campos de bits, enteros, cadenas y todo lo que el programa no haya pegado y entendido, pero que no sea legible por humanos. Yo descifro esto. Deseo documentar exactamente cuál es el formato de este archivo, de una manera legible para los humanos, como una especificación para implementar una biblioteca para analizar y modificar este archivo. Además, me gustaría que otras personas lo entiendan fácilmente.

Hay varias formas en que se puede escribir dicho documento. El ejemplo PKZIP anterior es muy prolijo y describe principalmente el formato de archivo en texto libre. El ejemplo de PS2 proporciona tablas de tipos de valores, compensaciones y tamaños, con comentarios extensos sobre lo que significan. Muchos otros, como los de XentaxWiki, solo enumeran los tipos y tamaños variables, con poco o ningún comentario.

Pregunto si hay algún estándar, similar a una guía de estilo de codificación, que proporciona orientación sobre cómo escribir este tipo de documentación. Si no, ¿hay algún ejemplo excelente bien conocido que deba emular? Si no, ¿alguien puede al menos resumir algunos consejos útiles?

documentation reverse-engineering

— Sopoforico
fuente

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

— mosquito

¡Decir ah! Conozco ese sentimiento. Un formato que estaba viendo en realidad tenía el código fuente original que escribió el archivo. El problema era que las variables se escribían en un orden diferente que en la definición de la estructura, con algunas cosas adicionales esparcidas entre ellas. Y los comentarios estaban equivocados sobre las compensaciones. Es parte de lo que inspiró esta pregunta: un fuerte deseo de NO HACER ESO.

— Sopoforic

Mi única experiencia con los tipos de archivo documentados de ingeniería inversa es de wiibrew.org. Si no recuerdo mal, documentaron el archivo como a struct. Funcionó bastante bien.

— MetaFight

Puedo estar malinterpretando la pregunta, pero parece que estás buscando algo como EBNF .

@MattFenwick: BNF es para especificar la sintaxis de un idioma; no es exactamente lo que busco. Editaré para tener más claro a qué tipo de formato de archivo me refiero.

— Sopoforic

Respuestas:

Un archivo binario es solo una secuencia de bits organizados en unidades lógicas de acuerdo con ciertas reglas . Estas reglas generalmente se llaman gramática . La gramática se puede clasificar en cuatro tipos (la jerarquía de Chomsky ), y para las gramáticas libres de contexto , debe usar la Forma Backus-Naur Extendida como lo señala Matt Fenwick en su comentario. La interpretación (o semántica) de la secuencia almacenada en el archivo puede describirse verbalmente o con programas de muestra bien anotados que serializan y deserializan la información.

Para saber más sobre la documentación de formatos de archivos binarios, sugiera leer, por ejemplo, en el estándar ASN.1 .

— Cazador de ciervos
fuente

Técnicamente , la mayoría de los archivos de configuración tienen un lenguaje sin contexto, ya que tienen un lenguaje finito. Prácticamente, escribir 'el conjunto de todas las cadenas de 2 bytes' (por ejemplo, para un archivo de configuración que es solo un campo de bits de 16 elementos) en EBNF no le enseña nada a nadie. El puntero al estándar ASN.1 es lo más parecido a una respuesta que he recibido, aunque parece que una especificación en ASN.1 está destinada a ser leída por computadoras, y quería información para escribir documentación para humanos. Sin embargo, si no aparece nada más que coincida con mis requisitos, en breve, aceptaré esta respuesta. Gracias por su ayuda.

— Sopoforic

Eso es extraño porque una búsqueda rápida de formatos de archivo mostró un artículo de Wikipedia (Lista de formatos de archivo) . También incluye varios formatos de datos de videojuegos .

Lista de formatos de archivos comunes de datos para videojuegos en sistemas que admiten sistemas de archivos, más comúnmente juegos de PC.

También incluye una gran selección de formatos de medios de almacenamiento de videojuegos .

Lista de las extensiones de nombre de archivo más comunes que se utilizan cuando la imagen ROM o el medio de almacenamiento de un juego se copia desde un dispositivo ROM original a una memoria externa, como un disco duro, para realizar copias de seguridad o para que el juego se pueda jugar con un emulador. En el caso del software basado en cartuchos, si no se usa la extensión específica de la plataforma, las extensiones de nombre de archivo ".rom" o ".bin" generalmente se usan para aclarar que el archivo contiene una copia de un contenido de una ROM. Las imágenes de ROM, disco o cinta generalmente no consisten en un solo archivo o ROM, sino en un archivo completo o estructura ROM contenida dentro de un solo archivo en el medio de respaldo.

¿Existen estándares aceptados para documentar formatos de archivo?

No hay un estándar "oficial" en ninguna parte. Dado que los formatos de archivo son realizados por una empresa, la empresa decide el formato de la documentación.

— Adam Zuckerman
fuente

Creo que has entendido mal mi pregunta. Por supuesto, hay muchos formatos de archivo que se han documentado: mencioné XentaxWiki, que incluye más de 1500 sobre ellos. Pero los archivos que me interesan a menudo no están documentados: cosas específicas del juego como guardar archivos o configuración, en lugar de formatos de contenedor generales, por lo general. Mi situación es que no existe documentación, y tengo la intención de escribirla, entonces, ¿cómo se hará esto?

— Sopoforic

De la misma manera, todos esos otros formatos de archivo fueron documentados.

— Robert Harvey

@RobertHarvey: ¿Confuso, conflictivo, inexacto e incompleto? En serio, sin embargo, como mencioné, noté varios estilos generales diferentes en uso. No estoy lo suficientemente familiarizado con el trabajo en esta área para saber si se prefiere algún estilo en particular. Los de XentaxWiki, el recurso más grande que he visto, son casi exclusivamente para formatos de contenedor, por lo que no se asignan al caso más general. Si pensara que elegir un ejemplo aleatorio para emular sería lo suficientemente bueno, no estaría pidiendo consejo.

— Sopoforic

@Sopoforic: Entonces debes tener más claro en tu pregunta lo que quieres. ¿Nos está preguntando seriamente "¿Cómo escribo la documentación para un formato de archivo?" Hay currículos educativos completos sobre redacción técnica dedicados a ese tema. Busque un formato que tenga documentación clara y bien escrita (de acuerdo con sus estándares personales) y emule ese. No todos pueden ser basura. Sugerencia: los ejemplos de uso son el rey. La claridad de la explicación viene en segundo lugar.

— Robert Harvey

@RobertHarvey: Sí, al igual que las preguntas sobre cómo comentar su código o cómo documentar una función, estoy buscando una 'guía de estilo' para escribir una especificación de formato comprensible. Si quiero saber cómo escribir un RFC, puedo ver el RFC 2223. Si quiero saber qué estilo usar en el código Python, puedo leer PEP 8. Si quiero saber cómo hacer preguntas de manera inteligente, ESR me tiene cubierto. ¿Hay alguna guía similar para las especificaciones de formato de archivo? ¿O un excelente ejemplo bien conocido de uno? Seguramente puedo usar mi propio juicio, pero si existe un estándar, sería sensato seguirlo.

— Sopoforic