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

12

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?

Sopofórico
fonte
Ha! Eu conheço esse sentimento. Um formato que eu estava vendo, na verdade, tinha o código fonte original que escreveu o arquivo. O problema era que as variáveis ​​estavam sendo escritas em uma ordem diferente da definição da estrutura, com algumas coisas extras espalhadas no meio. E os comentários estavam errados sobre as compensações. É parte do que inspirou essa pergunta - um forte desejo de NÃO FAZER ISSO.
Sopoforic
1
Minha única experiência com tipos de arquivos de engenharia reversa documentados é de wiibrew.org. Se bem me lembro, eles documentaram o arquivo como um arquivo struct. Funcionou muito bem.
MetaFight
1
Posso estar entendendo mal a pergunta, mas parece que você está procurando algo como o EBNF .
@MattFenwick: BNF é para especificar a sintaxe de um idioma; não é bem o que estou procurando. Vou editar para ficar mais claro que tipo de formato de arquivo eu quero dizer.
Sopoforic

Respostas:

4

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 .

Deer Hunter
fonte
Tecnicamente , a maioria dos arquivos de configuração possui uma linguagem livre de contexto, pois possui uma linguagem finita. Praticamente, escrever 'o conjunto de todas as strings de 2 bytes' (por exemplo, para um arquivo de configuração que é apenas um campo de bits de 16 itens) no EBNF não ensina nada a ninguém. O ponteiro para o padrão ASN.1 é a coisa mais próxima de uma resposta que recebi, embora pareça que uma especificação no ASN.1 seja para ser lida por computadores, e eu queria informações para escrever documentação para humanos. No entanto, se nada mais próximo dos meus requisitos aparecer, em breve aceitarei esta resposta. Obrigado pela sua assistência.
Sopoforic 07/04
2

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.

Adam Zuckerman
fonte
2
Acho que você não entendeu minha pergunta. É claro que existem muitos formatos de arquivo que foram documentados - mencionei o XentaxWiki, que inclui mais de 1500 sobre eles. Mas os arquivos nos quais estou interessado geralmente não são documentados - coisas específicas do jogo, como salvar arquivos ou configuração, em vez de formatos gerais de contêiner, geralmente. Minha situação é que não existe documentação e pretendo escrever alguns - então como isso deve ser feito?
Sopoforic
Da mesma forma que todos os outros formatos de arquivo foram documentados.
Robert Harvey
4
@RobertHarvey: Confuso, conflitante, impreciso e incompleto? Sério, como mencionei, notei vários estilos gerais diferentes em uso. Não estou familiarizado o suficiente com o trabalho nessa área para saber se algum estilo em particular deve ser preferido. Os do XentaxWiki, o maior recurso que já vi, são quase exclusivamente para formatos de contêiner, portanto, eles não são mapeados para o caso mais geral. Se eu pensasse que apenas escolher um exemplo aleatório para emular seria bom o suficiente, eu não pediria conselhos.
Sopoforic
@ Sopoforic: Então você precisa ser mais claro na sua pergunta sobre o que deseja. Você está nos perguntando seriamente "Como escrevo a documentação para um formato de arquivo?" Existem currículos educacionais completos sobre redação técnica que são dedicados a esse assunto. Encontre um formato que possua documentação clara e bem escrita (de acordo com seus padrões pessoais) e emule-o. Nem todos podem ser uma porcaria. Dica: exemplos de uso são rei. A clareza da explicação chega em segundo lugar.
Robert Harvey
1
@RobertHarvey: Sim, assim como perguntas sobre como comentar seu código ou como documentar uma função, estou procurando um 'guia de estilo' para escrever uma especificação de formato compreensível. Se eu quiser saber como escrever uma RFC, posso olhar para a RFC 2223. Se quiser saber qual estilo usar no código Python, posso ler o PEP 8. Se quiser saber como fazer perguntas de maneira inteligente, ESR me cobre. Existe alguma orientação semelhante para especificações de formato de arquivo? Ou um excelente exemplo bem conhecido de um? Certamente posso usar meu próprio julgamento, mas se existir um padrão, seria sensato segui-lo.
Sopoforic 06/04