7.1. Языки разметки

Как известно, большинство программистов не любит писать документацию к своим проектам. На это есть причины. В частности, документацию трудно поддерживать в актуальном состоянии в процессе разработки программы. Кроме того, традиционный подход к ведению технической документации с использованием редакторов в духе Microsoft Word с точки зрения разработчика сильно отличается от процессов ведения программного проекта.

В связи с вышесказанным перспективным является подход «документация как код» (docs as code), основная идея которого в использовании для создания технической документации тех же процессов, что и для разработки программ. Подход «документация как код» отличается следующими особенностями:

Использование текстовых языков разметки, удобных как для чтения человеком, так и с точки зрения машинной обработки;
Использование текстовых языков описания графических материалов;
Использование системы контроля версий для хранения проекта документации;
Использование инструментов командной строки для автоматической проверки, сборки документации и непрерывной интеграции (continuous integration);
Ориентация на выходной web-формат.

Языки разметки, помимо очевидной возможности написания текстов, поддерживают специальные команды, отвечающие за внешний вид и структурные особенности документа. В отличие от обычных WYSIWYG-редакторов («что вижу на экране, то и получу в документе»), язык разметки позволяет документ «запрограммировать», при этом «программа» на языке разметки и ее результат в виде документа отличаются друг от друга.

Очевидным примером языка разметки является HTML, но для задач составления документации было создано множество специальных языков, в частности:

LaTeX;
Markdown;
reStructuredText;
AsciiDoc.

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

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

7.1.1. TeX и LaTeX

Один из древнейших и, пожалуй, самый мощный язык разметки – TeX, который используется в одноименной системе компьютерной верстки. TeX был разработан Д. Кнутом в 1978 году для задач написания литературы в области компьютерных наук. В 1984 году Л. Лэмпорт создал набор макрорасширений для TeX под названием LaTeX. Сегодня LaTeX используется для написания статей в журналах по математике и физике, создания технических книг, дипломов и диссертаций.

LaTeX отличают средства автоматизации создания документов, это касается, в частности, построения списка литературы, нумерации элементов и ссылок на них, оптимизации размещения элементов на страницах и описания математических формул.

Ниже представлен пример простого документа в LaTeX:

\documentclass[14pt]{article} % Формат страниц
\usepackage{polyglossia} % Поддержка русского языка
\setmainlanguage{russian}
\setmainfont{Times New Roman} % Настройка шрифта

\title{Тестовый документ} % Заголовок
\author{П.Н. Советов} % Автор
\date{\today} % Дата создания
   
\begin{document} % Тело документа

\maketitle % Вставка заголовка
     
Это простой \textbf{пример} документа в \LaTeX.

\end{document}

Можно заметить, что команды в LaTeX предваряются символом \ и могут иметь аргументы, заключенные в скобки различных форм.

Результат компиляции документа с помощью xelatex показан на рис. 37.

Рисунок 37. Результат компиляции LaTeX-документа

Особый интерес представляет использующийся в LaTeX язык разметки математических формул. Формулы обрамляются символами $ (встраивание в текст) или $$ (в отдельной строке). Примеры простых формул представлены ниже:

$$
a^n + b^n = c^n
$$

$$
x_{1,2}=\frac{-b \pm \sqrt {b^2-4ac}}{2a}
$$

$$
f(x) = \frac{1}{\sigma \sqrt{2\pi} }
    e^{-\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2}
$$

$$
\eta(T|a)= \sum_{v\in vals(a)} {\frac{|S_a{(v)}|}{|T|}
    \cdot \eta\left(S_a{\left(v\right)}\right)}
$$

Результат компиляции формул представлен на рис. 38.

Знакомство с языком описания формул LaTeX очень полезно, поскольку этот язык или его подмножества используются во многих современных системах, например, в языке разметки Wikipedia.

7.1.2. Грамотное программирование

Как уже говорилось выше, особенную проблему представляет разделенность программного кода и документации на программный проект. Ранней попыткой решить указанную проблему является подход «грамотного программирования» (literate programming) Д. Кнута в виде системы WEB, созданной в 1984 году. WEB основана на системе TeX и позволяет вести документацию с внедренным в нее программным кодом.

С помощью инструмента weave из WEB-файла извлекается только часть, связанная с документацией. С помощью инструмента tangle из WEB-файла извлекается программный код. Схема работы WEB показана на рис. 39.

На рис. 40 показан пример LaTeX-документа, извлеченного из WEB-файла.

Из приведенного WEB-документа может быть извлечен также следующий код:

def insert(tree, key):
    if not tree:
        tree = Node(key)
    elif key < tree.key:
        tree = Node(tree.key, insert(tree.left, key), tree.right)
    elif key > tree.key:
        tree = Node(tree.key, tree.left, insert(tree.right, key))
    return tree

В какой-то мере черты грамотного программирования унаследовала система Jupyter-блокнотов, в которой документы представлены в виде последовательности ячеек. Ячейка может либо содержать программный код, либо – документацию. Jupyter-блокноты используются, в основном, в области научно-технических расчетов и для анализа данных.

7.1.3. Markdown и Pandoc

Одним из простейших языков разметки является Markdown. Его авторы преследовали цель получения незаметного командного языка, чтобы файлы на Markdown было легко читать, как есть, даже без трансляции в какое-то выходное представление.

Ниже показаны примеры элементов синтаксиса Markdown:

# Заголовок 1
## Заголовок 2
## Заголовок 3

Параграф с текстом и [ссылкой](https://pandoc.org/).

Параграф с текстом, выделенным **жирным** и *курсивом*.

> Важная цитата (Автор)

Список элементов:

1. Первый.
1. Второй.
    * Вложенный первый.
    * Вложенный второй.
1. Третий.

| Поле 1      | Поле 2      |
| ----------- | ----------- |
| Данные 1    | Данные 3    |
| Данные 2    | Данные 4    |

```python
{
  "name": "Ivan",
  "last_name": "Drago",
  "age": 25
}
```

Markdown, в силу простоты и читаемости своего синтаксиса, представляет собой возможную альтернативу LaTeX. Однако, при использовании более-менее сложного форматирования документов возможностей Markdown быстро перестанет хватать. В этой ситуации может помочь инструмент Pandoc [46], предназначенный для трансляции документов из одного представления в другое. Особенность Pandoc в том, что в нем поддерживается расширенный вариант Markdown, который, в свою очередь, можно дополнить рядом сторонних модулей.

Архитектура Pandoc показана на рис. 41. Работу Pandoc можно разбить на три этапа:

Одно из входных представлений с помощью поддерживаемых трансляторов для чтения (readers) преобразуется во внутреннее представление Pandoc – дерево абстрактного синтаксиса.
На уровне AST могут бы применены пользовательские фильтры (filters).
Полученное AST с помощью поддерживаемых трансляторов для записи (writers) преобразуется в одно из выходных представлений.

В варианте markdown от Pandoс поддерживаются некоторые элементы LaTeX, в частности, язык описания математических формул.

Keyboard shortcuts

Конфигурационное управление. Курс в РТУ МИРЭА