Markdown в науке

С распространением персональных компьютеров научные статьи, а также книги, методические пособия и учебники, обрели новый носитель. Осталась в прошлом печатная машинка и текст с отступами, куда впоследствии аккуратно вставлялись формулы и рисунки от руки. Математические формулы с появлением TeX ^[1] набирают обычным текстом. Сейчас TeX уже не просто программа верстки, а способ записи формул. Даже если Вам не довелось с ним работать, а подготовка документа ассоциируется с Word ^[2], удобным и быстрым способом ввода формулы в Word ^[3] служат те самые команды из TeX.

Интернет и эпоха Web 2.0 существенно изменили метод подготовки научных публикаций. Сейчас мы читаем статьи с экранов компьютеров, смартфонов и электронных книг, а не только с бумаги. Крайне желательно, чтобы работа над текстом по превращению журнальной статьи в энциклопедическую вики-справку ^[4], в презентацию, или же в содержимое сайта, не требовала чрезмерных усилий. Далее мы рассмотрим решение означенной проблемы с помощью текстовой разметки Markdown ^[5] и попробуем представить себе дальнейшее развитие технологий.

В чём особенность Markdown-разметки? Почему бы не использовать LaTeX?

Краткий ответ: документ Word это doc/docx ^[6] файл, он открывается с помощью Word ^[2], *.tex файлу нужен LaTeX ^[7], *.pdf требует для просмотра Acrobat Reader ^[8] или схожей по функционалу программы. Текст Markdown ^[5] - это просто текст. Читать и редактировать его чем-то особенным не обязательно.

Хорошо, но это же свойство есть и у файлов LaTeX? Да, но... Сравните:

begin{document}
title{Разметка LaTeX}
maketitle
section{Введение}
Здесь мы рассмотрим несколько проблем.
begin{enumerate}
item Разметка предназначена для человека или машины?
item Нужны ли emph{особые} инструменты и какие?
end{enumerate}
end{document}

# Разметка Markdown
## Введение
Здесь мы рассмотрим несколько проблем.
* Разметка предназначена для человека или машины?
* Нужны ли _особые_ инструменты и какие?

Кого не отпугнул LaTeX «программированием» и логической ^[9] (а не визуальной ^[10]) разметкой, тот всё еще потратит немало сил на борьбу с ним. Цикл «внес изменения - скомпилировал, прочёл - внёс изменения» не самый продуктивный способ работы с текстом. Да и не все способны к отрисовке формул TeX в голове!

Да простят мне эту инвективу поклонники LaTeX’а, хоть и задумано, что Вам не нужно думать об оформлении, только о содержании, остальное возьмет на себя LaTeX… но, будем честны, это не всегда так! Кто верстал диссертацию или автореферат под вкусы конкретного диссертационного совета, а вкусы у них бывают очень специфичны, тот поймет. Вот одна хорошая инструкция, как писать диплом в LaTeX - Как я написал диплом по химии с (Xe)LaTeX ^[11]. Под катом мой опыт - посмотрите и оцените сложность задачи для себя.

% Математические символы и шрифты
usepackage{amsmath}
usepackage{amsfonts}

usepackage{fontspec}
usepackage{xunicode}
usepackage{xltxtra}

% Вместо babel, локализация документа под язык
usepackage{polyglossia}
setmainlanguage{russian}
setotherlanguage{english}

% Чтобы << >> превращались в кавычки
defaultfontfeatures{Mapping=tex-text}

% Идеологически правильные шрифты
setmainfont{Times New Roman}
setsansfont{Arial}
setmonofont{Consolas}

% нужно явно указывать шрифт под каждый язык
newfontfamilyrussianfont{Times New Roman}

usepackage{wrapfig}
usepackage{fancybox}
usepackage{calc}

usepackage{type1cm}
renewcommandnormalsize{%
   @setfontsizenormalsize{9pt}{10.8pt}
   abovedisplayskip 10p@ @plus2p@ @minus5p@
   abovedisplayshortskip z@ @plus3p@
   belowdisplayshortskip 6p@ @plus3p@ @minus3p@
   belowdisplayskip abovedisplayskip
   let@listi@listI}normalsize  

linespread{1.25} % полуторный интервал

clubpenalty=100000
widowpenalty=100000
usepackage{caption}
usepackage{subcaption}
DeclareCaptionLabelFormat{gostfigure}{Рисунок #2}
DeclareCaptionLabelFormat{gosttable}{Таблица #2}
DeclareCaptionLabelSeparator{gost}{~--~}

captionsetup{labelsep=gost}

captionsetup[figure]{labelformat=gostfigure,justification=centering}
captionsetup[table]{labelformat=gosttable}
renewcommand{thesubfigure}{asbuk{subfigure}}
frenchspacing

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

Подружить TeX-разметку с вебом, сделать правку независимой от огромного набора пакетов и самой программы LaTeX, тем не менее, совсем непросто.

С помощью таких инструментов как LyX ^[12] отчасти удаётся преодолеть порог вхождения. Как ни отрицай, но делать таблицы и сложные формулы проще WYSIWYG ^[10] (визуально) и LyX тут очень хорошо помогает. Однако, LyX работает поверх LaTeX, тот поверх TeX и вся эта система подчас громоздка.

Есть и другие решения. Например, Authorea ^[13] или Overleaf ^[14]. Они хорошо подходят для коллектива авторов желающих совместно написать академическую статью. Для многих журналов уже созданы готовые шаблоны и всё, что остается — наполнить форму содержанием. Тем не менее, недостаток WYSIWYG форматирования и упомянутая заточенность только на журналы остаётся камнем преткновения.

Желаемое

Хочется простой, всем и всеми читаемый текст, чтобы применяя к нему автоматизированные фильтры получать:

1. пригодную к отправке в журнал статью (препринт ^[15]),

2. контент блога,

3. слайды презентации,

4. техническую документацию.

Препринт

Начнём с первого пункта. Есть множество редакторов Markdown удобных для коллективной и индивидуальной работы. У себя дома я предпочитаю Typora ^[16], а всем вместе можно воспользоваться StackEditPro ^[17]. Выбор редакторов широк и здесь проблемы нет. Макет сделаем с использованием расширенного синтаксиса Markdown, который реализован в конвертере Pandoc ^[18].

---
title: "Pizza - A Carbohydrate Based Substrate For Tomato Delivery"
date: "Apr 2021"
author: "Sergei Malykhin, Pizza Enthusiasts Institute"
---

# Abstract

Pizza [@pizza2000identification] is an understudied yet widely utilized 
implement for delivering in-vivo *Solanum lycopersicum* based 
liquid mediums in a variety of next-generation mastications studies. 
Here we describe a de novo approach for large scale *T. aestivum* 
assemblies based on protein folding that drastically reduces the 
generation time of the mutation rate. See Figure ref{fig:1}.

# Algorithm

![It's Pizza label{fig:1}](./pizza.png)

Cauchy's integral formula [@dixon1971brief]

$$
f(a)=frac{1}{2πi}∮_γfrac{f(z)}{z-a},dz.
tag{1}
label{eq:1}
$$

As seen in equation $eqref{eq:1}$ ...

# Source Code
Lorem ipsum dolor sit amet, consectetur adipisicing elit, 
sed do eiusmod tempor incididunt ut labo

```python
def foo():
    return "bar"
```

# Table

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

Table: Table styles. label{tab:1}

Seen in table ref{tab:1}, Lorem ipsum dolor sit amet, 
consectetur adipisicing elit, sed do eiusmo

# References

Конвертируем в формат LaTeX:

pandoc --filter panflute --natbib --variable --biblio-style=./styles/american-chemical-society.csl --bibliography=paper.bib -s paper.md -t latex > paper.tex

Стили библиографических ссылок доступны в репозитории Zotero ^[19]. Программа Panflute ^[20] отвечает за обработку библиографии. Различные варианты тонкой доводки описаны в статье How to write academic papers in Markdown ^[21]. Я удовлетворился простой проверкой работы конвейера Markdown -> LaTeX -> PDF, и полагаю, что при желании вполне можно сделать свой аналог Authorea ^[13]. Скажем, на фреймворке bangle.dev ^[22] реализовать WYSIWYG онлайн-редактор Markdown со специфическим набором расширений, а экспорт препринтов доверить Pandoc ^[18] и товарищам.

Взглянуть бы на современный отечественный журнал, что принимает статьи в Markdown, не придираясь с мелочной дотошностью: нам пожалуйста файлом MS WORD, Times New Roman 14 пунктов, ссылки оформить согласно ГОСТ. С удобным интерфейсом загрузки манускрипта, данных, иллюстраций... Мечты.

Вывод. К настоящему моменту нет простого решения для решившегося писать в Markdown научную статью, а тем более диплом или диссертацию. Наполнить содержанием - более менее легко (попробуйте упомянутые редакторы Typora ^[16] и StackEditPro ^[17]), а дальше... поскольку журналы принимают сугубо LaTeX (или Word) манускрипт оформленный под определенный стандарт... дальше - сложности. Настройка конвертации Pandoc -> LaTeX, возможно, что также понадобится разбираться с Citation Style Language ^[23], затем неизбежное составление преамбулы LaTeX, доводка руками - расположение плавающих объектов, неразрывные пробелы, специфические поля, шрифт...

Контент блога

Разметка Markdown прекрасно подходит для статических генераторов сайтов ^[24]. Вы переносите текст, иллюстрации и математику из статей в свой блог. Лучше один раз увидеть - вот образец ^[25] того, что достижимо. Wowchemy ^[26] - конструктор веб сайтов на фреймворке Hugo ^[27]. Понравилось? Вы или ваша исследовательская группа решили завести такой сайт? Расскажу вкратце о том, какие есть подводные камни.

1. Нужен аккаунт на GitHub ^[28] и некоторое понимание принципов работы с репозиториями кода ^[29].

2. Помимо разметки Markdown, активно используется разметка YAML ^[30].

Это совсем не сложно. YAML-разметку я уже приводил в макете статьи с Pandoc. Вот так она выглядит:

---
title: "Pizza - A Carbohydrate Based Substrate For Tomato Delivery"
date: "Apr 2021"
author: "Sergei Malykhin, Pizza Enthusiasts Institute"
---

Считайте, что YAML - ближайший родственник Markdown. Еще одна читаемая разметка. По-моему, даже новичку в IT вполне по силам. Так выглядит описание страницы блога ^[31]:

---
title: Slides
summary: An introduction to using Wowchemy's Slides feature.
authors: []
tags: []
categories: []
date: "2019-02-05T00:00:00Z"
slides:
  # Choose a theme from https://github.com/hakimel/reveal.js#theming
  theme: black
  # Choose a code highlighting style (if highlighting enabled in `params.toml`)
  #   Light style: github. Dark style: dracula (default).
  highlight_style: dracula
---

# Create slides in Markdown with Wowchemy

[Wowchemy](https://wowchemy.com/) | [Documentation](https://owchemy.com/docs/managing-content/#create-slides)

---

## Features

- Efficiently write slides in Markdown
- 3-in-1: Create, Present, and Publish your slides
- Supports speaker notes
- Mobile friendly slides

Презентации в Markdown

Последний пример показывает как делаются презентации с помощью Markdown. В нём мы разбиваем текст на слайды с помощью символов ---. Pandoc позволяет конвертировать их в адаптированный под пакет beamer ^[32] LaTeX. Далее тот компилируется в PDF файл презентации.

pandoc --to=beamer --output=out.pdf test.md

Pandoc в качестве разделителя слайдов использует строки # Название слайда:

---
author: Sergei Malykhin
title: Awesome Markdown Presentation!
institute: Habr
theme: Berlin
---

# Slide 1
This is my first slide

# Slide 2

$a^2 + b^2 = c^2$

Другая возможность делать слайды - программа Marp ^[33]. Она доступна как плагин к IDE Visual Studio Code ^[34]. Очень хорошо подходит тем, кто делает презентацию используя фрагменты из кода и документации к своей программе.

Вы просто включаете в шапке Markdown текста строки

---
marp: true
---

И получаете окно с предварительным просмотром презентации.

Документация

Markdown словно создан для документирования программ, однако, жизнь усложняется тем, что единых стандартов нет. Например, я использую Documenter.jl ^[35] для генерации документации к своему пакету на языке Julia ^[36]. А в нем соглашение следующее:

Here's some inline maths: ``sqrt[n]{1 + x + x^2 + ldots}``.

Вместо $sqrt[n]{1 + x + x^2 + ldots}$ тут апострофы! Ничего не поделаешь, приходится писать свой фильтр из одного синтаксиса в другой.

#!/bin/bash
#=
exec julia -O0 --compile=min "${BASH_SOURCE[0]}" "$@"
=#

using ArgParse

function doc2latex(mdfile)
	formula = false
  for line in eachline(mdfile)
    if      formula && occursin("```", line)
      s = replace(line, r"```" => s"$$")
      formula = false
    elseif !formula && occursin("```math", line)
      s = replace(line, r"```math" => s"$$")
      formula = true
    else
      # replace `` -> $
      s = replace(line, r"(?<=[^`])``(?=[^`])|^``(?=[^`])|(?<=[^`])``$" => s"$")
    end
    println(s)
	end
end

function latex2doc(mdfile)
	formula = false
  for line in eachline(mdfile)
    if      formula && occursin(r"$$", line)
      s = replace(line, r"$$" => s"```")
      formula = false
    elseif !formula && occursin(r"$$", line)
      s = replace(line, r"$$" => s"```math")
      formula = true
    else
      # replace $ -> ``
      s = replace(line, r"(?<=[^$])$(?=[^$])|^$(?=[^$])|(?<=[^$])$$" => s"``")
    end
    println(s)
	end
end

function parse_commandline(args)
    s = ArgParseSettings()
    add_arg_group!(s, "Mutually exclusive options", exclusive=true, required=true)
    @add_arg_table! s begin
        "--to-latex", "-l"
            help = "convert math formulae from Documenter.jl ``E=mc^2`` to LaTeX $E=mc^2$ format"
            action = :store_true
        "--to-documenter", "-d"
            help = "convert math formulae from LaTeX $E=mc^2$ to Documenter.jl ``E=mc^2`` format"
            action = :store_true    
    end
    add_arg_group!(s, "Required arguments", required=true)
    @add_arg_table! s begin
        "input"
            help = "Markdown text file"
            required = true
    end
    return parse_args(args,s)
end

function main(args)
  parsed_args = parse_commandline(args)
  isnothing(parsed_args) && return
  try
    f = open(parsed_args["input"], "r")
    if     parsed_args["to-latex"]
      doc2latex(f)
    elseif parsed_args["to-documenter"]
      latex2doc(f)
    end
  catch
    println("file $(parsed_args["input"]) doesn't exist.")
  end
end

main(ARGS)

Я не единственный, кто столкнулся с этой проблемой, универсального решения не нашёл. Больше на эту тему рассказано в посте Статьи — это тоже исходный код { ^[37]

Возможности, которых еще нет, но хотелось бы

Химикам приходится постоянно иметь дело со структурными формулами. Для них тоже есть подходящий для чтения и машинной обработки формат, но нет фильтра для преобразования его в изображения. Речь идёт о SMILES ^[38] (Simplified Molecular Input Line Entry System — «система упрощённого представления молекул в строке ввода»). Например, афлавотоксин ^[39] B₁

Представляется строкой SMILES: O1C=C[C@H]([C@H]1O2)c3c2cc(OC)c4c3OC(=O)C5=C4CCC(=O)5.

Почему бы ему не быть отрисованым WYSIWYG редактором Markdown? Программа OpenBabel ^[40] это умеет делать на лету. Кроме структур, полезно иметь возможность включать небольшие графики, 3D структуры молекул, как это делается встраиванием плагина JsMol ^[41].

Словом, еще есть куда развиваться. Имеется JavaScript библиотека ChemDoodle Web Components ^[42], её бы соединить с Typora - все химики будут ваши.

Заключение

Идеи, заложенные в разметку Markdown, несмотря на кажущуюся простоту и очевидность, (давайте сделаем разметку удобной человеку) несут в себе большой потенциал. Вместо утомительной работы по перегонке информации из переписки в статьи, со статей в презентации, с них в книги и документацию к программам, мы получим много свободного времени для творческой работы. Уже сейчас совместная работа и подготовка слайдов достаточно удобны. В будущем, как мне хочется надеяться, оформление публикаций перестанет быть вавилонским столпотворением и вместо настройки пакетов LaTeX, составления библиографических стилей bibtex, оформления и компоновки таблиц и рисунков мы будем иметь задачу только ясно изложить свою мысль.

Наши серверы ^[43] можно использовать для разработки и просчета научных экспериментов.

Зарегистрируйтесь по ссылке выше или кликнув на баннер и получите 10% скидку на первый месяц аренды сервера любой конфигурации!

Автор: Малыхин Сергей

Источник ^[44]