vdf_specification_ru.md

title	author	version	description
Versatile Description Format specification	Nikolay Gniteev ([email protected])	1.0.draft.4	Specification of Versatile Description Format (for hardware)

Спецификация формата описания Versatile Description Format

Данный формат обеспечивает смешанное описание документации и кода в одном файле

Формат позволяет совмещать разные форматы структурированного текстового описания, языки и способы описания в одном файле

Формат позволяет описывать документацию и код секциями и держать описание и код рядом друг с другом, а так же формировать фрагменты кода из самого описания

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

Формат позволяет создавать документацию, код и сопутствующие артефакты и интерактивно выполнять код последовательно добавляя / изменяя фрагменты документации и кода с помощью "ячеек", являющихся основными "строительным" элементом документа

Цепочки ячеек документа могут организовываться как линейным так и нелинейными способами чтобы наглядно показать разницу между различными вариантами или для того чтобы провести эксперименты

Был обнаружен проект, в котором много идей уже реализовано - Quarto. В ближайшем времени принципы проекта VDF будут пересмотрены с точки зрения интеграции с Quarto.

Принцип описания

Текстовый файл делится на "ячейки" - элементарные единицы

Ячейки могут быть двух типов - описательные / исполнимые

Разделителем ячеек является строка, содержащая ---

Формат текста в описательных ячейках определяется типом файла

Возможно использование в качестве основы различных форматов структурированного описания - markdown, asciidoc и т.п. в которых имеется понятие fenced code а так же использование формата jupyter notebook (для описательных ячеек используется markdown). Но на весь документ м.б. использоваться только один формат.

Исполнимые ячейки в форматах структурированного описания должны содержать только fenced code В формате jupyter notebook исполнительная ячейка должна быть типа code с указателем используемой "магии"

В исполнимых ячейках строка --- не приведёт к разделению на ячейки

В исполнимых ячейках содержатся специальные тэги, управляющими как с их с помощью формируются исходные файлы / документация или осуществляется исполнение (симуляция и т.п.)

При исполнении определённых ячеек результат сохраняется и это значение м.б. использовано позже если ячейке было дано имя, а так же при исполнении каждой ячейки регистрируется вывод stdout/stderr, который может быть отображён с помощью специальных ячеек

Некоторые тэги могут так же использоваться для наполнения описательных ячеек (подстановка значений, преобразования кода в описание)

Система тэгов

Тэги определяют поведение при компиляции исполнимой ячейки в код, структуру последовательности ячеек и многие другие аспекты

В ячейке указывается:

• обязательно один базовый тэг (один и только один)
• опционально тэги расширения

Тэги расширения могут быть заданы / загружены под типовой случай и иметь эффект на последующие ячейки, а так же иметь эффект на заданную секцию ячеек (границы секции определяется так же с помощью тэгов)

Формат указания тэгов: в первой строке исполнимой ячейки тэги указываются последовательно через пробел после волшебного начала %%vdf . Первым указывается базовый тэг, затем тэги расширения. Порядок тэгов расширения м.б. любым, при этом порядок влияет на то, какой будет результат.

Тэги могут дополняться значениями, которые следуют за именем тэга через символ -. Символы значений должны быть из подмножества alpha_numeric, если не указано иное. Если после # следует !, то это отменяет тэг, если он был определён ранее (в ячейке или глобально)

%%vdf #<valueless_tag_name> #<tag_name>-<tag_value> #<tag_name>-<tag_value> #!<tag_name>...

Базовые тэги

Тэги приведены в порядке частоты применения и/или их важности в общем процессе

Тэги описания исходного кода

Выполнение ячеек с тэгами такого типа по умолчанию приводит к созданию и компиляции исходных файлов

none

Эта ячейка не исполняемая

doc

Секция с кодом для формирования фрагментов документации

code

Секция с кодом для архитектуры блока.

В тексте ячейки содержится код декларативной части архитектуры блока и/или тела архитектуры.

В тексте ячейки:

до строки --- - декларативная часть, после - тело

если строка --- отсутствует, то считается что декларативной части нет (если у тэга нет доп.значения declaration)

Возможные значения для тэга:

• без значения эквивалентно add
• add - дополнение кода из прошлых ячеек
• new - ввод кода заново, значения из прошлых ячеек игнорируются
• declaration указание в явном виде что в ячейке код только для декларативной части
• body указание в явном виде что что в ячейке код только для "тела"

Для значений declaration, body подразумевается одновременное действие значения add

header

Секция с кодом заголовочной части.

В тексте ячейки содержится код, предшествующий объявлению блока и/или его архитектуры (там где такое разделение существует) а так же для пакета и/или его тела.

Если спецификация языка на котором написан текст ячейке подразумевает разделение заголовочной части для декларации блока и архитектуры (пакета/тела), то:

до строки --- - заголовочная часть предшествующая объявлению блока, после - часть предшествующая архитектуре блока (в тех случаях где есть такое разделение)

если --- отсутствует, то считается что заголовочной части блока нет (если у тэга нет доп.значения declaration)

Остальной принцип применения и дополнительные значения аналогичны тэгу code

unit

Секция с кодом объявления блока

В тексте ячейки содержится код с декларацией параметров блока и/или интерфейса блока.

В тексте ячейки:

до строки --- - код с описанием параметров блока, после - интерфейсы блока

если строка --- отсутствует, то считается что часть с параметрами отсутствует (если у тэга нет доп.значения generics)

Возможные значения для тэга:

• без значения эквивалентно add
• add - дополнение кода из прошлых ячеек
• new - ввод кода заново, значения из прошлых ячеек игнорируются
• generics - указание в явном виде что в ячейке код только для параметров
• interface - указание в явном виде что что в ячейке код только для интерфейсов

Для значений generics, interface подразумевается одновременное действие значения add

package

Секция с кодом для пакета

Требует использование тэга target (т.е. результат всегда будет в дополнительном исходном файле)

В тексте ячейки:

до строки --- - код для декларативной части пакета, после - для тела пакета

если строка --- отсутствует, то считается что декларативная часть отсутствует (если у тэга нет доп.значения declaration)

Остальной принцип применения и дополнительные значения аналогичны тэгу code

constraints

Ограничения для блока (задел под синтез/кодогенерацию)

Требует использование тэга target (т.е. результат всегда будет в дополнительном исходном файле)

В тексте ячейки содержится текст кода с определениями ограничений

Возможные значения для тэга:

• без значения эквивалентно add
• add - дополнение кода из прошлых ячеек
• new - ввод кода заново, значения из прошлых ячеек игнорируются

subject

Задаёт имя блока, описываемого этим файлом

В теле ячейки - одна строка с именем в формате alpha_numeric

Если не задан, считается значение тэга соответствует имени документа без суффиксов

arch

Задаёт имя архитектуры, описываемой этим файлом

В теле ячейки - одна строка с именем в формате alpha_numeric

Если не задан, считается значение тэга соответствует значению vdf

Тэги для компиляции, исполнения исходного кода и т.п.

Выполнение ячеек с тэгами такого типа по умолчанию приводит к созданию и компиляции исходных файлов, запуску симуляции

display

Вывести результат выражения

В теле ячейки указывается само выражение.

Код с выражением будет помещён в тело архитектуры в специальной обёртке для выполнения и вывода значения без влияния на работу остальной части В коде в сообщении добавляется специальная пометка для поиска его в выводе и извлечения значения

Возможные значения:

• без значения (формат по умолчанию)
• %0h, %0b, %0d и т.п. для функции $display или её эквивалента

Запуск ячейки по умолчанию так же выполняет симуляцию в течении определённого времени

drive

Формат: drive-<name>

Добавляет воздействия в стимул с указанным именем

Возможные значения:

• без значения эквивалентно add
• new - задание стимула с нуля
• add - дополнение уже существующего стимула

Форматы текста в ячейке:

• neutral yaml (описать)
• wavedrom json/yaml

По умолчанию запуск ячейки с таким тэгом только выводит заданную диаграмму

monitor

Формат: monitor-<name>

Добавляет сигналы для отображения в набор с указанным именем

Возможные значения:

• без значения эквивалентно add
• new - задание стимула с нуля
• add - дополнение уже существующего стимула

Формат текста в ячейке: в строку иерархический путь сигналов

Дополнительно в строке м.б. указан после символа : тип и формат данных (clk/bit/data и т.п. что есть в wavedrom и ещё где)

Запуск ячейки по умолчанию так же выполняет симуляцию в течении определённого времени

golden

Формат: golden-<name>

Добавляет сигналы и их диаграмму для сравнения

Возможные значения:

• без значения эквивалентно add
• new - задание стимула с нуля
• add - дополнение уже существующего стимула

Формат текста в ячейке: TODO:

По умолчанию запуск ячейки с таким тэгом только выводит заданную диаграмму

generics

Задаёт параметры для блока верхнего уровня

Возможные значения:

• без значения эквивалентно add
• new - задание стимула с нуля
• add - дополнение уже существующего стимула

Формат текста в ячейке: словарь YAML

pragma

Установка параметров препроцессора

Возможные значения:

• без значения эквивалентно add
• add - дополнение уже ранее заданных параметров
• new - ввод параметров заново

Текст ячейки в формате списка yaml

order

Значение ячейки содержит порядок компиляции в случае если для выполнения ячеек требуется задействовать другие файлы (в т.ч. файлы порождённые с помощью самих ячеек)

Возможные значения:

• без значения эквивалентно add
• add - дополнение уже существующего порядка
• new - новый порядок компиляции, старый игнорируется

Текст ячейки - строки содержащую пару - имя библиотеки (alpha_numeric) и путь к файлу, разделённые пробелами

env

Установка переменных окружения

Возможные значения:

• без значения эквивалентно add
• add - дополнение уже ранее заданных переменных
• new - ввод переменных заново

Текст ячейки в формате словаря yaml

ctag

Определение действий для кастомного тэга

pre

Инструкции (shell) для препроцессинга перед этапами сборки/выполнения

Формат: pre-(build|run)

Возможные доп. значения:

• без значения эквивалентно add
• new - задание инструкций с нуля
• add - дополнение уже существующих инструкций

В тексте ячейки - команды shell в строку

В качестве аргументов команды могут быть использованы результаты выполнения ячеек через переменную окружения с именем CELL_<имя ячейки>

Если значение ячейки разделено ---, то часть до --- м.б. использована как аргумент через переменную окружения CELL

post

Инструкции (shell) для препроцессинга после этапов сборки/выполнения

Формат: post-(build|run)

Возможные значения:

• без значения эквивалентно add
• new - задание стимула с нуля
• add - дополнение уже существующего стимула

В тексте ячейки - команды shell в строку

В качестве аргументов команды могут быть использованы результаты выполнения ячеек через переменную окружения с именем CELL_<имя ячейки>

Если значение ячейки разделено ---, то часть до --- м.б. использована как аргумент через переменную окружения CELL

Тэги для работы со структурой документа и управления выводом

define

Ячейка с определением значений по-умолчанию тэгов для последующих ячеек

Формат - построчный список тэгов

Возможные значения для тэга:

• без значения эквивалентно add
• add - дополнение/изменение уже ранее заданных значений
• new - ввод значений заново

replace

требует использование тэга name

варианты значений:

• без значения эквивалентно cell
• cell - замена всего тела ячейки
• tags - замена только тэгов
• full - полная замена ячейки
• p1 - замена 1й части ячейки (части до строки-разделителя, если ячейка м.б. разделена)
• p2 - замена 2й части ячейки (части после строки-разделителя, если ячейка м.б. разделена)

Замена содержимого указанной ячейки

Если указываются доп. тэги и выбран вариант с заменой тэгов - они дополнят / заменят тэги ячейки Если для тэга указано значение NONE, то тэг будет удалён

insert

вставка ячейки до/после указанной ячейки

формат: insert-(after|before)-<cell-name>

cut

вырезать одну или серию ячеек

формат:

• cut-<cell-name>
• cut-<start-cell-name>-<end-cell-name>

output

Тэг для спецификации самого подмножества вывода

Формат: output-<subset-name>

Возможные доп. значения для тэга:

• без значения эквивалентно add
• add - дополнение/изменение уже ранее заданных значений
• new - ввод значений заново

В тексте ячейки содержатся параметры для подмножества в формате словаря YAML

В частности м.б. определено имя ячейки, которая будет выполняться для формирования вывода этого подмножества

Примеры имён подмножеств:

• doc - формирование документации
• src - формирование исходника(ов)

subset

Имя секции и ключ

Формат: subset-<subset-name>-(on|off)

Включение / отключение последующих ячеек для того или иного подмножества вывода

Значения subset-name - те которые были определены тэгами output

disable

Отключение указанных в тексте ячеек из обработки

Действует только на исполнение последующих ячеек

Формат текста - список имён и/или диапазонов ячеек в строку и/или через запятую

Имеет смысл использовать вместе с тэгом расширения cond или external

enable

Включение указанных в теле ячеек из обработки

Действует только на исполнение последующих ячеек

Формат текста - список имён и/или диапазонов ячеек в строку и/или через запятую

Имеет смысл использовать вместе с тэгом расширения cond или external

container

Ячейка не используется для обработки но её содержимое может быть использовано другими ячейками по имени

extend

Тэг для расширения уже существующего документа VDF

Формат: extend[-<subset-name>][-<cell-name>]

Применение этого тэга эквивалентно тому, как если бы вместо него были введены ячейки из заданного документа

Если указан параметр subset-name то будут использованы только ячейки для указанного подмножества

Если указан параметр cell-name то будет использован вывод указанного под множества для указанной ячейки

В теле ячейки указывается путь документу VDF

Если к ячейке добавлен тэг расширения external, то вывод будет использован в качестве текста документа VDF

tags

В теле ячейки содержится список включения/исключения тэгов для последующих ячеек

Использовать чтобы ограничить используемое подмножество тэгов

Возможные значения:

• off - в ячейке список запрещённых тэгов которые надо запретить
• on - в ячейке содержится список тэгов которые надо разрешить (если они были запрещены)
• lock - список тэгов менять более не разрешается. если в ячейке есть список тэгов то разрешёнными будут только указанные в ячейке

scope

Ограничение зоны действия правил / переменных и т.п.

Формат: scope-<scope-name>-(begin|end)

Вывод информации и пр.

show

Может использоваться как тэг расширения

Тэг для вывода состояний и т.п. на момент запуска ячейки

Влияет на вывод при запуске последующих ячеек

Формат текста - список из значений, приведённых ниже, в строку

• def - sources, stdout, stderr, stim-.*, wave-.*, structure
• sources - все сформированные исходные файлы после препроцессинга
• sources-pre - все сформированные исходные файлы до препроцессинга
• diff - последние изменения в исходных файлах
• file-<path> - вывести указанный файл
• stim-<name> - диаграмма стимула с указанным именем (возможен regex)
• wave-<name> - диаграмма набора сигналов с указанным именем (возможен regex)
• output-<name> - вывод результата указанной ячейки с тэгом display
• stdout - полный вывод stdout
• stdout-build - вывод stdout сборки
• stdout-run - вывод stdout запуска
• stderr - полный вывод stderr
• stderr-build - вывод stderr сборки
• stderr-run - вывод stderr запуска
• symbol - символ блока
• structure - структура/схема блока- cells-branch-<name> - ветвь ячеек до указанной ячейки
• cells - все возможные ячейки и их связи между собой
• cells-branch - текущая ветвь ячеек (до этой ячейки)
• cells-branch-<name> - ветвь ячеек до указанной ячейки

для file, stdout, stderr после доп. - можно указать диапазоны строк для structure после доп - можно указать regex для исключения ячеек, после ещё одного - regex включения ячеек для stim, wave после доп - можно указать диапазон отрезка времени

При использовании с тэгом расширения target вывод осуществляется в указанный файл

После доп. - можно указать формат интерпретации полученных данных:

• md - в виде markdown
• html - в виде html
• yaml - в виде мульти-документа yaml
• tree - в файлы внутри папки, путь папки указывается после доп. -

show-custom

Может использоваться как тэг расширения

Кастомный вывод

Влияет на вывод при запуске последующих ячеек

Возможные доп. значения:

• shell - вывести результат (stdout) команды
• web - получить данные из сервера
• mixed - аналогично include

После доп. - можно указать формат интерпретации полученных данных:

• raw - в виде сырого текста
• md - в формате markdown
• html - в виде html
• yaml - в виде мульти-документа yaml

В качестве аргументов команды могут быть использованы результаты выполнения ячеек через переменную окружения с именем CELL_<имя ячейки>

Если значение ячейки разделено ---, то часть до --- м.б. использована:

• как аргумент команды, доступный при вызове через переменную окружения CELL

Тэги расширения

name

Имя ячейки

Возможные значения:

• значение в формате alpha_numeric

М.б. использован для описательных ячеек

lang

Определяет тип языка для тэгов описания исходного кода

Возможные значения:

• vhdl
• verilog
• sv

Если в fenced секции указан формат подсветки, то он будет использован в качестве значения тэга lang

После значения может идти доп.значение, указывающее тип файла. К примеру header или package.

Тип файла так же м.б. определён с помощью тэга kind

at

В какое время выполнить выражения или захватить диаграмму

Возможные значения:

• время (только для отображения выражения)
• диапазон времени
• <имя сигнала>-<r/f/t/c>[-<номер события>]
  • r - rise (any-to-1)
  • f - fall (any-to-0)
  • t - toggle (any-to-1 / any-to-0)
  • c - change (любое изменение значения)
  • e - expression. Через доп - указывается выражение по наступлению равенства которого осуществляется вывод

Можно указывать несколько тэгов at

fetch

Подгрузка деклараций (только декларативные части) из следующих ячеек чтобы решить проблему курицы и яйца

Формат fetch-<integer-number> - на сколько ячеек вперёд подгружать Формат fetch-<cell-name> - подгружать вплоть до ячейки с указанным именем (включительно)

target

Имя целевого исходного файла

Возможные значения:

• без значения - вывод в <subject>.(v|sv|vhd) (subject определяется с помощью тэга, а расширение - использованным тэгом lang)
• путь файла, в формате alpha_numeric + ./

subsection

Имя секции для группировки кода внутри одной секции

branch

Имя "ветки" описаний. Ячейки из разных веток обрабатываются и выполняются изолировано друг от друга

Возможные значения:

• без значения - эквивалентно использованию значения 0
• значение в формате alpha_numeric

М.б. использован для описательных ячеек

fork

Создать ветку от предыдущей ячейки (или ячейки с указанным именем)

Возможные значения:

• имя ветки в формате alpha_numeric
• опционально через доп.значение имя ячейки

М.б. использован для описательных ячеек

flow

Маршрут выполнения

Возможные значения:

• без значения - эквивалентно использованию значения run
• no
• build
• elaborate/instantiate
• run

parent

Какую ячейку использовать как родительскую при обработке

Возможные значения:

• имя другой ячейки
• root

format

Возможные значения:

• имя формата данных в ячейке (описание для тэга drive и т.п.)

var

Установка значения переменной, которая будет использована для подстановки в текст ячейки / в тэгах с условиями / в значения тэгов

М.б. использован для описательных ячеек

subst

При применении этого тэга в тексте ячейки предварительно будут выполнены подстановки значений переменных, переменных окружения, frontmatter

М.б. использован для описательных ячеек

М.б. использован как самостоятельный тэг

cond

Ячейка используется при соблюдении условия

Возможны значения:

• env-<env-var-name> - имя переменной окружения
• var-<var-name> - имя переменной документа
• subset - имя подмножества вывода

после имени можно указать символ операции сравнения и значение

Можно указывать несколько тэгов cond. Ячейка будет использована при выполнении любого увлосия в любом из тэгов

М.б. использован для описательных ячеек

ignore

Полностью игнорировать ячейку при обработке

после доп. - можно указать условие аналогично тэгу cond

М.б. использован для описательных ячеек

hide

Скрыть ячейку / часть ячейки из вывода в печать

При этом ячейка будет присутствовать в истории и на неё можно ссылаться

Формат hide-[subset-]<value>

subset - подмножество вывода, опционально

Возможны значения:

• без значения эквивалентно body
• body - только тело ячейки
• output - вывод ячейки
• all - ячейку целиком

после доп. - можно указать условие аналогично тэгу cond

toggle

Персонально включить/исключить ячейку в определённом подмножестве вывода

Формат: toggle-<subset>-(on|off)

М.б. использован для описательных ячеек

section

отметка начала той или иной секции

Формат: section-<section-name>-(begin|end)

К ячейкам внутри секции применяются тэги их секции

М.б. использован для описательных ячеек

template

файл с правилами / шаблоном для генерации подмножества вывода

Формат: template-<subset>-<template>

convert

Конверсия значения ячейки в указанный формат при обработке

Возможно конверсия только для совместимых форматов

Возможные значения:

• json для конверсии из формата yaml

external

При использовании этого тэга в теле ячейки содержится команду или путь к внешнему ресурсу, который будет использован для формирования тела ячейки при обработке

Возможные значения:

• file
• shell (stdout)
• get (web)
• cell
• cell_result
• mixed

Тело ячейки формируется из указанного источника (нескольких источников при значении mixed)

в теле ячейки указывается источник в зависимости от значения

• имя файла из которого необходимо вставить код

  • может быть указан файл в формате VDF и после доп. символа : указать имя ячейки / имя начальной и конечной ячейки через -

• команда (shell) результат которой (stdout) необходимо использовать

• имя ячейки этого документа (будет использовано её тело)

• имя ячейки с суффиксом _result (будет использован результат выполнения ячейки)

• ПЕРЕД именем/командой можно указать список / диапазоны строк которые требуется использовать

Для случая mixed по строчно указывается <тип источника>:<источник>

если это ячейка может использовать разделитель ---, то используя разделитель указать разные источники для обеих частей указывается источник для каждой части

М.б. использован для описательных ячеек

vdf

Задать версию спецификации тэгов для этой / последующих ячеек

Возможные значения: версия в формате alpha_numeric+[.]

strip

Удалить из вывода определённую информацию

• vdf - удалить строку %%vdf ... (например если это кодовая ячейка должна ещё отобразиться и в документации)

Особенности для markdown/asciidoc и пр. форматов структурированного описания

• Frontmatter часть документа исключается из ячеек, но м.б. использована для инициализации исходных значений переменных / тэгов
• Исполняемой ячейкой трактуется та, которая полностью содержит fenced блок
• Fenced блок с указанием формата языка определяет язык
• Fenced блок с форматом python будет выполняться (если нет тэга ignore)
• Ячейка с fenced блоком неизвестного формата трактуется как описательная
• Известные форматы:
  • vhdl
  • verilog
  • system verilog
  • python
• параметры можно определить через frontmatter часть
  • в Jupyter Notebook и пр. форматах, не поддерживающих концепцию frontmatter, следует данные frontmatter описать в первой ячейке (типа code для Jupyter Notebook) с тэгами #var-frontmatter #format-yaml

пример frontmatter части

title       : Versatile Description Format specification
author      : Nikolay Gniteev ([email protected])
version     : 1.0.draft.0
vdf         : "1.0"   # Используемая спецификация формата

# Установка атрибутов, определяемых тэгами, в frontmatter части через словарь
attrs     :
  # Установка значений тэга output
  tag1_name : value
  tag2_name :
    subtag  :
      etc   : value

# Установка атрибутов, определяемых тэгами, в frontmatter части через список (эквивалентно записи attr выше), но в этой форме будут учтены все особенности ввода тэгов
define      :
  - tag1_name-value
  - tag2_name-subtag-etc-value

# Установка значений переменных в frontmatter части
vars        :
  # Установка скалярной переменной
  var1_name : value

  # Установка списка
  var2_name :
            - value1
            - value2

  # Установка словаря
  var3_name :
    keyA    : valueA
    keyB    : valueB

  # Установка сложно-составного значения
  var4_name :
    keyCA   : valueCA
    keyCB   :
            - valueCB1
            - valueCB2
    keyCC   :
      subCC1: valueCC1
      subCC2: valueCC2

Сценарии использования

При использовании формата Jupyter Notebook:

• постановка быстрых экспериментов при обучении или при проверках
• сопровождение вопросов - ответов в сообществе
• интерактивный обучающий материал
• упрощение поиска места ошибки
  • инкрементальная компиляция
  • инкрементальное сопровождение кода unit тестами

В общем случае:

• документация, исходный код и тестовый код в непосредственной близости, принцип единого источника истины
• понижение фрагментации кода (описание декларативной части и тела с соответствующим кодом расположены в непосредственное близости)
• сегментация крупных файлов в несколько
• код с rich-text комментариями
• условная компиляция и препроцессор в тех языках где они отсутствуют
• повторное использование небольших фрагментов кода (интерфейсы, регистры управления и пр.)
• кодогенерация в рамках одного файла
• кодогенерация множества файлов по шаблону
• использование с LLM (инкрементальный и слабофрагментированный код с развернутыми пояснениями может служить хорошей базой для обучения и лучше подходить для генерации / контроля контента)

Подмножества тэгов

Хотя все приведённые в спецификации тэги могут быть использованы в любом сценарии использования, всё же рекомендуется ограничиваться в зависимости от сценария

Документация и исходный код

В этом сценарии следует избегать нелинейности, за исключением, возможно, unit тестов при их включении в документ

Быстрый эксперимент, сопровождение вопросов - ответов

В этом сценарии следует максимально упрощать и не создавать лишних сущностей, файлов и т.п.

Принципы обработки файла