Pull to refresh

Концепция включений в markvan-разметке текстов

Level of difficultyEasy
Reading time5 min
Views1.8K

Настоящие знания остаются полезными гораздо дольше их носителей. Вопрос о том, как лучше хранить полезную информацию в электронном виде, всё ещё открыт.

Многие знакомы с markdown-разметкой, которая позволяет подготавливать небольшие простые тексты для последующей конвертации в html. Теперь появился аналогичный инструмент разметки — markvan, предназначенный для написания полноразмерных литературных и технических текстов.

Приглашаю познакомиться со стандартом и поучаствовать в его разработке.

Как возникла идея

В эпоху стремительного, даже безумного, развития информационных технологий, требующих применения всё большого количества языков, стандартов, фреймворков и подходов, иногда хочется чего-то простого… более надёжного и понятного. Хочется долговечного, не зависящего от популярных в настоящее время программ. Txt, doc, docx, gdoc, rtf, odt и т.д., ну вы поняли.

Другая причина — практические неудобства при подготовке публикаций для интернета. Html возможно хорош для машин, но обычному человеку сложно. Теги "лезут в глаза" и не дают сосредоточиться на содержимом. Поэтому текст сначала готовится в визуальном редакторе, а потом экспортируется, с сопутствующим "мусором" и не всегда ожидаемым результатом.

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

Описание задачи

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

Сразу было поставлено жёсткое ограничение: разметка не включает в себя оформительские инструменты, а передаёт только смысловые акценты и структуру текста. Кроме того, разметка должна помогать человеку сфокусироваться на той части текста с которой он работает, не мешая восприятию.

О проекте

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

Довольно быстро получилось придумать основу новой системы разметки текстов, которая почти меня устраивала. В ней удалось достичь некоей системности и согласованности. Оставил идею годик отлежаться и вернулся к ней только на этих новогодних каникулах. Разметку удалось проработать процентов на 70-80 и теперь хотелось бы ею поделиться, чтобы двигаться дальше. Разметка называется Маркван, ознакомиться с ней можно на сайте markvan.mudrium.ru, там же есть ссылка на телеграм-канал для обсуждений.

Немного о разметке

Базовая маркван-разметка выглядит довольно ожидаемо. Для заголовков используется несколько символов образующих линию, например, привычные всем знаки равно и минус. Однако, помимо текстовых заголовков, добавляется возможность разметить части и главы произведения. Выделение жирным привычно двумя звёздочками и т.п. Вот пример простой маркван-разметки:

***
Мой первый рассказ



"""
Глава I
Неизвестная планета


===
Удачная находка

Прежде, чем начать своё повествование, расскажу вам весьма интересную, но **жуткую** историю про переселенцев в Калахари.

Название стоит особняком - оно выделяется звёздочками, что интуитивно пересекается с выделением жирным. Далее части и главы выделяются вертикально направленными чёрточками ^^^ и """, текстовые заголовки обозначаются горизонтальными ===, ---, ..., а меньшие подзаголовки используются реже и не стоят упоминания.

Сноски и ссылки

Отдавая дань традициям, маркван-разметка позволяет размечать сноски, как звёздочками, так и цифрами.

Некий текст со звёздочковой[***] и цифровой[*5] сносками.
|*** Вот текст сноски, его можно разместить где угодно.
|*5 При конвертации останется только цифра.

И по аналогии создаются ссылки.

А это текст со ~[ссылкой]~, адрес которой должен находиться в следующей строке.
|~ example.com (Пример гиперссылки)

Всё просто, но к этой простоте не так легко было прийти. Ещё больше вы оцените это, когда заметите очередную переемственность подобного обозначения.

Включения

Очень часто текст включает в себя дополнительную информацию. Это могут быть справочные данные, иллюстрации, таблицы, примеры кода, формулы, рабочие комментарии автора и т.п.

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

Вот, чтобы получить такой результат:

Достаточно ввести такой текст

[[ Схема строения сердца
>Схема сердца.jpg
]] 1. Левая общая сонная артерия. 2. Левая аортная подключичная артерия. 3. Аорта. 4. Левые лёгочные артерии. и т.д.

Вариации включений

Включения бывают нескольких типов:
[( ... )] текстовый блок;
[= ... =] преформатированный текст;
[& ... &] программный код;
[% ... %] формулы;
[| ... |] таблицы;
[/ ... /] комментарии;
[[ ... ]] медиа-включение;

Для включения можно указать класс, идентификатор, название включения, и его описание.

[(class #id Name
Тело включения
)] Description

Причём, ряд классов уже зарезервирован и имеет знаковый синоним для короткого написания, например, !! — warning

А ещё текстовые включения могут содержать в себе другие включения:

[(i Это интересно!
Когда Верроккьо получил заказ на картину, на которой надлежало изобразить двух ангелов, одного он нарисовал сам, а рисование второго поручил своему юному ученику. Когда да Винчи справился с работой лучше него, Верроккьо был так потрясён его талантом, что навсегда завязал с живописью, заявив, что своего ученика ему никогда не превзойти.
[[
>davinci.jpg (Фото Леонардо да Винчи)
]]
)]

Строковые включения

Строковые включения

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

Пример однострочного условия &[rez = a + b if a < b else a - b]& в языке программирования python.

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

Работа продолжается

Мне кажется, такой подход к разметке включений достаточно оригинальным и удобным. И глазу легко выхватить включение из повествования, и парсить несложно. Неплохо уместились класс, идентификатор, название и описание, не мешая самому тексту включения и не требуя избыточных разметочных символов, просто находясь на положенных местах.
Конечно, остался ещё ряд вопросов, которые нужно "обкатывать" на практике, например, сделать для видео и аудио отдельный тип включения, чтобы не усложнять логику обработки изображений. Также есть вариации по ряду других моментов в разметке. Для становления стандарта нужно чтобы его начало использовать некоторое количество людей.

Маркван-сайт

Побочным продуктом размышлений стал маркван-сайт. Я подумал, вот у меня html, но теперь нужно его копировать и куда-то вставлять. А нельзя ли сделать так, чтобы сайт получался сам собой? Ведь что такое сайт в традиционном его понимании — это просто несколько страничек плюс навигация по ним. Отдельно можно приложить шаблон, стили, яваскрипт. Ну и попробовал — опять получилось.

Понятно, что это прототип с самым минимальным функционалом. По меньшей мере, ещё нужно разобраться с обработкой списков публикаций, сделать альтернативный способ формирования навигации и т.д. Но результат уже есть и он радует.

Кстати, сам сайт о маркван-разметке сформирован по этой технологии. Изначально были созданы текстовые файлы и разложены по папкам. Не делалось никаких описей структуры и какой-либо другой подобной работы. Чтобы создать сайт, потребовалось нажать 3 кнопки: выбор источника, выбор места сохранения и старт. Для обычного пользователя не нужно устанавливать на компьютер питон, не нужно идти в командную строку и что-то там колдовать, не нужно вникать в yaml или что-то подобное. Пусть это довольно ограниченный по возможностям способ создания сайта, но как по мне, способ довольно простой и изящный в своей простоте.


Хотелось бы ознакомиться с какими-нибудь советами (не в духе мемов про единый стандарт или критики нового). Хочется чего-то конструктивного типа: а вот этот тег будет сложно парсить, т.к. он может слиться с применяемым математиками способом записи факториала. Либо получить совет по оптимизации символов разметки. А ещё помогла бы консультация любого хоть немного разбирающегося в программировании разработчика, т.к. я просто гуглю очередной шаг, не имея целостного опыта в создании программ. Надеюсь кто-то реально захочет сделать себе такой сайт и даст обратную связь, а у меня будет стимул доработать конвертер.

Tags:
Hubs:
Total votes 8: ↑8 and ↓0+8
Comments92

Articles