org-lit

Этот пакет не в состоянии заменить собой org-babel-tangle полностью, но лишь дополняет его. Про некоторые моменты известно, что они точно не работают, прочие же не проверялись. org-babel — очень мощный пакет функций с очень большим количеством возможностей, за что ему огромное спасибо. Но в некоторых случаях он работает, скажем так, не самым лучшим образом.

Этот пакет заточен на разработку ПО в литературном стиле, когда исходный код плавно вытекает из прочих текстовых человекочитаемых описаний. Для такого применения не столь важны разнообразные наполнения блоков кода в результате исполнения другого кода, сколь важна возможность наполнения блоков кода не в том порядке в каком они будут удобны для компьютера, а в том, в котором они будут удобны автору описаний, а в последствии способствуют лучшему пониманию читателя.

Поэтому упор сделан в основном на разбор следующей типовой ситуации. Сначала пишем код со вставками вроде <<тут-чего-то-чего-будет-детализовано-далее>>, а где-то далее по тексту заполняем эти вставки. Где сами последующие вставки и дополнения — это полнострочные кусочки кода. Зато служебные комментарии добавляемые в процессе запутывания файлов с кодом позволяют однозначно осуществить навигацию между запутанным файлом и файлом с орг-исходником.

Подробнее про мотивацию к разработке этого пакета можно почитать в "литературных" исходниках.

Вот чего точно здесь пока не работает:

• :noweb-sep поддержка кастомизации разделителей для блоков noweb пока не сделана. Этот аспект вообще не очень тщательно проработан, поэтому всякие вложения вроде print "<<noweb>>" могут не очень хорошо работать на выходе может получиться что-нибудь неожиданное вроде:

  print "
  something from other block
  "
  

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

У меня в doom-emacs это сделано так:

(package! org-lit
 :recipe (:type git
 :host codeberg
 :repo "irbis/org-lit"))

А затем настроено так:

(use-package! org-lit
 :after org
 :config
 (add-hook 'org-mode-hook #'org-lit-auto-tangle-mode)
 (setq org-lit-comments-default "yes")
 (setq org-lit-auto-tangle-default nil))

После этого можно пользоваться главными командами:

• org-lit-tangle — для того, чтобы запутать всё из текущего орг-файла
• org-lit-jump-to-src — для того, чтобы перейти на соответствующую строку в запутанце
• org-lit-jump-to-org — для того, чтобы перейти из файла запутанца на соответствующую строку в орг-исходнике
• org-lit-src-goto-line — для того, чтобы находясь в файле орг-исходника указать номер строки в запутанце, например, как её показывает какой-нибудь компилятор или линтер, и перейти на соответствующую ей строку в орг-исходнике
• org-lit-detangle — для того, чтобы находясь в файле запутанца распутать изменения в его содержимом обратно в орг-исходник, изменения предполагаются "мелкими", без всяких полных удалений блоков и всякого такого

Из настроек пока имеется одна настроечная переменная

• org-lit-comments-default — задаёт значение по-умолчанию для заголовка :comments в блоках кода. Если nil или "no", то служебные комментарии не будут выводиться. Если же любое другое значение из описанных в документации орг-моды, то будут.

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

Для этого следует включить переменную (setq org-lit-auto-tangle-default t) в конфигурации, чтобы автоматически запутывались все сохраняемые орг-файлы. Я включаю её точечно в файле .dir-locals.el в корне соответствующих проектов. Либо можно добавлять ключевик #+auto_tangle: t непосредственно в редактируемый орг-файл.

Если вам интересно узнать как это дело устроено и почему именно так, то можно поизучать литературные исходники пакета в файле org-lit.el.org.

Для сборки и тестирования используестя инструментарий Eldev.

Скрипты по управлению проектом собраны в Makefile, который запутывается из файле Makefile.org командой ./configure.

После этого можно подготовить проектные настройки которые запутываются из файла bootstrap.org командой make bootstrap.

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