Markdown в науке
С распространением персональных компьютеров научные статьи, а также книги, методические пособия и учебники, обрели новый носитель. Осталась в прошлом печатная машинка и текст с отступами, куда впоследствии аккуратно вставлялись формулы и рисунки от руки. Математические формулы с появлением TeX набирают обычным текстом. Сейчас TeX уже не просто программа верстки, а способ записи формул. Даже если Вам не довелось с ним работать, а подготовка документа ассоциируется с Word, удобным и быстрым способом ввода формулы в Word служат те самые команды из TeX.
Печатная машинка и формулы от руки. Оставшийся в прошлом способ писать свои труды.Интернет и эпоха Web 2.0 существенно изменили метод подготовки научных публикаций. Сейчас мы читаем статьи с экранов компьютеров, смартфонов и электронных книг, а не только с бумаги. Крайне желательно, чтобы работа над текстом по превращению журнальной статьи в энциклопедическую вики-справку, в презентацию, или же в содержимое сайта, не требовала чрезмерных усилий. Далее мы рассмотрим решение означенной проблемы с помощью текстовой разметки Markdown и попробуем представить себе дальнейшее развитие технологий.
В чём особенность Markdown-разметки? Почему бы не использовать LaTeX?
Краткий ответ: документ Word это doc/docx файл, он открывается с помощью Word, *.tex файлу нужен LaTeX, *.pdf требует для просмотра Acrobat Reader или схожей по функционалу программы. Текст Markdown — это просто текст. Читать и редактировать его чем-то особенным не обязательно.
Хорошо, но это же свойство есть и у файлов LaTeX? Да, но… Сравните:
\begin{document}
\title{Разметка \LaTeX}
\maketitle
\section{Введение}
Здесь мы рассмотрим несколько проблем.
\begin{enumerate}
\item Разметка предназначена для человека или машины?
\item Нужны ли \emph{особые} инструменты и какие?
\end{enumerate}
\end{document}# Разметка Markdown
## Введение
Здесь мы рассмотрим несколько проблем.
* Разметка предназначена для человека или машины?
* Нужны ли _особые_ инструменты и какие?Кого не отпугнул LaTeX «программированием» и логической (а не визуальной) разметкой, тот всё еще потратит немало сил на борьбу с ним. Цикл «внес изменения — скомпилировал, прочёл — внёс изменения» не самый продуктивный способ работы с текстом. Да и не все способны к отрисовке формул TeX в голове!
Да простят мне эту инвективу поклонники LaTeX«а, хоть и задумано, что Вам не нужно думать об оформлении, только о содержании, остальное возьмет на себя LaTeX… но, будем честны, это не всегда так! Кто верстал диссертацию или автореферат под вкусы конкретного диссертационного совета, а вкусы у них бывают очень специфичны, тот поймет. Вот одна хорошая инструкция, как писать диплом в LaTeX — Как я написал диплом по химии с (Xe)LaTeX. Под катом мой опыт — посмотрите и оцените сложность задачи для себя.
Преамбула для удовлетворения вкусов какого-то диссовета% Математические символы и шрифты
\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}
% нужно явно указывать шрифт под каждый язык
\newfontfamily\russianfont{Times New Roman}
\usepackage{wrapfig}
\usepackage{fancybox}
\usepackage{calc}
\usepackage{type1cm}
\renewcommand\normalsize{%
\@setfontsize\normalsize{9pt}{10.8pt}
\abovedisplayskip 10\p@ \@plus2\p@ \@minus5\p@
\abovedisplayshortskip \z@ \@plus3\p@
\belowdisplayshortskip 6\p@ \@plus3\p@ \@minus3\p@
\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}}
\frenchspacingLaTeX великолепен в сложных задачах, требующих безупречной верстки. Пусть местами умозаключения еще сырые, но ничто не сравнится с тем чувством, когда идеальные колонки текста обтекают формулы, а таблицы и иллюстрации дышат гармонией. С первого взгляда становится ясно — серьезная статья. Выглядит умно и строго. Мотивирует.
Подружить TeX-разметку с вебом, сделать правку независимой от огромного набора пакетов и самой программы LaTeX, тем не менее, совсем непросто.
Почти WYSIWYG таблицы в LyX.С помощью таких инструментов как LyX отчасти удаётся преодолеть порог вхождения. Как ни отрицай, но делать таблицы и сложные формулы проще WYSIWYG (визуально) и LyX тут очень хорошо помогает. Однако, LyX работает поверх LaTeX, тот поверх TeX и вся эта система подчас громоздка.
AuthoreaЕсть и другие решения. Например, Authorea или Overleaf. Они хорошо подходят для коллектива авторов желающих совместно написать академическую статью. Для многих журналов уже созданы готовые шаблоны и всё, что остается — наполнить форму содержанием. Тем не менее, недостаток WYSIWYG форматирования и упомянутая заточенность только на журналы остаётся камнем преткновения.
Желаемое
Хочется простой, всем и всеми читаемый текст, чтобы применяя к нему автоматизированные фильтры получать:
пригодную к отправке в журнал статью (препринт),
контент блога,
слайды презентации,
техническую документацию.
Препринт
Начнём с первого пункта. Есть множество редакторов Markdown удобных для коллективной и индивидуальной работы. У себя дома я предпочитаю Typora, а всем вместе можно воспользоваться StackEditPro. Выбор редакторов широк и здесь проблемы нет. Макет сделаем с использованием расширенного синтаксиса Markdown, который реализован в конвертере Pandoc.
Макет статьи с использованием расширений Pandoc: paper.md---
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
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. Программа Panflute отвечает за обработку библиографии. Различные варианты тонкой доводки описаны в статье How to write academic papers in Markdown. Я удовлетворился простой проверкой работы конвейера Markdown → LaTeX → PDF, и полагаю, что при желании вполне можно сделать свой аналог Authorea. Скажем, на фреймворке bangle.dev реализовать WYSIWYG онлайн-редактор Markdown со специфическим набором расширений, а экспорт препринтов доверить Pandoc и товарищам.
Взглянуть бы на современный отечественный журнал, что принимает статьи в Markdown, не придираясь с мелочной дотошностью: нам пожалуйста файлом MS WORD, Times New Roman 14 пунктов, ссылки оформить согласно ГОСТ. С удобным интерфейсом загрузки манускрипта, данных, иллюстраций… Мечты.
Вывод. К настоящему моменту нет простого решения для решившегося писать в Markdown научную статью, а тем более диплом или диссертацию. Наполнить содержанием — более менее легко (попробуйте упомянутые редакторы Typora и StackEditPro), а дальше… поскольку журналы принимают сугубо LaTeX (или Word) манускрипт оформленный под определенный стандарт… дальше — сложности. Настройка конвертации Pandoc → LaTeX, возможно, что также понадобится разбираться с Citation Style Language, затем неизбежное составление преамбулы LaTeX, доводка руками — расположение плавающих объектов, неразрывные пробелы, специфические поля, шрифт…
Контент блога
Разметка Markdown прекрасно подходит для статических генераторов сайтов. Вы переносите текст, иллюстрации и математику из статей в свой блог. Лучше один раз увидеть — вот образец того, что достижимо. Wowchemy — конструктор веб сайтов на фреймворке Hugo. Понравилось? Вы или ваша исследовательская группа решили завести такой сайт? Расскажу вкратце о том, какие есть подводные камни.
Нужен аккаунт на GitHub и некоторое понимание принципов работы с репозиториями кода.
Помимо разметки Markdown, активно используется разметка YAML.
Это совсем не сложно. YAML-разметку я уже приводил в макете статьи с Pandoc. Вот так она выглядит:
---
title: "Pizza - A Carbohydrate Based Substrate For Tomato Delivery"
date: "Apr 2021"
author: "Sergei Malykhin, Pizza Enthusiasts Institute"
---Считайте, что YAML — ближайший родственник Markdown. Еще одна читаемая разметка. По-моему, даже новичку в IT вполне по силам. Так выглядит описание страницы блога:
---
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 LaTeX. Далее тот компилируется в PDF файл презентации.
pandoc --to=beamer --output=out.pdf test.mdPandoc в качестве разделителя слайдов использует строки # Название слайда:
---
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. Она доступна как плагин к IDE Visual Studio Code. Очень хорошо подходит тем, кто делает презентацию используя фрагменты из кода и документации к своей программе.
Вы просто включаете в шапке Markdown текста строки
---
marp: true
---И получаете окно с предварительным просмотром презентации.
Презентация в Visual Studio Code.Документация
Markdown словно создан для документирования программ, однако, жизнь усложняется тем, что единых стандартов нет. Например, я использую Documenter.jl для генерации документации к своему пакету на языке Julia. А в нем соглашение следующее:
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)
Я не единственный, кто столкнулся с этой проблемой, универсального решения не нашёл. Больше на эту тему рассказано в посте Статьи — это тоже исходный код {
Возможности, которых еще нет, но хотелось бы
Химикам приходится постоянно иметь дело со структурными формулами. Для них тоже есть подходящий для чтения и машинной обработки формат, но нет фильтра для преобразования его в изображения. Речь идёт о SMILES (Simplified Molecular Input Line Entry System — «система упрощённого представления молекул в строке ввода»). Например, афлавотоксин B1
Представляется строкой SMILES: O1C=C[C@H]([C@H]1O2)c3c2cc(OC)c4c3OC(=O)C5=C4CCC(=O)5.
JsMol позволяет встраивать в веб-страницу интерактивную 3D структуру молекулы.Почему бы ему не быть отрисованым WYSIWYG редактором Markdown? Программа OpenBabel это умеет делать на лету. Кроме структур, полезно иметь возможность включать небольшие графики, 3D структуры молекул, как это делается встраиванием плагина JsMol.
Словом, еще есть куда развиваться. Имеется JavaScript библиотека ChemDoodle Web Components, её бы соединить с Typora — все химики будут ваши.
Интерактивные компоненты ChemDoodle.Заключение
Идеи, заложенные в разметку Markdown, несмотря на кажущуюся простоту и очевидность, (давайте сделаем разметку удобной человеку) несут в себе большой потенциал. Вместо утомительной работы по перегонке информации из переписки в статьи, со статей в презентации, с них в книги и документацию к программам, мы получим много свободного времени для творческой работы. Уже сейчас совместная работа и подготовка слайдов достаточно удобны. В будущем, как мне хочется надеяться, оформление публикаций перестанет быть вавилонским столпотворением и вместо настройки пакетов LaTeX, составления библиографических стилей bibtex, оформления и компоновки таблиц и рисунков мы будем иметь задачу только ясно изложить свою мысль.
Наши серверы можно использовать для разработки и просчета научных экспериментов.
Зарегистрируйтесь по ссылке выше или кликнув на баннер и получите 10% скидку на первый месяц аренды сервера любой конфигурации!
