Как документировать спецификацию формата файла [закрыто]

12

Для проекта мне нужно работать с различными типами файлов из некоторых старых игр и сопутствующего программного обеспечения - конфигурационных файлов, сохранений, архивов ресурсов и так далее. Большая их часть еще не документирована, и не существует инструментов для работы с ними, поэтому я должен перепроектировать форматы и собрать свои собственные библиотеки для их обработки.

Хотя я не думаю, что большая часть этого спроса востребована, я намерен опубликовать результаты своих усилий. Существуют ли принятые стандарты для документирования форматов файлов? Оглядываясь вокруг, можно использовать несколько стилей: некоторые, такие как Спецификация формата файла .ZIP , очень многословны; другие, такие как в XentaxWiki, гораздо более лаконичны - некоторые из них трудно читать; лично мне больше всего нравится это описание файловой системы карты памяти PlayStation 2 , которая включает в себя как подробный описательный текст, так и несколько «карт памяти» со смещениями и тому подобное - оно также наиболее близко соответствует моему варианту использования. Это будет немного отличаться для разных форматов, но, похоже, должны быть общие принципы, которым я должен следовать.

Изменить: Я, кажется, не очень хорошо объяснил, что я хочу сделать. Позвольте мне построить пример.

У меня может быть какой-то старый программный продукт, который хранит свою конфигурацию в «двоичном» файле - серию битовых полей, целых чисел, строк и всего такого, что склеено и понято программой, но не читается человеком. Я расшифрую это. Я хочу документально описать формат этого файла, понятный человеку, в качестве спецификации для реализации библиотеки для анализа и изменения этого файла. Кроме того, я хотел бы, чтобы это было легко понято другими людьми.

Существует несколько способов написания такого документа. Приведенный выше пример PKZIP очень многословный и в основном описывает формат файла в произвольном тексте. В примере PS2 приведены таблицы типов значений, смещений и размеров с подробными комментариями о том, что они все значат. Многие другие, такие как в XentaxWiki, перечисляют только типы и размеры переменных, практически без комментариев.

Я спрашиваю, существует ли какой-либо стандарт, похожий на руководство по стилю кодирования, в котором содержится руководство о том, как писать такую ​​документацию. Если нет, то есть ли какой-нибудь известный отличный пример, которому я должен подражать? Если нет, может кто-нибудь хотя бы обобщить некоторые полезные советы?

Sopoforic
источник
Ха! Мне знакомо это чувство. В одном из форматов, на который я смотрел, у меня был исходный код, в котором был написан файл. Проблема заключалась в том, что переменные записывались в другом порядке, чем в определении структуры, с некоторыми дополнительными элементами, расположенными между ними. И комментарии были неправильными по поводу смещений. Это часть того, что вдохновило этот вопрос - сильное желание не делать этого.
Сопофорик,
1
Мой единственный опыт работы с документированными обратными проектированными типами файлов - с wiibrew.org. Если я правильно помню, они задокументировали файл как struct. Это работало довольно хорошо.
MetaFight
1
Возможно, я неправильно понимаю вопрос, но кажется, что вы ищете что-то вроде EBNF .
@MattFenwick: BNF для указания синтаксиса языка; не совсем то, что я после. Я отредактирую, чтобы было яснее, какой формат файла я имею в виду.
Сопофорик

Ответы:

4

Бинарный файл - это просто последовательность битов, сгруппированных в логические единицы в соответствии с определенными правилами . Эти правила обычно называют грамматикой . Грамматику можно разделить на четыре типа ( иерархия Хомского ), а для неконтекстных грамматик вы должны использовать расширенную форму Бэкуса-Наура, как указал Мэтт Фенвик в своем комментарии. Интерпретация (или семантика) последовательности, хранящейся в файле, может быть описана устно или с помощью хорошо аннотированных примеров программ, сериализующих и десериализующих информацию.

Чтобы узнать больше о документировании двоичных форматов файлов, рекомендуем прочитать, например, стандарт ASN.1 .

Охотник на оленей
источник
Технически , большинство файлов конфигурации имеют язык без контекста, так как они имеют конечный язык. Практически, написание «набора всех 2-байтовых строк» ​​(например, для конфигурационного файла, который является просто битовым полем из 16 элементов) в EBNF никому не учит. Указатель на стандарт ASN.1 - самая близкая вещь к полученному ответу, хотя кажется, что спецификация в ASN.1 предназначена для чтения компьютерами, и я хотел получить информацию для написания документации для людей. Однако, если ничто более близко не соответствует моим требованиям, в скором времени я приму этот ответ. Спасибо за вашу помощь.
Сопофорик
2

Это странно, потому что быстрый поиск форматов файлов привел к появлению статьи в Википедии (Список форматов файлов) . Он также включает несколько форматов видеоигр .

Список распространенных форматов файлов данных для видеоигр в системах, поддерживающих файловые системы, чаще всего для компьютерных игр.

Он также включает в себя большой выбор форматов видеоигр .

Список наиболее распространенных расширений имен файлов, используемых, когда образ ПЗУ игры или носитель информации копируется с исходного устройства ПЗУ на внешнюю память, такую ​​как жесткий диск, для резервного копирования или для создания возможности игры с помощью эмулятора. В случае программного обеспечения на основе картриджей, если расширение для конкретной платформы не используется, тогда обычно используются расширения имени файла «.rom» или «.bin», чтобы уточнить, что файл содержит копию содержимого ПЗУ. Образы ПЗУ, дисков или лент обычно не состоят из одного файла или ПЗУ, а представляют собой целую структуру файла или ПЗУ, содержащуюся в одном файле на резервном носителе.


Существуют ли принятые стандарты для документирования форматов файлов?

Официального стандарта нигде нет. Поскольку форматы файлов создаются компанией, компания принимает решение о формате документации.

Адам Цукерман
источник
2
Я думаю, что вы неправильно поняли мой вопрос. Конечно, есть много форматов файлов, которые были задокументированы - я упомянул XentaxWiki, который включает в себя более 1500 над ними. Но файлы, которые меня интересуют, часто не документированы - обычно это специфические для игры вещи, такие как сохранение файлов или конфигурации, а не общие форматы контейнеров. Моя ситуация такова, что никакой документации не существует, и я собираюсь написать кое-что - так как это сделать?
Сопофорик,
Точно так же все остальные форматы файлов были задокументированы.
Роберт Харви
4
@RobertHarvey: Запутанный, противоречивый, неточный и неполный? Серьезно, хотя, как я уже упоминал, я отметил несколько различных общих стилей в использовании. Я недостаточно знаком с работой в этой области, чтобы знать, стоит ли отдавать предпочтение какому-либо конкретному стилю. Те, что в XentaxWiki, единственном крупнейшем ресурсе, который я видел, почти исключительно для контейнерных форматов, поэтому они не совсем соответствуют более общему случаю. Если бы я подумал, что достаточно просто выбрать случайный пример для подражания, я бы не стал просить совета.
Сопофорик,
@ Сопофорик: Тогда вам нужно уточнить в своем вопросе, что вы хотите. Вы серьезно спрашиваете нас "Как мне написать документацию для формата файла?" Есть целые учебные программы по техническому письму, которые посвящены этому предмету. Найдите формат, который имеет четкую, хорошо написанную документацию (в соответствии с вашими личными стандартами), и подражайте этому. Они не могут быть все дерьмом. Подсказка: примеры использования - король. Четкость объяснения наступает близко.
Роберт Харви
1
@RobertHarvey: Да, очень похоже на вопросы о том, как комментировать ваш код или как документировать функцию, я ищу «руководство по стилю» для написания понятной спецификации формата. Если я хочу знать, как написать RFC, я могу взглянуть на RFC 2223. Если я хочу узнать, какой стиль использовать в коде Python, я могу прочитать PEP 8. Если я хочу знать, как задавать вопросы, Smart Way, ESR меня прикрыл. Существуют ли аналогичные инструкции для спецификаций формата файлов? Или хорошо известный отличный пример одного? Я, конечно, могу использовать свое собственное суждение, но если стандарт существует, было бы разумно следовать ему.
Сопофорик