HelpDown Makefile scripts

Предлагается система сборки документации в различных форматах (.hlf, .html, и .md для форума) из единого источника на базе Markdown.

Система представляет собой базовый Makefile, и несколько lua-скриптов (“фильтров”), необходимых для тонкой настройки вывода.

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

Требования:

• pandoc
• HtmlToFarHelp (или прямая ссылка на файл пакета)
• make или winget install ezwinports.make
• Makefile + cкрипты из данного репозитория. Или архив.

Для чего же нужны фильтры, приведу лишь несколько примеров:

• Для md, в частности для публикации на Github:

  • При конвертации в Github-flavored Markdown у заголовков пропадают id, указанные посредством attribute syntax, а значит ломаются ссылки. Их можно исправить, используя “автоматические идентификаторы” (Implicit Headers IDs).
  • DefinitionList (Description List) не является стандартной фичей маркдауна, его надо заменить на BulletList.

• Для hlf:

  • Cформировать индекс справки, и в каждый раздел добавить перекрёстные ссылки на другие (например в верхнем блоке как в справке LuaCheck. Или в нижнем, как в BufferScroll).
  • Выделить внутренние заголовки, добавив их содержимому дополнительный отступ.

• Для презентации какого-либо скрипта на форуме его документацию стоит специально подготовить, в частности:

  • Исправить форматирование при наличии одиночного *, поскольку стандартный способ экранирования слешем на форуме не работает.
  • Преобразование ссылок:
    • Движок форума не создаёт внутренние ссылки, поэтому их надо убрать (заменить на просто жирный текст).
    • Ссылки на справку фара работают только в hlf. А в html, в md и для форума их надо заменять на что-то более полезное.
    • Аналогично со ссылками на локальные *.chm и пр.
  • Поместить все разделы кроме первого в спойлеры, чтобы сэкономить место в посте.

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

• Для html полезно Title не оставлять пустой, а продублировать туда первый Header.

Чтобы подключить всё это к своему проекту достаточно Makefile подобного примеру в Makefile.sample.
Всё, теперь при наличии исходного документа в файле с расширением *.text достаточно запустить команду make для создания *.hlf.
Или же явно указать цель: make hlf, make html, make forum.
В качестве цели также может быть указано имя результирующего файла.