Создание статьи, отчета или презентации с использованием синтаксиса Pweave noweb

Как только вы узнаете, хотя бы в какой-то степени, мощь LaTeX, вы сможете расширить его возможности даже больше. Одна из возможных идей — интегрировать некоторый код в вашу публикацию в соответствии с концепцией литературного программирования.

Есть много способов как это сделать на практике. Во-первых, я хотел бы представить вам способ интеграции кода Python в документ LaTeX. Во-вторых, мы поговорим об инструментах, которые могут помочь нам реализовать все идеи.

Мы собираемся использовать так называемый синтаксис «noweb» для встраивания кода Python в документ LaTeX. Синтаксис «noweb» имеет некоторые отличительные преимущества: нет необходимости в установке собственного пакета LaTeX «Pweave», после запуска Pweave, перед компиляцией LaTeX - окончательный документ представляет собой обычный документ TeX, который можно скомпилировать в PDF на любом компьютере имея только необходимые пакеты TeX и источники.

Базовый фрагмент кода noweb помечен как:

<<>>=
x = 987.2
x = x**2
@

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

Pweave поддерживает размещение встроенного кода в пределах маркеров <% %> и результата выражения в пределах маркеров <%= %>. Типичное использование разметки кода <% %> хорошо иллюстрируется импортом пакетов Python

<%
import sys
from numpy import pi, linspace, sqrt, sin
%>

И фрагмент кода, и маркеры встроенного кода не будут включены в окончательный документ.

Для практического применения этого документа требуется установить следующее программное обеспечение:

1. LaTeX (например, дистрибутив TeXlive)
2. Python (например, дистрибутив Anaconda)
   • Пакет Pweave (установка проверена с Python версий 3.6, 3.7 и 3.9; версия 3.8 имеет некоторые проблемы с Pweave, поэтому не рекомендуется)
3. Редактор (который поддерживает подсветку синтаксиса и пользовательские сборки)

Если не рассматривать этапы установки Python, то следующим шагом будет его настройка для обработки документов Pweave. За основу возьмем известный дистрибутив Anaconda Python. Обычно рекомендуемый способ — создать виртуальную среду для запуска кода Python:

conda create --name pweave
conda install -n pweave python=3.6
conda install -n pweave -c conda-forge pweave
conda install -n pweave pygments
conda install -n pweave numpy

Мы указали версию Python 3.6, если мы этого не сделаем, будет установлена последняя версия.

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

Целью следующего списка является описание редакторов, поддерживающих Pweave:

• TeXstudio (отличный редактор с долгой историей разработки, поддерживает файлы Pweave .Pnw по умолчанию, включая подсветку синтаксиса, с помощью команды пользователя мы можем создавать команды для компиляции файла Pweave в PDF)
• Atom (великолепный редактор с множеством расширений, разработку и поддержку которого компания Microsoft остановила, чтобы не создавать внутреннюю конкуренцию с Visual Studio Code (VSC), во многих случаях применения Atom до сих пор не уступает VSC) с atom-latex или другим пакетом поддержки LaTeX, language-weave extensions (имеет подсветку синтаксиса)

Каждый редактор имеет свою специфику, связанную с подсветкой синтаксиса Pweave. У TeXstudio нет проблем со вставками кода Pweave во встроенные математические уравнения синтаксиса $ $ (например, $ x= <%= x %> $).

Пример открытия и компиляции файла Pweave в TeXstudio представлен ниже:

Настройка команды сборки для редактора TeXstudio

В TeXstudio мы можем создать пользовательскую команду.

Чтобы настроить пользовательскую команду, перейдите в «Параметры» > «Настроить TeXstudio…», затем выберите вкладку «Сборка» слева. На правой панели вы увидите группу «Пользовательские команды», которая состоит из двух полей ввода, самое левое из которых предназначено для имени команды.

Распространенный подход к созданию пользовательской команды сборки состоит в том, чтобы разделить ее на несколько команд, необходимых для выполнения задачи:

1. Давайте назовем первую команду pweave-activate:pweave-activate. Следующее поле ввода, которое мы должны заполнить фактической командой: "C:\Users\yourusername\anaconda3\Scripts\activate.bat" pweave (для ОС Windows). Здесь мы активируем ранее созданную среду «pweave».

2. Имя второй команды — pweave:pweave, а командная строка — C:\Users\yourusername\anaconda3\envs\pweave\Scripts\pweave -f tex %.Pnw.

3. Имя третьей команды — «pweave-deactivate:pweave-deactivate», а ее командная строка — «C:\Users\yourusername\anaconda3\condabin\conda.bat deactivate».

4. Последней командой будет pweave-compile:pweave-compile и txs:///pweave-activate | TXS:///pweave | TXS:///pdflatex | TXS:///pdflatex | txs:///pweave-деактивировать. Теперь мы можем использовать его из меню или из комбинации клавиш (которая назначается автоматически при создании пользовательской команды).

Другой популярный подход: мы можем объединить все вышеперечисленные команды в один командный файл для ОС Windows (назовем его build-win.bat):

@echo off

echo "Compile script for pweave noweb documents (.pnw) under Windows OS"
echo "Requires a LaTeX installation"
echo "Requires a Python installation in form of anaconda/miniconda distribution in user directory"
echo "Requires a creation of Python virtual environment with name 'pweave'"
echo "Requires conda package installation with name 'pweave' (within the environment)"
echo "Usage example, e.g.: build-win.bat test.pnw"

set filename=%1
set filenamenoext=%~n1
REM It is recommended that you install anaconda in user directory
REM To adjust to your system setup, in the path string below, replace 'yourusername' with your own
REM and make a correction to anaconda path
set pathtoanaconda="C:\Users\yourusername\anaconda3"

echo "Compiling ...%filename%"

echo "activativating conda pweave environment and compiling by pweave ..."

CALL "%pathtoanaconda:"=%\Scripts\activate.bat" pweave

"%pathtoanaconda:"=%\envs\pweave\Scripts\pweave.exe" -f tex %filename%

echo "compiling %filenamenoext%.tex by pdflatex ... into %filenamenoext%.pdf"

REM In this script, a pdflatex is called, change it according to your TeX engine
pdflatex -synctex=1 -interaction=nonstopmode %filenamenoext%.tex
pdflatex -synctex=1 -interaction=nonstopmode %filenamenoext%.tex

CALL "%pathtoanaconda:"=%\condabin\conda.bat" deactivate

echo "Complete"

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

build-win.bat test.pnw

В этом случае нам понадобится только одна пользовательская команда.

Настройка редактора Atom

В Atom конфигурация пользовательской команды зависит от используемого расширения LaTeX. Здесь мы будем использовать пакет Atom-LaTeX. Конфигурация пользователя пакета может быть установлена в файле .latexcfg в каталоге проекта:

{
"root": "yourfilename.Pnw",
"toolchain": "build-win.bat %DOC.%EXT",
"latex_ext": [".Pnw", ".pnw", ".texw", ".tex"]
}

Текущая подсветка синтаксиса в Atom не поддерживает код Pweave во встроенных математических выражениях, таких как $ x= <%= x %> $. Обходной путь — использовать альтернативную разметку встроенной математики в виде \begin{math} x= <%= x %> \end{math}.

Также есть проблема с компиляцией файла .Pnw при использовании пакета atom-latex. Пакет не распознает их как файлы LaTeX. Все описание проблемы можно найти здесь. Чтобы решить эту проблему, в локальной папке установки пакета я просто изменил одну строку в main.coffee в следующем фрагменте этого файла:

@disposables.add atom.workspace.observeTextEditors (editor) =>
      return if @activated
      editor.observeGrammar (grammar) =>
        if (grammar.packageName is 'atom-latex') or
           ((grammar.scopeName.indexOf('text.tex.latex') > -1) or
            (grammar.scopeName.indexOf('source.pweave.latex') > -1)) or
           (grammar.name is 'LaTeX')
          promise = new Promise (resolve, reject) =>
            setTimeout(( => @lazyLoad()), 100)
            resolve()

Пример открытия и компиляции файла Pweave в Atom представлен ниже:

(продолжение следует)