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

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

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

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

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

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

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

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

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

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

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

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

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

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

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