Como documentar uma especificação de formato de arquivo [fechada]

Para um projeto, preciso trabalhar com vários tipos de arquivos de alguns jogos antigos e softwares relacionados - arquivos de configuração, salvamentos, arquivos de recursos e assim por diante. A maior parte delas ainda não está documentada, nem existem ferramentas para trabalhar com elas; portanto, devo fazer engenharia reversa dos formatos e criar minhas próprias bibliotecas para lidar com eles.

Embora eu não suponha que exista grande demanda pela maior parte, pretendo publicar os resultados de meus esforços. Existem padrões aceitos para documentar formatos de arquivo? Olhando em volta, existem vários estilos em uso: alguns, como a Especificação de Formato de Arquivo .ZIP , são muito prolixo; outros, como os do XentaxWiki, são muito mais concisos - acho que alguns deles são difíceis de ler; o que eu mais gosto pessoalmente é essa descrição do sistema de arquivos do cartão de memória PlayStation 2 , que inclui texto descritivo detalhado e vários 'mapas de memória' com deslocamentos e coisas do gênero - ele também se aproxima mais do meu caso de uso. Vai variar um pouco para diferentes formatos, mas parece que deve haver alguns princípios gerais que eu deveria tentar seguir.

Edit: Parece que eu não expliquei muito bem o que eu quero fazer. Deixe-me construir um exemplo.

Talvez eu tenha algum software antigo que armazene sua configuração em um arquivo 'binário' - uma série de campos de bits, números inteiros, seqüências de caracteres e outros itens colados e entendidos pelo programa, mas não legíveis por humanos. Eu decifro isso. Desejo documentar exatamente qual é o formato deste arquivo, de maneira legível por humanos, como uma especificação para implementar uma biblioteca para analisar e modificar esse arquivo. Além disso, eu gostaria que isso fosse facilmente entendido por outras pessoas.

Existem várias maneiras de escrever esse documento. O exemplo PKZIP acima é muito prolixo e descreve principalmente o formato do arquivo em texto livre. O exemplo do PS2 fornece tabelas de tipos de valores, compensações e tamanhos, com extensos comentários sobre o que todos eles significam. Muitos outros, como os do XentaxWiki, listam apenas os tipos e tamanhos de variáveis, com pouco ou nenhum comentário.

Pergunto se existe algum padrão, semelhante a um guia de estilo de codificação, que fornece orientações sobre como escrever esse tipo de documentação. Se não, existe algum exemplo excelente e conhecido que eu deveria imitar? Caso contrário, alguém pode pelo menos resumir alguns conselhos úteis?

Um arquivo binário é apenas uma sequência de bits organizados em unidades lógicas de acordo com certas regras . Essas regras são geralmente chamadas de gramática . A gramática pode ser classificada em quatro tipos (a hierarquia de Chomsky ) e, para gramáticas sem contexto, você deve usar o Extended Backus-Naur Form, conforme apontado por Matt Fenwick em seu comentário. A interpretação (ou semântica) da sequência armazenada no arquivo pode ser descrita verbalmente ou com programas de amostra bem anotados, serializando e desserializando as informações.

Para saber mais sobre a documentação de formatos de arquivos binários, sugira a leitura, por exemplo, do padrão ASN.1 .

Isso é estranho, porque uma pesquisa rápida de formatos de arquivo trouxe um artigo da Wikipedia (Lista de formatos de arquivo) . Ele também inclui vários formatos de dados de videogame .

Lista de formatos de arquivo comuns de dados para jogos de vídeo em sistemas que suportam sistemas de arquivos, mais comumente jogos de PC.

Ele também inclui uma grande variedade de formatos de mídia de armazenamento de videogame .

Lista das extensões de nome de arquivo mais comuns usadas quando a imagem de ROM ou a mídia de armazenamento de um jogo é copiada de um dispositivo ROM original para uma memória externa, como disco rígido, para fins de backup ou para tornar o jogo jogável com um emulador. No caso de software baseado em cartucho, se a extensão específica da plataforma não for usada, as extensões de nome de arquivo ".rom" ou ".bin" serão usadas para esclarecer que o arquivo contém uma cópia do conteúdo de uma ROM. As imagens de ROM, disco ou fita geralmente não consistem em um único arquivo ou ROM, mas em um arquivo inteiro ou estrutura de ROM contida em um único arquivo na mídia de backup.

Existem padrões aceitos para documentar formatos de arquivo?

Não existe um padrão "oficial" em lugar nenhum. Como os formatos de arquivo são criados por uma empresa, a empresa decide o formato da documentação.