Русский
Русский
English
Статистика
Реклама

Markdown

MarkedText маркдаун здорового человека

08.01.2021 12:15:36 | Автор: admin

Здравствуйте, меня зовут Дмитрий Карловский и все свои статьи (и презентации) пишу я в MarkDown разметке. И знаете что? Она уже порядочно меня подзаелозила! Тексты я пишу на русском, но большая часть спецсимволов есть только в английской раскладке клавиатуры. А редактирование таблиц - это вечная пизанская башня из вертикальных линий. Короче, есть у него проблемы как с удобством редактирования, так и с наглядностью представления. Так что давайте попробуем спроектировать его с нуля, не таща за собой килотонны головоломных конструкций.

Вёрстка несколько поехала, так как на Хабре выкатили новый кривой визивиг. Так что теперь писать статьи в маркдауне, а потом выкладывать на Хабр будет крайне сложно. С нормальной вёрсткой эту статью вы можете почить на гитхабе: https://github.com/nin-jin/HabHub/issues/39

Принципы

  • Однозначность синтаксиса

  • Простота синтаксиса

  • Единообразность синтаксиса

  • Минимальное влияние на естественный вид текста

  • Удобство редактирования независимо от раскладки

  • Наглядность представления

  • Расширяемость

  • Быстрая и надёжная запоминаемость

В качестве спец-символов форматирования лучше использовать такие, которые есть в любой раскладке, а не только в английской. То есть при прочих равных лучше отдать предпочтение следующим символам: ! " ; % : ? * ( ) _ + / \ . , - =

Существующие решения

В английской Википедии есть сравнительный обзор легковесных языков разметки, так что не будем повторяться. Там приведены следующие языки: AsciiDoc, BBCode, Creole, GitHub Flavored Markdown, Markdown, Markdown Extra, MediaWiki, MultiMarkdown, Org-mode, PmWiki, POD, reStructuredText, Textile, Texy, txt2tag.

Почти все они придерживаются примерно похожих конструкций. Однако, BBCode не является легковесным - это практически HTML с квадратными скобками вместо угловых. Поэтому его мы далее рассматривать не будем. Также проигнорируем и POD, чей синтаксис слишком многословный и не слишком наглядный.

Текстовые блоки

Блоки текста будем разделять двойным переводом строки, что даст визуальный отступ между блоками. Тип блока определяется специальным префиксом в начале каждой строки блока. Если префикс не распознан, то это обычный параграф.

Списки

Списки бывают двух типов: упорядоченные и неупорядоченные. Их можно вкладывать друг в друга в произвольной комбинации. В этом случае вложенные списки отображаются с отступом.

Элементы неупорядоченного списка предваряются маркером. По нормам многих языков таким маркером выступает тире. В вебе в основном потребляются "буллеты". В облегчённых языках разметки в основном используются следующие:

- item* item+ item

Из них лучше всего подходит на эту роль именно дефис - он выглядит похоже на тире и легко набирается с клавиатуры. Маркер и текст элемента списка отделяется пробелом. Таким образом суммарный отступ текста слева получается равным 2 - именно такой у нас будет отступ у вложенных списков, чтобы они были выровнены с текстом, к которому относятся. То есть останавливаемся на таком варианте:

- first- second  - first of second    - first of first of second  - second of second - third
  • first

  • second

    • first of second

      • first of first of second

    • second of second

  • third

Упорядоченные списки предполагают отображение увеличивающегося перед каждым элементом счётчика. Счётчик отделяется от текста элемента списка разделителем - точкой, скобочкой и тп. Некоторые языки предполагают ручное задание значений счётчика, что крайне не удобно поддерживать в актуальном состоянии:

1. item2) item

Некоторые языки позволяют указать специальный маркер списка, который будет отображаться как счётчик - это уже куда удобнее:

# item

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

+ first+ second  + first of second    + first of first of second  + second of second + third
  1. first

  2. second

    1. first of second

      1. first of first of second

    2. second of second

  3. third

Цитаты

Цитаты объединяют произвольные блоки текста, показывая, что их автором является кто-то другой. Распространённая практика - выделять цитаты угловыми скобками:

> quote> - list in quote> > inner quote

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

" quote" - list in quote" " inner quote

Таблицы

Таблицы - это двумерное представление данных. И многие языки стараются сохранять двумерность ради наглядности:

|=  |= table |= header || a | table  | row     || b | table  | row     ||   | table | header ||---|-------|--------|| a | table | row    || b | table | row    |First Header | Second Header------------ | -------------Content from cell 1 | Content from cell 2Content in the first column | Content in the second column

Однако, такое представление сильно бьёт по удобству редактирования - приходится вручную постоянно выравнивать колонки.

И ладно бы только это, но такое представление обладает крайне слабой выразительностью - в ячейку можно поместить лишь один параграф. Туда нельзя поместить несколько параграфов, список, преформатированный блок и тд.

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

|   | table                                                                                                                          | header || a | There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form, by injected humour, or randomised words which don't look even slightly believable.  | row     || b | table                                                                                                                          | row     |

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

!   ! table    ! header! a  ! There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form, by injected humour, or randomised words which don't look even slightly believable.    ! row! b  ! table     ! row

Таким образом человеку легко навигироваться по такой структуре как по горизонтали, так и по вертикали. А маркеры в виде восклицательных знаков похожи на вертикальные линии, но доступны не только в английской раскладке. Редактировать такое представление гораздо удобнее. Оно не боится внезапных переносов текста. А внутрь ячеек можно помещать любые другие блоки текста в произвольном количестве.

Заголовки

В некоторых языках заголовки выделяются разными типами подчёркиваний:

Level 1 Heading===============Level 2 Heading---------------Level 3 Heading~~~~~~~~~~~~~~~

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

Есть более удобная форма, где уровень заголовка определяется числом спецсимволов в префиксе:

# Level 1 Heading ### Level 2 Heading ##### Level 3 Heading ###

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

## Level 2 Heading== Level 2 Heading** Level 2 Heading!! Level 2 Heading++ Level 2 Heading

Решётка есть лишь в английской раскладке. Плюсы, звёздочки, восклицательные знаки мы задействуем для другой семантики. А вот массивные символы равенства - то, что надо. Заголовки делят текст на секции, так что пара горизонтальных линий отлично это иллюстрируют:

= Level 1 Heading== Level 2 Heading=== Level 3 Heading

Преформатированный текст

В некоторых языках для преформатированного текста используются специальные кавычки:

```markdownpreformatted         text```

Однако, если в таком тексте тоже нужно вывести эти кавычки, то получается облом. Поэтому предпочтительнее вариант с префиксом перед каждой строкой. Например, в качестве такого префикса может выступать отступ, равный 2 или 4 пробелам:

    preformatted             text

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

В преформатированном тексте важен каждый символ, поэтому внутри него не может быть никакого форматирования. Однако, часто в повествовательных целях необходимо выделить какие-то строки или пометить их удалёнными/добавленными.

Поэтому мы разделим префикс на две части:

  • Маркер преформатированного текста из 2 пробелов.

  • Маркер форматирования строки из пары спец символов.

Выглядеть оно будет так:

    preformatted            text  --deleted  --   text  ++inserted  ++    text  **highlighted  **       text

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

Инлайн форматирование

Типичный приём для добавления некоторым словам особого смысла - это окружить их специальными "кавычками". Такие кавычки должны достаточно редко встречаться в обычном тексте, чтобы не приходилось париться с экранированием, которое негативно сказывается на удобстве чтения. Как правило такие кавычки состоят из нескольких повторяющихся спец-символов. Рассмотрим варианты их числа:

  • 1 - слишком мало, высок риск, что символ обычного текста будет воспринят как форматирование.

  • 3 - слишком много, каждый раз трижды нажимать клавишу - слишком утомительно.

  • 2 - золотая середина, на этом и остановимся.

Акценты

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

Варианты сильного акцента:

*strong***strong**__strong__'''strong'''''strong''

Апострофы слишком похожи на кавычки и секунды, так что их сразу отбрасываем. Из оставшихся более распространён вариант с "массивными" звёздочкам - его и выберем.

**strong**

strong

Варианты слабого акцента:

'emphasis'''emphasis''_emphasis_/emphasis///emphasis//*emphasis*~emphasis~

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

//emphasis//

emphasis

Правки

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

Итак, типичные формы выделения добавлений:

_insertion___insertion__+insertion+

И удалений:

~deletion~~~deletion~~-deletion---deletion--

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

++insertion++--deletion--
  • insertion

  • deletion

Ссылки

Ссылки бывают двух видов:

  • Гиперссылка - она переносит вас к цели при клике на неё. Для неё задаётся отображаемое содержимое и урл для перехода.

  • Встраивание - цель встраивается в просматриваемый документ. Для него задаётся урл, откуда берётся встраиваемый документ, и альтернативное содержимое, если встраивание по какой-либо причине не произошло (не поддерживаемый формат, не разрешённый домен, не удалось подключиться и тд).

Гиперссылки выглядят в разных языках так:

"Text":http://example.comhttp://example.com[Text]<http: example.com|text="">[Text|http://example.com][[Text|http://example.com]][[http://example.com|Text]][Text http://example.com][http://example.com Text][Text](http://personeltest.ru/away/example.com)`Text <http: example.com="">`_

А встраивания так:

![title](http://personeltest.ru/away/example.com/image.png){{http://example.com/image.png|title}}.. image:: /path/to/image.jpg

Важно отметить, что обычно встраивать разрешено лишь изображения. Если хочется встроить видео или сайт - в лучшем случае предлагается писать HTML. Мы же позволим встраивать что угодно - проверка безопасности для урлов должна происходить системно и регулироваться отдельно. Язык разметки текста никак не должен их регламентировать.

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

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

""Embedded image\http://example.org/favicon.ico""""Embedded video\https://youtube.com/video=1234""""Embedded site\https://marked.hyoo.ru/""

Если альтернативное содержимое опущено, то в качестве него должен быть взят сам урл. То есть следующие два варианта дают идентичный результат:

""http://example.org/favicon.ico""""http://example.org/favicon.ico\http://example.org/favicon.ico""

Для гиперссылок же воспользуемся \ во всех местах:

\\Clickable text\http://example.org/\\Clickable url: \\http://example.org/\\

Разумеется разные типы ссылок можно комбинировать. Например, сделать картинку-ссылку можно так:

\\""Example\http://example.org/favicon.ico""\http://example.org/\\

Инлайн код

Инлайн код выводится моноширинным шрифтом и выключает внутри себя любое форматирование. В каждом языке используется что-то своё:

+monospace text+`monospace text```monospace text`````monospace text```|monospace text|{{monospace text}}{{{monospace text}}}=code=~verbatim~@monospace text@@@monospace text@@

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

This is  monospace text  !

This is monospace text !

Резюме

Теперь давайте соберём все конструкции формата в одной короткой шпаргалке:

= MarkedTextФормат текста с **легковесным форматированием**.--== Принципы+ Синтаксис:- Однозначность- Простота- Единообразность+ Внешний вид:- Минимальное влияние на естественный вид текста- Наглядность форматирования+ Редактирование:- Независимость от раскладки- Быстрая и надёжная запоминаемость== Cравнение с альтернативами! **Язык**! **Плюсы**    ! **Минусы**! MarkedText! - Удобное редактирование таблиц.! - Поддержка сложного форматирования внутри ячеек.! - Простота реализации.! - Легко запоминающийся консистентный синтаксис.! - Удобство редактирования в русской раскладке.! - Колонки не расползаются далеко вправо за горизонтальный скроллинг и не переносятся на новую строку.    ! - Не поддерживается пока что никакими сторонними инструментами.! MarkDown! - Широкая поддержка различными инструментами.! - Наглядное представление таблиц.    ! - Сложности с редактированием таблиц.    ! - Сильно ограниченное содержимое ячеек.== Парсинг    const res = [ ... $hyoo_marked_line.parse( '**text**' ) ]--$mol_assert_equal( res[0].strong, '**text**' )++$mol_assert_equal( res[0].marker, '**' )**$mol_assert_equal( res[0].content, 'text' )== Отзывы" " " Типичный пользователь: Нигде не поддерживается, идите в --жопу-- ++Жодино++ с таким синтаксисом!" " " " Но мы же программисты, мы можем это исправить.. Для этого даже не надо быть экспертом ни по  C++  , ни по  D++  .." " Никому это не нужно (с) Диванный ЭкспертТем не менее, это полезное упражнение в проектировании.== Ссылки- Песочница: \\https://marked.hyoo.ru/\\- \\Статья о MarkedText\https://github.com/nin-jin/HabHub/issues/39\\- \\Парсер на TS\https://github.com/hyoo-ru/marked.hyoo.ru/\\- \\Конвертер в HTML на TS\https://github.com/hyoo-ru/marked.hyoo.ru/tree/master/to/html\\- ""Результат билда $mol_regexp\https://github.com/hyoo-ru/mam_mol/workflows/mol_regexp/badge.svg""

Ссылки

Подробнее..

Из песочницы Trello начало работы и скрытые фишки

17.07.2020 16:20:19 | Автор: admin

Что такое Trello, и как оно работает?




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


P.S. если вы хоть раз открывали приложение trello листайте до основы работы.




Как начать работу


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


Теперь нам нужно добавить список, то, что я в дальнейшем буду называть колонкой. Нажимаем добавить, вводим название и тут начинается самое интересное, потому что сейчас мы перейдем к созданию карточек.


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


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


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




Основы работы


Давайте посмотрим направо и быстро изучим основные вещи, которые мы можем добавить на карточку.


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


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




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


Интересная модель: когда я готовился к ЕГЭ, и у меня было большое количество вебинаров, которое нужно было посмотреть, я просто создавал чек-лист с вебинарами и в строчки вносил ссылки на эти видео, а затем отмечал по мере просмотра.




Третья функция карточки это создание сроков. Мы можем задать срок выполнения той или иной задачи, записанной на карточке, и trello напомнит нам заблаговременно, что срок карточки скоро истекает и будет менять цвет маркера времени на карточке в зависимости от того, сколько времени осталось до намеченного срока. Также мы можем добавить календарь на всю доску, и у нас появится еще одна полезная функциональность доски.


Как это сделать:


  1. В правом верхнем углу доски нажимаем на кнопку меню.
  2. Далее, в открывшемся меню мы видим раздел Улучшения.
  3. Открываем этот раздел и вбиваем в поиск календарь, по-русски или по-английски в зависимости от версии приложения.
  4. Видим карточку calendar и нажимаем добавить.
  5. Готово, теперь на нашей доске есть календарь.

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




Четвертая штука это вложения, на них мы остановимся поподробнее. Для меня, человека, который из-за учебы работает с огромным количеством файлов, это одна из самых полезных функций карточки. В эти вложения можно очень просто добавлять картинки или файлы, перетащив их из папки на компьютере или телефоне на карточку (drag and drop).


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





Вот мои шаблоны, копируйте, пользуйтесь.












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




Шаблоны


В Trello существует огромное колличество шаблонов досок, и вам не обязательно каждый раз придумывать самому, как правильно расставить колонки, и как из лучше будет назвать их.
Для того, чтобы использовать шаблон нужно на самом первом экране нажать на кнопку шаблоны (слева), и далее выбрать нужный вам шаблон из того множества, которое там представлено. Когда вы определились с выбором шаблона, просто нажимаем добавить шаблон, и у вас появляется новая доска с этим шаблоном, которую вы далее можете настраивать под себя, как вам удобно.


P.S. я использую шаблон, который можно найти, вбив getting things done.




Синтаксис


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


В trello используется известный во всем мире способ синтаксиса markdown, и вот некоторые штуки, которые можно применять для оформления текста в карточке trello.




Заголовки


Если вам нужно выделять заголовки, ставим # (чем больше хэштегов перед заголовком, тем меньше будет шрифт заголовка).


Заголовок H1


Заголовок H2




Шрифты


Различные виды шрифтов (ставим служебные символы перед и после текста и при дальнейшем просмотре карточки шрифты будут различаться).



Курсив и Курсив
Жирный текст и Жирный текст
Жирный и курсивный текст




Выделение


Выделение части текста рамочкой другого оттенка, ставим (>) перед текстом и все красиво.


Очень глубокомысленная цитата. Пожалуйста, прочтите её внимательно.

Оскар Уайльд



Линии разделения


Линии разделения текста на абзацы и блоки, также если мы создадим новую карточку, добавим (---) в название карточки и больше ничего не будем писать, у нас появится пустая карточка\линия, которой можно делить карточки на блоки внутри колонки.


(***)
(___)




Зачеркнутый текст


Символ (~)
~~ зачеркнутый текст ~~
зачеркнутый текст




Как посчитать количество карточек?


Если на доске открыть меню и вбить в поиск карточек символ ($), то над каждым столбцом появится количество карточек в нем.




Заключение


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

Подробнее..

Перевод Единый математический язык для физики и инженерного искусства в 21 веке

15.02.2021 14:04:42 | Автор: admin

Введение

Сегодня, старшеклассников обучающихся по уровням А или их эквивалентам в естественных науках, познакомят с понятием векторов направленных отрезков прямых, и научат манипулировать ими с помощью классической векторной алгебры. Фактически это алгебра, введенная Гиббсом в конце 19-го века; с тех пор она мало изменилась. Ученики практикуются в искусстве векторной алгебры и видят, насколько успешно она выражает большую часть двумерной и трехмерной геометрии. Манипулирование системой становится почти второй натурой.

Уильям Роуэн Гамильтон 1805-1865. Изобретатель кватернионов и один из ключевых научных деятелей 19 векаУильям Роуэн Гамильтон 1805-1865. Изобретатель кватернионов и один из ключевых научных деятелей 19 века

Понятное дело, что будет трудно отказаться от этой знакомой и, по-видимому, успешной системы в пользу новой алгебры (геометрической алгебры (ГА)), которая имеет дополнительные правила и нетрадиционные понятия. Однако, за умеренные затраты времени и усилий, вложенные в изучение ГА, наградой будет возможность получить в свое распоряжение инструмент, который позволяет пользователю проникать даже в самые мощные области современных научных исследований. По мере того, как мы переходим в 21-й век, мы достигли стадии, когда исследования в области физических наук часто специализируются в одной, как правило, очень ограниченной области. Тем не менее, всегда было так, что большие преимущества могут быть получены из взаимодействия между различными областями, что становится все более трудным, но все более желательным. Мы предполагаем, что в новом тысячелетии толчок к междисциплинарной деятельности возрастет во много раз. В следующих разделах мы попытаемся дать читателю некоторые доказательства того, что ГА может быть лучшей надеждой на достижение цели унификации математического языка для современной науки.

Немного истории

Многих выдающихся математиков начала 19-го века занимал вопрос заключавшийся в том, как лучше всего математически представить вращения в трех измерениях, то есть в обычном пространстве. Гамильтон провел большую часть своей жизни, работая над этой проблемой, и в конце концов создал кватернионы, которые были обобщением комплексных чисел. Алгебра содержит четыре элемента и правило

\{ 1,\,\mathbf i,\,\mathbf j,\,\mathbf k \} \\ i^2 = j^2 = k^2 = \mathbf i\mathbf j\mathbf k = -1

Хотя элементы i, j, k часто называют векторами, позже мы увидим, что они не обладают свойствами векторов. Несмотря на очевидную полезность кватернионов, всегда существовала небольшая загадка и путаница в их природе и использовании. Сегодня кватернионы все еще используются для представления трехмерных вращений во многих областях, поскольку признано, что они являются очень эффективным способом выполнения таких операций. Однако путаница все еще сохраняется, и глубокое и детальное понимание кватернионов было потеряно для целого поколения.

Герман Гюнтер Грассман (1809-1877). Немецкий математик и школьный учитель, прославившийся алгеброй, которая теперь носит его имяГерман Гюнтер Грассман (1809-1877). Немецкий математик и школьный учитель, прославившийся алгеброй, которая теперь носит его имя

В то время как Гамильтон разрабатывал свою кватернионную алгебру, Грассман формулировал свою собственную алгебру, ключом к которой было введение внешнего произведения; мы обозначаем это внешнее произведение как , так что внешнее произведение двух векторов a и b записывается как a b. Это произведение имеет определенные особенности. Одной из таких особенностей является его ассоциативность, т. е.

\mathbf a \wedge (\mathbf b \wedge \mathbf c) = (\mathbf a \wedge \mathbf b) \wedge \mathbf c

То, как мы группируем множители, не имеет значения. Другая особенность антикоммутативность, то есть, если мы изменим порядок векторов во внешнем произведении, то изменим его знак:

\mathbf{a}\wedge\mathbf{b} = -\mathbf{b}\wedge\mathbf{a}

Мы больше привыкли иметь дело с коммутативным произведением, то есть умножением между двумя числами, 25 = 52 = 10, но оказывается чрезвычайно полезным во многих областях физики, математики и техники иметь произведение, которое не обязательно коммутирует. Напротив, внутреннее (скалярное) произведение между двумя векторами, a и b, записанное как a b (что дает скаляр, величина которого равна ab cos , где угол между векторами), является коммутативным, т. е.

\mathbf a \cdot \mathbf b = \mathbf b \cdot \mathbf a

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

 Портрет Уильяма Кингдона Клиффорда (1845-1879), математика и философа, работы достопочтенного Дж. Джон Кольер. (Библиотека и архив Королевского общества.) Портрет Уильяма Кингдона Клиффорда (1845-1879), математика и философа, работы достопочтенного Дж. Джон Кольер. (Библиотека и архив Королевского общества.)

Следующий решающий этап истории происходит в 1878 году и связан с работой английского математика Уильяма Кингдона Клиффорда. Клиффорд был одним из немногих математиков, которые читали и понимали работу Грассмана, и в попытке объединить алгебры Гамильтона и Грассмана в единую структуру он ввел свою собственную геометрическую алгебру. В этой алгебре мы имеем одно геометрическое произведение, образованное объединением внутреннего и внешнего произведений; оно ассоциативно, как произведение Грассмана, но также обратимо, как произведения в алгебре Гамильтона. В геометрической алгебре Клиффорда уравнение типа ab = C имеет решение b = aC, где a существует и известно как обратное от a. Ни внутреннее, ни внешнее произведение не обладают этой обратимостью сами по себе. Большая часть силы геометрической алгебры заключается в этом свойстве обратимости.

Алгебра Клиффорда объединила все преимущества кватернионов с преимуществами векторной геометрии, так что геометрическая алгебра должна была тогда идти вперед как основная система математической физики. Однако два события помешали этому. Первой была безвременная смерть Клиффорда в возрасте всего 34 лет, а второй введение Гиббсом своего векторного исчисления. Векторное исчисление хорошо подходило к теории электромагнетизма в том виде, в каком она существовала в конце XIX века; это, а также значительная репутация Гиббса, привели к тому, что его система затмила работу Клиффорда и Грассмана. Ирония заключается в том, что сам Гиббс, похоже, был убежден, что подход Грассмана к множественным алгебрам был правильным.

С появлением специальной теории относительности физики поняли, что им нужна система, способная обрабатывать четырехмерное пространство, но к этому времени важнейшие идеи Грассмана и Клиффорда уже давно затерялись в бумагах конца 19-го века. В 1920-х годах алгебра Клиффорда вновь появилась как алгебра, лежащая в основе квантового спина. В частности, алгебра спиновых матриц Паули и Дирака стала незаменимой в квантовой теории. Однако к ним относились просто как к алгебрам: геометрический смысл был утрачен. Соответственно, мы будем использовать термин "алгебры Клиффорда", когда он используется исключительно в формальной алгебре. Говоря же о геометрической постановке, мы используем название данное Клиффордом геометрическая алгебра. Это также уступка Грассману, который фактически первым записал геометрическое (клиффордовское) произведение!

Ситуация оставалась в значительной степени неизменной до 1960-х годов, когда Дэвид Хестенес начал восстанавливать геометрический смысл алгебр Паули и Дирака. Хотя его первоначальная мотивация состояла в том, чтобы получить некоторое представление о природе квантовой механики, он очень скоро понял, что при правильном применении система Клиффорда была не чем иным, как универсальным языком для математики, физики и инженерии. Опять же, эта замечательная работа в значительной степени игнорировалась около 20 лет, но сегодня интерес к системе Гестенеса набирает обороты. В настоящее время во всем мире существует множество групп, работающих над применением геометрической алгебры к таким различным темам, как черные дыры и космология, квантовое туннелирование и квантовая теория поля, динамика пучков и дефформации, компьютерное зрение и робототехника, свертывание белков, нейронные сети и автоматизированное проектирование. Во всем используется одна и та же алгебраическая система, позволяющая людям одновременно вносить вклад в ряд этих областей

Краткий обзор

В нашей геометрической алгебре мы начинаем со скаляров, то есть обычных чисел, которые имеют величину, но не связаны с ориентацией, и векторов, то есть направленных отрезков как с величиной, так и с ориентацией/направлением. Давайте теперь возьмем эти векторы и посмотрим немного более внимательно на геометрию, лежащую за внешним произведением Грассмана. Внешнее произведение между двумя векторами a и b записывается как a b и представляет собой новую величину, называемую бивектором. Бивектор a b это направленная область, охватываемая двумя векторами a и b; таким образом, внешнее произведение двух векторов является новой математической сущностью, кодирующей понятие ориентированной плоскости.

Если мы пронесем b вдоль а, то получим тот же бивектор, но с противоположным знаком (ориентацией). Теперь, расширяя эту идею, мы видим, что внешнее произведение между тремя векторами, a b с, получается путем выметания бивектора a b вдоль c, что дает ориентированный объем или тривектор. Если мы пронесем a через область, представленную бивектором b с, мы получим тот же самый тривектор (можно показать, что он имеет ту же самую "ориентацию"); этот факт выражает ассоциативность внешнего произведения.

В n-мерном пространстве у нас будут n-векторы, которые являются просто ориентированными n-объемами; таким образом, мы видим, что внешнее произведение легко обобщается на более высокие измерения, в отличие от векторного произведения Гиббса, которое ограничено тремя измерениями. Решающий шаг в развитии геометрической алгебры теперь происходит с введением геометрического произведения. Мы уже знаем, что такое a b и a b; геометрическое произведение же их объединяет:

\mathbf{ab} = \mathbf a \cdot \mathbf b + \mathbf a \wedge \mathbf b

Этот шаг суммирования двух различных объектов не является совершенно чуждым актом; на самом деле мы уже давно делаем то же самое при выполнении операций с комплексными числами. Оказывается, что многие величины в физике могут быть выражены очень сжато и эффективно в терминах мультивекторов (линейные комбинации n-векторов, например скаляр плюс бивектор и т. д.); действительно, такое объединение объектов разных типов, по-видимому, происходит на глубоком уровне физической теории.

Геометрическая алгебра в двух измерениях

В двух измерениях (на плоскости) любая точка может быть достигнута путем принятия различных линейных комбинаций двух векторов с различными направлениями; мы говорим, что пространство тогда охватывается этими двумя базисными векторами. Теперь пусть эти два вектора ортонормированы, т. е. единичной длины и перпендикулярные друг другу, и назовем их e и e. Или на языке формул

\mathbf{e_1}^2 = \mathbf{e_2}^2 = 1 \\ \mathbf{e_1}\cdot\mathbf{e_2} = 0

Единственным новым элементом в нашей двумерной геометрической алгебре является бивектор e e; это самый высокий класс элемента в алгебре (часто называемый псевдоскаляром). Рассмотрим теперь свойства этого бивектора. Первое, на что следует обратить внимание

\mathbf{e_1e_2} = \mathbf{e_1} \cdot \mathbf{e_2} + \mathbf{e_1} \wedge \mathbf{e_2} = \mathbf{e_1} \wedge \mathbf{e_2} = - \mathbf{e_2} \wedge \mathbf{e_1} = -\mathbf{e_2e_1}

то есть геометрическое произведение является чистым бивектором, потому что перпендикулярность векторов гарантирует, что e e обращается в нуль. Теперь давайте разберем этот бивектор:

( \mathbf{e_1e_2} )^2 = \mathbf{e_1e_2e_1e_2} = -\mathbf{e_1e_1e_2e_2} = \mathbf{(e_1)^2 (e_2)^2} = -1

Обратите внимание, что у нас есть реальная геометрическая величина, которая в квадрате равна -1! Поэтому возникает соблазн связать эту величину с единицей мнимой комплексной системы счисления (комплексное число принимает форму x + iy, где i известна как мнимая единица и обладает свойством i = -1). Таким образом, в двух измерениях геометрическая алгебра воспроизводит свойства комплексных чисел, но использует только геометрические объекты. На самом деле, переходя к геометрическим алгебрам более высоких измерений, мы начинаем видеть, что есть много объектов, которые квадратичны к -1, и что мы можем использовать их все в их правильной геометрической постановке.

Давайте теперь посмотрим, что происходит, когда бивектор ee умножается на векторы слева и справа. Умножение e и e слева дает

 (\mathbf{e_1 e_2}) \mathbf{e_1} = - \mathbf{e_2 e_1 e_1} = - \mathbf{e_2} \\ (\mathbf{e_1e_2}) \mathbf{e_2} = \mathbf{e_1 e_2 e_2} = \mathbf{e_1}

Легко заметить, что умножение слева на бивектор вращает векторы на 90 по часовой стрелке. Точно так же, если мы умножаем справа, мы вращаемся на 90 против часовой стрелки

 \mathbf{e_1(e_1e_2)} = \mathbf{e_2} \\ \mathbf{e_2(e_1e_2)} = -\mathbf{e_1}

Вращения

Из свойств бивектора ee очень легко показать, что поворот вектора a на угол к вектору a' достигается уравнением

\mathbf{a^\prime} = R\mathbf{a}P

где R величина, которую мы будем называть ротором и которая состоит из суммы скаляра и бивектора

R = \cos\frac \theta 2 - \mathbf{e_1e_2}\sin\frac \theta 2

а P это то же самое выражение, но с "+". На первый взгляд это может показаться довольно громоздким выражением для выполнения простого двумерного вращения; однако оказывается, что оно обобщается на более высокие измерения и поэтому обладает огромной силой.

Ротор R, переводящий вектор a в вектор a'. Обратите внимание, что понятие перпендикулярного вектора больше не требуется; важен бивектор или плоскость вращения.Ротор R, переводящий вектор a в вектор a'. Обратите внимание, что понятие перпендикулярного вектора больше не требуется; важен бивектор или плоскость вращения.

Приведенное выше уравнение фактически является формулой, которая используется для вращения вектора в любом измерении; если мы перейдем к трем измерениям, ротор R будет вращаться на угол в плоскости, описываемой бивектором. Поэтому все, что нам нужно сделать, это заменить бивектор ee на бивектор, который определяет плоскость вращения. И все; используя это очень простое выражение, мы обнаружим, что можем вращать не только векторы, но и бивекторы и более высокоуровневые величины. Осуществить вращение в трех измерениях таким образом, чтобы расширить понятия, которые мы понимали в двух измерениях, было проблемой, с которой Гамильтон боролся в течение многих лет, прежде чем, наконец, получить в качестве своего решения кватернионы. На самом деле элементы кватернионной алгебры Гамильтона это не что иное, как элементарные бивекторы (плоскости). Вооружившись очень простой идеей ротора, который совершает вращения, мы можем дать удивительно простые геометрические интерпретации многих других сложных объектов.

Специальная теория относительности

Специальная теория относительности была введена в 1905 году и возвестила начало новой эры в физике; отход от чисто классического режима ньютоновской физики. В специальной теории относительности (СТО) мы имеем дело с четырехмерным пространством: тремя измерениями обычного евклидова пространства и временем. Предположим, что у нас есть стационарный наблюдатель, с которым мы можем связать координаты пространства и времени, и этот наблюдатель будет наблюдать события со своего пространственно-временного положения. Теперь предположим, что у нас есть другой наблюдатель, движущийся со скоростью v; он тоже будет наблюдать события из своего непрерывно меняющегося пространственно-временного положения.

Проблема того, как два наблюдателя воспринимают различные события, относительно проста, когда скорость |v| мала. Но когда |v| приближается к скорости света, c, и мы добавляем тот факт, что она должна быть постоянной в любой системе, и математика становится уже не такой простой. Условно можно получить преобразование координат между системами отсчета обоих наблюдателей, и для перемещения между этими двумя системами мы применяем матричное преобразование, известное как преобразование Лоренца. Геометрическая алгебра дает нам прекрасно простой способ работы со специальными релятивистскими преобразованиями, используя не что иное, как формулу для вращений, рассмотренную выше, а именно a' = RaP. Наше пространство теперь имеет четыре измерения, и наши базисные векторы это три пространственных направления и одно временное направление; назовем эти базисные векторы , , и . Для четырех измерений, у нас будет шесть бивекторов (три пространственных бивектора плюс бивекторы, состоящие из пространственно-временных "плоскостей").

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

Преобразование Лоренца оказывается просто ротором R, который переводит ось времени в другое положение в четырех измерениях: RP. Таким образом, элегантным бескоординатным способом мы можем придать преобразованиям СТО интуитивный геометрический смысл. Все обычные результаты СТО совершенно естественно следуют из этой отправной точки. Например, сложные формулы для преобразования электрического (Е) и магнитного (В) полей при лоренцевом ускорении заменяются (гораздо более простым!) результатом

\mathbf {E^\prime} + I\mathbf {B^\prime} = R(\mathbf {E} + I\mathbf {B} )P

где I = псевдоскаляр четырехмерного пространства (4-объем), а штрихами обозначаем преобразованные величины.

Квантовая механика

В нерелятивистской квантовой механике существуют важные величины, известные как спиноры Паули; используя эти спиноры, мы можем записать уравнение Паули, которое управляет поведением квантово-механического состояния в некотором внешнем поле. Уравнение включает в себя величины, называемые спиновыми операторами, которые обычно рассматриваются как совершенно разные сущности для состояний. Используя трехмерную геометрическую алгебру, мы можем записать эквивалент уравнения Паули, в котором операторы и состояния являются мультивекторами реального пространства; действительно, спиноры становятся роторами того типа, о котором мы говорили ранее.

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

Рассмотрим случай, когда пакет частиц с энергией, скажем, 5 эВ сталкивается с прямоугольным барьером потенциалом высотой 10 эВ и конечной шириной, скажем, 5 Ангстрем. Теория квантовой механики позволяет предсказать, что, несмотря на кажущийся непроницаемым барьер, часть пакета действительно возникает с другой стороны. Эффект называется туннелированием, и он имеет фундаментальное значение во многих современных полупроводниковых приборах. Однако, когда мы задаем кажущийся очевидным вопрос о том, сколько времени туннелирующая частица проводит внутри барьера, квантовая теория дает нам множество ответов:

  1. такое не обсуждается, поскольку время не является эрмитовой наблюдаемой;

  2. время тождественно нулю;

  3. время является мнимым.

Почему квантовая механика делает такие странные предсказания? Основная причина неспособности иметь дело с траекторией частицы/пакета внутри барьера заключается в использовании i, неинтерпретированного мнимого скаляра (i = -1); обычно импульс частицы внутри барьера принимается кратным i, и это приводит ко всяким довольно бесполезным представлениям о мнимом времени.

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

На рисунке изображены предсказанные линии тока частиц, начинающих движение из различных позиций внутри волнового пакета энергии 5 эВ, падающего на барьер высотой 10 эВ и шириной 5 Ангстрем, как показано выше. Здесь видно, что линии потока частиц замедляются, находясь в барьере. Это контрастирует с некоторыми недавними обсуждениями сверхсветовых скоростей внутри таких барьеров, которые были выведены из экспериментально наблюдаемого факта, что частицы, туннелирующие через барьер, достигают цели раньше, чем те, которые проходят эквивалентное расстояние в свободном пространстве. Это кажущееся противоречие объясняется здесь тем, что именно частицы вблизи фронта волнового пакета, которые уже имеют фору, передаются и способны достичь цели. Интересно отметить, что большая часть модной в настоящее время области квантовой космологии основана на понятиях мнимого времени.

Гравитация

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

Следствием этой теории является огромное упрощение возможности обсуждать гравитацию целиком на плоском пространственно-временном фоне. Нет необходимости в сложных понятиях искривленного пространства-времени, которые мы все привыкли связывать с общей теорией относительности Эйнштейна. Именно здесь подход ГА отличается от прошлых подходов калибровочной теории к гравитации, где эти прошлые теории все еще сохраняли идеи искривленного пространственно-временного фона. Локально гауссова калибровочная теория гравитации воспроизводит все результаты общей теории относительности, но глобально эти две теории будут отличаться, когда речь зайдет о топологии. Например, всякий раз, когда обсуждаются сингулярности или горизонты (как в случае с черными дырами), теория ГА может давать различные предсказания обычной ОТО. Некоторые усовершенствованные методы решения, работающие исключительно с физическими величинами, также были найдены в ГА. Калибровочная теория гравитации ГА имеет дело с экстремальными полями (то есть полями, в которых возникают сингулярности) иначе, чем ОТО. Эти особенности рассматриваются просто способом, аналогичным тому, который используется в электромагнетизме (с использованием интегральных теорем). Взаимодействие с квантовыми полями также отличается и предлагает альтернативный путь к квантовой теории гравитации. В этом контексте интересно также отметить, что многие другие модные попытки объединить гравитацию и квантовую теорию (твисторы, супергравитация, суперструны) также естественным образом вписываются в рамки ГА.

Стержни, оболочки и прогибающиеся балки

Геометрическая алгебра полезна не только в области фундаментальной физики. Концепция системы отсчета, изменяющейся в пространстве или во времени (или и в том, и в другом), лежит в основе многих работ, направленных на понимание деформирующихся тел. Возьмем в качестве простого примера однородную балку, которая подвергается некоторой нагрузке по своей длине; свойства балки и нагрузки будут определять, как она деформируется.

Математически мы можем описать деформацию, разделив балку на очень маленькие сегменты и прикрепив системы координат (три взаимно перпендикулярные оси) к центру масс каждого сегмента. Первоначально, при отсутствии нагрузки и кручения, мы ожидаем, что начало координат каждого набора осей будет находиться вдоль осевой линии балки и что каждая система отсчета будет выровнена так, что ось x будет направлена вдоль длины балки, а ось z вертикально вверх. Теперь, когда луч деформируется, мы можем описать его положение в данный момент времени, указав положение начала координат и ориентацию рамки для каждого сегмента.

Предположим, что у нас есть неподвижная система отсчета на одном конце балки. Тогда система координат на сегменте i будет связана с ней некоторым ротором, R. Таким образом, при движении вдоль балки ориентации описываются ротором, изменяющимся с расстоянием x. Для заданной нагрузки и заданных граничных условий можно было бы решить задачу для роторов, чтобы получить информацию о свойствах изгиба балки. Условно эта задача была выполнена с использованием различных средств кодирования вращений: углов Эйлера, параметров вращения, направляющих косинусов, матриц вращения и т. д. Преимущество использования роторов двоякое: во-первых, они автоматически имеют правильное число степеней свободы (три), в отличие, например, от направляющих косинусов (где у нас девять параметров, только три из которых независимы), а во-вторых, мы можем эффективно решать полные уравнения (без аппроксимаций).

Эту идею варьирования фреймов можно развить еще на одну ступень. Сегодня большая часть исследований в области современной строительной механики стала прерогативой математика. Чтобы иметь дело с тонкими структурами, такими как стержни и оболочки, где при деформации структура поверхности может быть довольно сложной, люди увидели, что области математики, такие как дифференциальная геометрия и дифференциальная топология, могут предоставить полезные инструменты. Действительно, большая часть конечно-элементного кода, используемого сегодня в стандартных конструкторских пакетах, написана на основе алгоритмов, основанных на этой математике. В результате, однако, многие инженеры больше не могут понять работу таких пакетов и должны считать само собой разумеющимся, что то, что они используют, является правильным. С другой стороны, при использовании геометрической алгебры, задача снова сводится к тому, чтобы работать с роторами, которые могут изменяться во времени и/или пространстве на любой заданной поверхности; математика не сложнее, чем можно было бы использовать для решения простых задач механики. Таким образом, внутренний конечно-элементный код становится доступным для инженеров с возможностью его модификации.

Компьютерное зрение и анализ движения

Компьютерное зрение это, по сути, искусство реконструировать или выводить вещи о реальном трехмерном мире из представлений о сцене, снятых одной или несколькими камерами. Положение и ориентация камер могут быть известны, а могут и не быть известны, и внутренние параметры камер (которые определяют, насколько изображения, которые мы видим, отличаются от тех, которые были бы результатом идеальной проекции на плоскость изображения) также могут быть неизвестны. Из этого довольно упрощенного описания видно, что будет задействовано значительное количество трехмерной геометрии. Фактически, с середины 1980-х годов большая часть компьютерного зрения была написана на языке проективной геометрии.

В классической проективной геометрии мы определяем трехмерное пространство, точки которого соотносятся линиям проходящим через некоторое начало координат (заданную точку) в четырехмерном пространстве. Использующая такую систему алгебра инцидентности (пересечения линий, плоскостей и т. д.) чрезвычайно изящна, и, кроме того, преобразования, которые кажутся сложными в трех измерениях (например, проекция точек, линий и т. д. вниз на данную плоскость), теперь становятся простыми. В последние годы люди начали использовать алгебру, называемую алгеброй Грассмана-Кэли для проективных геометрических вычислений и манипуляций; это фактически внешняя алгебра Грассмана, поскольку она ограничивает себя использованием только внешнего произведения. Геометрическая алгебра содержит внешнюю алгебру как подмножество и, следовательно, является идеальным языком для выражения всех идей проективной геометрии. Однако у ГА также есть понятие внутреннего произведения, часто позволяющее нам делать вещи, которые были бы очень трудными при наличии только внешнего произведения.

Чтобы проиллюстрировать еще один способ использования геометрической алгебры в компьютерном зрении, рассмотрим задачу, возникающую при анализе движения, при реконструкции сцены и регистрации изображения (мозаика ряда различных, перекрывающихся изображений при наличии ограниченной информации). Предположим, что у нас есть несколько камер, наблюдающих за объектом. Также предположим, для удобства, что маркеры размещены на объекте так, чтобы эти точки можно было легко извлечь из изображений.

На рисунке показан эскиз системы с тремя камерами. Теперь, если мы наблюдаем сцену, скажем, с помощью M камер, мы обнаружим, что в каждой паре камер есть подмножество общего числа маркеров, которые видны. Первая задача состоит в том, чтобы найти, используя эти М изображений, наилучшие оценки относительных положений и ориентаций каждой камеры. Как только мы узнаем положение камер, мы хотели бы провести триангуляцию, чтобы найти трехмерные координаты других точек мира, видимых на ряде изображений; эти задачи не слишком сложны для точно известных точек изображения, но становятся намного сложнее, если эти точки зашумлены. Конечно, существуют общепринятые методы решения этих проблем.

Действительно, фотограмметристы делают именно это в течение многих лет. Однако решения, как правило, требуют больших оптимизаций, которые часто нестабильны. Вот тут-то и может помочь геометрическая алгебра. Используя ГА, можно решить как калибровочные, так и триангуляционные задачи таким образом, чтобы одновременно учитывать все данные с каждой камеры. Оптимизации, участвующие в решениях, способны использовать как первую, так и вторую аналитическую (в отличие от численной) производную всех величин, которые должны быть оценены согласованным образом. Обычно гораздо сложнее взять производные от величин, представляющих вращения. Используя ГА таким образом, можно получить точные решения при одновременном снижении вычислительной нагрузки, что делает его полезным в приложениях, требующих множества таких оптимизаций.

Выводы

Мы попытались дать краткое введение в математическую систему, которую мы называем геометрической алгеброй, и проиллюстрировать ее полезность в различных областях. Хотя мы обсуждали целый ряд тем от квантовой механики до изгибающихся балок, есть много убедительных примеров использования ГА в физике и технике, которые мы не обсуждали. К ним относятся электромагнетизм, поляризация, геометрическое моделирование и линейная алгебра. Современные инструменты математики, с которыми большинство из нас знакомо, разнообразны и сложны. За одну жизнь исследований мы можем надеяться овладеть лишь очень немногими областями. Однако, если бы большинство физиков и математиков использовали один и тот же язык, ситуация, возможно, была бы иной. Мы надеемся, что в этой статье мы показали, что геометрическая алгебра является кандидатом на такой единый язык.

P.S.

Статья вышла в свет в 2000 году. И хотя с тех пор геометрическая алгебра может и не стала универсальным языком точных наук, но все же, она нашла множество применений и продолжает завоевывать сердца и умы исследователей по всему миру. Так что, было бы полезным продолжить дальнейшее погружение:

  1. Для начала следует уяснить отличия от алгебраической геометрии. Там тоже есть замахи на универсальность. В качестве примера можно посоветовать наработки Джона Баэза. Да и вообще, его блог стоит отдельного внимания.

  2. Про сравнение с векторной алгеброй смотрим в Википедии.

  3. Видео-лекция от одного из авторов статьи (спасибо, @sergehog).

  4. Поднимаем планку: более современное введение в ГА.

  5. Свежая книжка с приложениями.

  6. Более-200-страничный опус от одного из авторов.

  7. Grassmann.jl пакет для языка Julia

  8. + еще множество источников на одном сайте.

Подробнее..

Docs as Code введение в предмет

30.04.2021 08:08:53 | Автор: admin

В последние несколько лет в среде технических писателей все больше на слуху концепция Docs as Code. Если вы раньше не сталкивались с этим термином, он обозначает подход к разработке технической документации с использованием тех же инструментов и процессов, что и написание кода. Если DocOps это про процессы и коллаборацию, то Docs as Code про инструментарий, при помощи которого мы несмотря ни на что. Мы выбрали этот подход, когда создавали портал документации Plesk.

В этой статье я кратко расскажу, что такое Docs as Code и зачем оно нужно, а затем дам несколько советов относительно того, как это чудо враждебной техники внедрять, сдобрив всю историю рассказами о тех граблях, на которые мы наступили, топая в светлое будущее. Я старался писать такую статью, которая пригодилась бы мне в 2017 году, когда мы эту кашу заваривали.

(N.B. Сразу оговорюсь, что эта статья - обзорная, в ней нет огрызков конфигов или примеров кода. Если вы уже знаете теорию и ищете, как конкретно пропатчить KDE2 под FreeBSD, статья может быть вам не очень интересна).

Акт 1: Теория

Давным-давно, в далёкой-далёкой галактике

Начнем от противного. Чтобы лучше понять преимущества Docs as Code, посмотрим, как документацию писали (а много где и продолжают писать) мои коллеги в компаниях по всему миру. Как правило, выглядит это так:

  • Документацию пишут и поддерживают технические писатели и только они.

  • Для разработки и публикации используются специализированные проприетарные инструменты, такие как MadCap Flare, Adobe RoboHelp, или Author-it. Реже Wiki или Confluence.

  • Технические писатели работают обособленно. Что происходит у них в отделе, никто в конторе не знает и особо этим не интересуется. Взаимодействие на уровне "разработчик заметил ошибку в примере кода и завел баг в Jira", так как с инструментами технических писателей разработчик не знаком и доступа туда, где хранятся доки, у него нет.

Окей, в чем недостатки status quo? Их несколько:

  • Отсутствие интереса к документации у большинства сотрудников. Хороша документация разрабатываемых продуктов или плоха никто не знает, и никому до этого нет дела. Не мой цирк, не мои обезьяны.

  • Плохая коллаборация. Чтобы исправить опечатку в документации, разработчик или сотрудник поддержки должен написать письмо или завести баг, и станут ли они это делать - бабушка надвое сказала. Это лишний геморрой, а у них и так работы по горло. Процесс совместного ревью также затруднен. Чтобы сделать ревью документа, его нужно выгрузить в гуглдок или файл MS Word, отправить по почте нескольким людям, принять от них комментарии в документах и потом свести их воедино. Ревьюеры не видят комментарии друг друга, делают двойную работу и противоречат друг другу. Это неудобно и техническому писателю, и проверяющему.

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

  • Стоимость. Лицензия на широко используемый продукт MadCap Flare обойдется вам в $149 на человека в месяц. Хотите воспользоваться облачным решением от MadCap? Готовьте $300. Незначительная сумма для большой организации. Большой удар по карману для маленькой фирмы или стартапа, еще не нашедшего стабильный источник финансирования.

Конечно, ни один из этих недостатков не является фатальным. Документация создавалась и еще долгие годы будет создаваться при помощи традиционных подходов и инструментов. Однако, если есть альтернатива, важно знать, в чем она заключается и чем она лучше. Что может нам предложить Docs as Code? Давайте узнаем вместе.

Дивный новый мир

Docs as Code это подход к разработке технической документации, который выглядит следующим образом:

  • Документация пишется не в плейнтексте и не в формате WYSIWYG, а на языке разметки (например, Markdown, reStructuredText, Asciidoc).

  • Документация хранится в репозитории Git.

  • Документация собирается в нужный формат при помощи генератора статических сайтов (Sphinx, Hugo, Jekyll, MkDocs). Форматов может быть сразу много: HTML, PDF, DOCX и так далее.

  • Документация пишется и обновляется коллаборативно.

К чему эти сложности?

Резонный вопрос. Какую головную боль лечит Docs as Code и в чем его преимущества перед классическим подходом? Преимущества есть, и их немало:

  • Docs as Code использует знакомые разработчикам процессы и инструменты, что помогает вовлечь их в процесс создания документации. Это может быть большим подспорьем, если в вашей организации нет выделенного технического писателя и разработкой документации для продукта занимаются сами разработчики. Чудес, правда, ждать не стоит. Для того, чтобы и все заверте, скорее всего, придется терпеливо приучать разработчиков: Василий, смотри, вот ты десять минут заводил баг в Jira, заполнял все необходимые поля и расписывал по шаблону действительность/ожидания только для того, чтобы мы в лоб заменили на по лбу. А что бы было просто не кинуть нам пулл реквест? Быстрее и проще же.

  • Использование репозиториев Git и связанных с ними процессов обеспечивает возможность поддерживать документацию для разных версий продукта, облегчает коллаборацию между сотрудниками, позволяет отслеживать авторов внесенных изменений, и дает возможность быстро откатить эти изменения, если нужно. До начала использования Docs as Code у меня в практике был случай, когда я, неправильно сориентировавшись в обстановке, дал сотруднику задачу, которую тот выполнял полдня. Через пару часов выяснилось, что внесенные изменения нужно откатить, чем я лично и занимался до самого вечера. Сейчас подобный конфуз решился бы за несколько минут.

  • Использование генератора статических сайтов для публикации приносит с собой все связанные с этим преимущества - сайт документации грузится быстро и на нем нечего ломать.

  • В отличие от проприетарных инструментов для разработки документации, функциональность инструментов Docs as Code безгранично расширяема и позволяет создать настолько мощную (или, наоборот, простую и дешевую) систему, насколько нужно именно вашей организации.

  • Значительное (в несколько раз) сокращение временных затрат на рутинные операции. Публикация при помощи проприетарных инструментов запускается вручную и выдает через какое-то время готовый документ в формате .html или .pdf. Разместить его онлайн ваша забота. В результате имеем долгие, многоступенчатые процедуры публикации, требующие ручных действий на каждом из шагов. Публикация же с помощью Docs as Code может быть сведена к выполнению одной команды или даже полностью автоматизирована.

  • Проприетарные инструменты для разработки документации требуют покупки одной или нескольких лицензий (зачастую весьма дорогих). Весь же цикл разработки документации по методологии Docs as Code можно выстроить при помощи свободного программного обеспечения. Это также порадует тех, кто отказывается от использования проприетарного ПО из идейных соображений.

Хотите страшную сказку на ночь? Я расскажу, как было у нас до того, как в Plesk появился Docs as Code. Мы использовали продукт под названием Author-It, и публикация документации с его помощью выглядела так:

  1. Делаешь выгрузку HTML. Это могло занять от пяти минут до часа, в зависимости от размера гайда.

  2. Обрабатываешь полученную россыпь файлов кастомной тулзой, накладывающей стили и брендинг.

  3. Пакуешь все это дело в архив и заливаешь по FTP на сервер.

  4. Запускаешь сборку и ждешь еще полчасика. Молишься, чтобы не упало. Если упадёт, надо перезапускать.

Всё это счастье происходило при каждой публикации. Даже если ты поправил опечатку в одну букву. Это был неописуемо нудный процесс, жравший непристойное количество времени и часто приводивший к ошибкам. Забыл накатить стили перед публикацией? GOTO 20. Забыл накатить стили и уже успел удалить сгенерированные Author-it html-ки? GOTO 10. Теперь же наша документация собирается и публикуется по мерджу пулл реквеста автоматически. Автоматически, Карл! Пока не попробуешь сам, не поймешь, насколько же это круто! А сэкономленное время и внимание можно пустить на решение интересных задач.

Подводные камни

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

  • Отсутствие готовой, коробочной версии продукта. Все инструменты, нужные для Docs as Code, доступны, но запускать и настраивать систему вам придется самостоятельно. Будьте готовы к тому, что создание, обслуживание и совершенствование системы публикации документации потребует времени и технической экспертизы.

  • Отсутствие off the shelf решения подразумевает и отсутствие технической поддержки. Если что-то пошло не так, некому завести срочный тикет. Придется разбираться самим при помощи комьюнити.

  • Вашим техническим писателям нужно будет освоить работу с Git хотя бы на базовом уровне (git checkout/pull/commit/push + разрешение конфликтов при слиянии). Поначалу с этим возникнут трудности, и производительность может пострадать.

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

Антракт

Теперь вы знаете, что такое Docs as Code, и дальше рекомендуется читать, только если вам интересно не только что, но и как. Наше путешествие к Docs as Code началось в 2017 году. У нас было много энтузиазма и мало практического опыта, поэтому мы провели в пути дольше, чем планировали, и набили немало шишек. Об этом и пойдет речь дальше.

Но сперва я сделаю еще один реверанс. Прежде чем читать про как, давайте подумаем про зачем. Docs as Code в тренде, но не стоит бросаться внедрять хайповую технологию, не задав себе вопрос чтобы что? В нашем случае ответ выглядел следующим образом:

  • Мы хотели ускорить и упростить процесс публикации - он занимал много времени и требовал ряда ручных действий в независимости от объема внесенных изменений.

  • Нам нужна была поддержка версионирования, а Author-It не мог в него от слова совсем. Author-It позволял хранить и публиковать документацию только для одной версии продукта. Если нужно было внести изменения в документацию для более ранней версии Plesk, приходилось править HTML руками.

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

  • Также хотелось оставить в прошлом некоторые заскоки Author-It. Например, он позволял молча и без подтверждения выкинуть из структуры гайда топик со всеми его подтопиками. И возможности откатить эту операцию при помощи Ctrl + Z не было. Сами топики при этом не удалялись, страдала только структура, и в теории ее можно было воссоздать руками. На практике было быстрее и проще зайти по RDP на виртуальную машинку, где крутилась серверная часть Author-It, развернуть более старый бэкап базы MSSQL, в которой Author-It хранил всю информацию, выгрузить неповрежденную структуру гайда в XML, снова подключить актуальную базу, удалить гайд, структура которого пострадала, а затем импортировать его из XML. Не шучу, время от времени приходилось заниматься подобным шаманством.

Мы рассматривали различные варианты нового механизма публикации, но все они по тем или иным параметрам не устраивали. Wiki не позволяла сделать версионирование и не имела наглядной структуры и оглавления. Confluence не имел внятной поддержки локализации кроме кошмарного варианта давайте сделаем отдельный спейс для каждой комбинации версия продукта + язык. Смотрели в сторону MadCap Flare, но в итоге отказались, решив, что нет никакой гарантии, что впоследствии не вылезут какие-то проблемы, которые снова заставят переезжать. В итоге выбор пал на Docs as Code как на вариант, обещавший в перспективе удовлетворить всем нашим требованиям.

Акт 2: Практика

Внедряем Docs as Code

Что же, вы решили внедрить в своей организации подход Docs as code. С чего начать?

Сформируйте список требований

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

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

Планируйте

Прежде чем начинать работу по внедрению, тщательно спланируйте ваш проект, разберитесь в существующих технологиях и инструментах. Эта грабля нам довольно больно стукнула по лбу. Мы начинали внедрение Docs as code силами отдела технической документации. Когда стало ясно, что нам не хватает где-то ресурсов, а где-то экспертизы, пришлось обратиться за помощью к коллегам. Мы обсудили с ними цели и план работ и пришли к выводу, что некоторые из выбранных инструментов лучше заменить. В итоге часть уже проделанной работы оказалась на свалке.

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

"Да чего тут рассусоливать, всем все понятно, поехали!""Да чего тут рассусоливать, всем все понятно, поехали!"

Пользоваться таким чудом может быть неудобно, а в худшем случае и вовсе невозможно.

Документируйте

Не ленитесь документировать вашу систему Docs as Code. Особенно если вы делаете что-то более сложное, чем один репозиторий Git + генератор статических сайтов в стандартной комплектации. Да, на это всегда не хватает времени, но поверьте, усилия окупятся сторицей. Через пару лет вам не нужно будет морщить лоб, пытаясь разобраться, как же оно тут все устроено. Это что? Как оно работает? Кто писал этот код? Ах, человек уже год как уволился... Чем подробнее вы опишете детали реализации вашего решения, тем проще его потом будет поддерживать и модернизировать. Если вы решили заказать создание системы Docs as Code на стороне, обязательно включите ее документирование в список задач, необходимых для выполнения.

Решите, в каком формате вы хотите публиковать документацию

HTML? PDF? DOC? Все из вышеперечисленного? В зависимости от ответа на этот вопрос вам может лучше подойти тот или иной язык разметки. Например, из reStructuredText можно публиковаться во все три вышеприведенных формата, а классическая интерпретация Markdown конвертируется только в HTML.

Выберите язык разметки

Зная задачу, проще подобрать инструмент для ее выполнения. Существует целый ряд легковесных языков разметки, но два самых популярных из них - reStructuredText и Markdown:

Markdown

Из двух рассматриваемых языков разметки этот более простой, но и более ограниченный в плане форматов, в которые он может быть сконвертирован без дополнительных приседаний. Существует несколько имплементаций Markdown, ни одна из которых не является канонической. Например, GitHub Flavored Markdown обладает более широкими возможностями по сравнению со своим предком. Выбрав наиболее подходящую для ваших нужд имплементацию Markdown, убедитесь, что используемый вами парсер корректно превращает ее в HTML.

reStructuredText

Более мощный язык разметки, но и более капризный. В нем сложнее писать и проще допустить ошибку в синтаксисе (во всяком случае, пока не привыкнешь). Например, чтобы документ в reStructuredText не собрался корректно, достаточно пропустить или поставить лишний пробел или перенос строки. Большое преимущество reStructuredText в его расширяемости при помощи плагинов вы можете научить систему публикации распознавать и корректно отображать необходимые вам сущности (ссылки, таблички, вставки и так далее) в HTML.

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

.. admonition:: summary

Hello world!

Собираем HTML и видим вот такое:

Какой язык разметки используется в Plesk? Мы подумали и решили:

Это не шутка мы действительно используем на нашем портале документации и reStructuredText и Markdown. Зачем? Все просто: мы используем разные языки разметки для решения разных задач с разными требованиями:

  • reStructuredText используется для написания документации. Для этой задачи нам в первую очередь важны богатые возможности форматирования, а также расширяемость.

  • Markdown используется для написания release notes. Мы пишем их много и часто, а требования к форматированию минимальны - болд/италик/моноспейс/кодблок/ссылки. Для этой задачи нам важнее всего простота и скорость использования.

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

Выберите инструмент для публикации

Вы определились с языком разметки. Пора выбрать инструмент, при помощи которого вы будете документацию публиковать. Вариантов несколько, но в этой статье для начинающих я хотел бы сфокусировать внимание на четырех: Hugo, Jekyll, Sphinx и MkDocs. По сути, все они являются генераторами статических сайтов. Hugo и Jekyll больше ориентированы на блоги, а Sphinx и MkDocs специально заточены для создания документации и обладают большим количеством полезных в этом деле фич из коробки. Все четыре инструмента популярны, широко используются, поддерживаются и имеют активное комьюнити.

Если выбор вас пугает, не переживайте. На самом деле, часть опций вы отсекли еще на предыдущих шагах. Генераторы статических сайтов поддерживают, как правило, один-два языка разметки. Если на предыдущем шаге вы выбрали reStructuredText (расширяемость наш выбор, а синтаксис выучим), то ваш главный кандидат Sphinx. И ваш выбор инструментов будет куда шире, если вы проголосовали за Markdown (мы не хотим возиться с reStructuredText и разбираться, почему после трех коммитов, призванных исправить ошибки форматирования, HTML собирается вкривь и вкось).

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

В Plesk для сборки документации мы используем Sphinx, а для сайта портала документации целиком - Jekyll. Это позволяет расцепить механизмы обновления непосредственно руководств и других страниц, размещенных на портале документации, например, чейнджлога или FAQ. Благодаря этому публикация release notes для новых версий продукта и его расширений занимает меньше минуты.

Сделайте красиво

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

Что насчет существующего контента?

Возможно, у вас уже есть сайт с документацией. Что же, при выборе Docs as code вам придется выбросить его или заново набивать руками? Не обязательно. Существуют решения для конвертации текстов из одного формата в другой, но с ними тоже придется разбираться. Как тут поступить зависит от объема существующей документации. Если у вас есть десяток-другой документов, возможно, будет проще, скрепя сердце, набрать их заново в выбранном языке разметки. В Plesk массив документации насчитывал приблизительно четыре с половиной тысячи документов, поэтому для нас подобный вариант не был реалистичным. В итоге мы без потерь сконвертировали всю существующая документацию из .html в .rst при помощи инструмента Pandoc.

Определитесь с версионированием

Если вы разрабатываете SaaS продукт или агрессивно пушите пользователей обновляться, поддержка версионирования вам вряд ли потребуется. Но что делать, если вам нужно поддерживать и предоставлять пользователям документацию для двух или более версий продукта?

Дешевое решение паковать собранную документацию для старых версий продукта в архивы и делать их доступными для скачивания. Мы так поступаем с документацией для ушедших в EOL много лет назад версий Plesk, которыми уже почти никто не пользуется. Но это неудобно для пользователя. Клиент на старой версии продукта вряд ли сможет найти вашу документацию при помощи Google или другой поисковой системы (для справки: на docs.plesk.com органический поисковый трафик составляет более половины посетителей).

Нам было важно дать клиентам доступ к документации последней и предпоследней версий Plesk (Onyx и Obsidian) и сделать так, чтобы отдельная страница со своим контентом и URL была у обеих версий. Мы реализовали это следующим образом: в каждом репозитории Git, содержащем исходники того или иного руководства, есть несколько веток. Каждая ветка содержит исходные файлы для той или иной версии продукта, что позволяет вносить изменения в документацию, например, для Plesk Obsidian, при этом никак не затрагивая документацию для Plesk Onyx. Есть и недостаток: когда нужно обновить документацию для всех версий продукта сразу, приходится делать коммиты в каждую ветку по очереди, что тоже занимает время.

Ду ю спик инглиш?

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

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

Мы пошли более затратным в реализации, но куда более дешевым в использовании путем. Мы разбиваем исходные документы на английском языке на единицы перевода (заголовки, абзацы все, что с обеих сторон ограничено переносом строки). Переводы руководств на все языки хранятся в том же репозитории/ветке, что и само руководство в виде .po файлов. Содержимое их выглядит так:

#: ../../../../projects/administrator-guide/source/53231.rst:15

msgid "You can choose to:"

msgstr "Folgende Optionen stehen zur Verfgung:"

Здесь мы видим перевод единицы перевода из репозитория administrator-guide, документ 53231.rst, строка 15. В наличии как исходная строка, так и ее перевод на немецкий (всего в данном .po файле шесть таких единиц, некоторые поменьше, некоторые побольше). В итоге все содержимое документа на английском покрывается переводом. При сборке документации на немецком механизм берет исходный файл .rst и автоматически заменяет единицы перевода в нем на переведенные. Данный подход позволил нам интегрироваться с сервисом Crowdin, в котором работают наши переводчики. Они пользуются привычным им интерфейсом мы получаем переводы.

Автоматизируй это

Одно из основных преимуществ подхода Docs as code - возможность использовать инструменты непрерывного развертывания, чтобы передать связанные с публикацией рутинные операции на попечение роботов. Не пренебрегайте им. Чем чаще вы вносите изменения или публикуете новые документы, тем больше времени автоматика вам сэкономит. С тех пор, как мы внедрили автоматическую публикацию по слиянию, автоматика экономит нам минимум один-два (а зачастую и больше) человеко-часа каждую неделю, а также исключает подобные драматические сцены:

-Василий, почему релиз ноты еще не на продакшене? Два часа как вышло обновление, клиенты жалуются (у нас были подобные случаи и клиенты действительно жалуются)!

-А, черт, я закоммитил, а запустить сборку забыл :(

В Plesk мы реализовали непрерывное развертывание документации при помощи Jenkins - он уже используется для разработки и публикации самого продукта, и мы решили не изобретать велосипед. Для публикации документации и релиз нот используются разные пайплайны. Схематично выглядит это так:

  1. При слиянии ветки с изменениями в основную, сервер Jenkins запускает сборку гайда, в который были внесены изменения (.rst => .html), на всех языках, на которые он переведен, а также обновляет файлы .po, которые пойдут потом на перевод. Если мы публикуем релиз ноты, этот шаг пропускается.

  2. Пересобирается сам портал документации, включая релиз ноты, FAQ и все прочие находящиеся на нем страницы.

  3. Собранная документация разворачивается на сервере.

  4. Сети доставки содержимого подается команда сбросить кэш.

Здесь есть еще одна тонкость. Кроме Plesk, мы публикуем множество расширений к нему, и каждый новый выпуск каждого из расширений тоже сопровождается своими релиз нотами. Они становятся доступными к сборке документации как только попадают в основную ветвь, поскольку для них время публикации не особо критично. Но для обновлений самого Plesk релиз ноты должны появиться в публичном доступе одновременно с выходом обновления, иначе сразу начинают сыпаться запросы от клиентов ("Мой Plesk автоматически обновился, где я могу прочесть об изменениях?", "Я вижу на портале документации релиз ноты для обновления Plesk, как мне его поставить?"). Во избежание подобных ситуаций, релиз ноты для основного продукта становятся доступными к сборке документации и публикуются строго в рамках публикации обновления Plesk.

Заключение

Нужен ли вам Docs as code? Зависит от. Если у вас небольшая компания, несложный продукт, устоявшиеся процессы и дюжина страниц документации, которые вы обновляете раз в квартал пожалуй, выхлоп не окупит затрат на внедрение. Если же вас заинтересовали описанные в моей статье возможности, или вы просто любите быть на острие прогресса почему нет? Просто заранее вдумчиво спланируйте вашу будущую систему Docs as code исходя из ваших уникальных потребностей, и я уверен вы не пожалеете :)

Спасибо за внимание!

P.S. Хочу также сказать "спасибо" Николаю Волынкину, Дмитрию Ширяеву и Катерине Говердовской за участие в работе по созданию и наполнению нашего портала документации, а также за помощь в написании статьи.

Подробнее..

Воспитание Obsidian вашего персонального информационного менеджера

01.06.2021 10:11:39 | Автор: admin

Методик повышения личной эффективности хоть пруд пруди. Как по мне, основная проблема с ними в том, что нужно работать самому. Совершенно нормальное стремление избежать приложения усилий. Пускай хорошая методика и есть тот рычаг, коим обещают сдвинуть Землю, но физика знает, что всю-всю работу делать всё равно нам самим. Основной вопрос, терзавший меня в вопросе выбора персонального информационного менеджера заключался в том, что он будет делать вместо меня. Задача была не самая легкая. За короткий срок разобраться в новой области организовать конспекты, классифицировать справочники и литературу по теме. Море открытых вкладок браузера (всё очень нужное, оно не должно скрыться с глаз), pdf-файлы, заботливо присланные новыми коллегами С этим всем в голове я познакомился с программой Obsidian, которая пообещала стать A second brain, for you, forever.


Преодолевая скепсис


В прошлом посте Markdown в науке я рассмотрел некоторые pro et contra использования Markdown-формата записей для исследователей. Вкратце еще раз перечислю: простой текст, читаемый свободно без всяких дополнительных программ, широкое распространение и поддержка, возможность использования готовых фрагментов для наполнения сайтов и презентаций.


База знаний (в терминологии Obsidian vault, хранилище) это просто папка на диске, куда вы складываете Markdown-заметки, мультимедиа файлы, иллюстрации и уже созданные кем-то книги и статьи (pdf). Всё, что имеет отношение к делу вы просто перетаскиваете в окно программы и оно окажется в этой самой папке.


Начать сбор материалов очень просто копируем с веб-страниц (разметка и ссылки сохраняются), перетаскиваем файлы и подписываем свои комментарии к тому, что образуется. Программа бесплатная, есть под разные платформы Linux, Windows, Mac OS.


Добавляем порядок


Сразу, как определились, где лежит и как называется хранилище, имеет смысл обозначить точку входа в предметную область. Это самая первая заметка (создаем её нажатием Ctrl-n), и описываем то, что хотим там видеть. "В этой базе собраны знания о том, что есть квантовая точка". Вот и первый термин. Запишем его в квадратных скобках


В этой базе собраны знания о том, что есть [[квантовая точка]]

Редактор Obsidian двухмодальный. Это означает, что пока вы находитесь в режиме редактирования, вы видите Markdown-разметку. С квадратными скобками и некоторыми другими вспомогательными символами, о коих напишу после. Переключившись в режим просмотра (Ctrl-e) мы видим оформленную страницу, со ссылкой квантовая точка. Ссылка еще никуда не ведёт, но один клик и мы редактируем новую заметку с названием квантовая точка.


Возможности редактора хорошо изучаются на примерах. Выберете Open another vault (кнопка слева), выберете Obsidian help. Видите что-то понравившееся из оформления переключайтесь в режим редактирования, изучайте, как оно сделано. Копируйте к себе.


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


Возможности из коробки


Кроме того, что Markdown заметки редактируются в том числе и визуально (WYSIWYG-принцип), в списке представлено, что понимает и умеет делать Obsidian.


  1. многоуровневые хэштеги #справка/химия/нано;
  2. таблицы и иллюстрации;
  3. математические формулы;
  4. встраивание мультимедиа.

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


Обучаем вашего помощника

Подробнее..

Из песочницы Фетиш WYSIWYG или Как правильно скрещивать ужа с ежом

05.11.2020 12:07:06 | Автор: admin

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


Уяснив стартовые данные, я впал в лёгкое уныние. Больше всего в тот момент мне хотелось сослаться на обстоятельства непреодолимой силы, перегруженность, невменяемость, сезонное обострение ящура короче говоря, найти любой повод и на волю, в пампасы! Но сакраментальное ты ж программист! и осторожное буду должен уже прозвучали, вздохи химика становились все тяжелее, размеренно падая на и без того узкую тропку к отступлению, химиковы глаза за толстыми стёклами очков давали изрядную фору фирменному взгляду Кота-в-сапогах из Шрека...


Пути назад не было. Квест начался.


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


Ситуация вырисовывалась невесёлая. Химик весьма уверенно набирал текст в notepadе и даже, кажется, знал, как выделить строчку в Wordе курсивом. Я совершенно точно помнил формулы воды, этилового спирта и был убеждён, что лить воду в серную кислоту ни в коем случае нельзя. Или наоборот? Неважно, главное на этом пересечение наших познаний исчерпывалось. Вопрос вырисовывался один, но глобальный: как? Как организовать работу так, чтобы химик мог излить ещё не рождённый СНТ на бумагу то есть, в какой-то текстовый формат, а я мог бы разобраться в структуре документа и сверстать его надлежащим образом, вставив в нужные места все упомянутые выше красоты?


Word отпал, когда к концу следующего дня химик прислал первые наброски нашего с ним великого творения, в порядке здоровой инициативы набранные с помощью именно это редактора. По привычке он набирал в нём текст как в блокноте: абзацные отступы, состряпанные из ядрёной смеси пробелов и табуляций, ряды пустых абзацев, долженствующие перенести текст на следующую страницу, нумерованные вручную списки, колонки текста, выровненные все теми же многострадальными пробелами и переносами строк в самых неожиданных местах Химик блистал! К сожалению, он совсем забыл про поля, и когда я выставил их ширину в требуемые значения, всё это великолепие рассыпалось в совершенно невзрачные и не поддающиеся восстановлению ошмётки. What you see оказалось не совсем what you get, а говоря по правде совсем не.


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


Решение пришло после короткого гугления: Markdown! Прикинув, что возможности этого простого, как табуретка, языка разметки перекрывают потребности химика по оформлению текстовой части его работы на 99%, я подыскал внятное руководство и переправил его химику с предложением обсудить этот вариант по скайпу. На удивление, химик воспринял идею без особого сопротивления: как потом выяснилось, вольная борьба с Wordом изрядно поднадоела ему самому.


По обсуждении, план совместной работы над документом сводился к следующему:


  • Химик, используя подходящий Markdown-редактор, готовит текстовую часть документа, соблюдая его структуру, вводя разделы, подразделы и т.п.
  • Простые формулы вписываются непосредственно в Markdown-разметку, сложные и структурные рисуются от руки, сканы пересылаются мне; место в тексте для них маркируется.
  • Данные для таблиц, диаграмм и графиков присылаются мне в сыром виде (как оказалось, это были в основном CSV-файлы); место в тексте для них также маркируется.
  • Я подготавливаю сложную вёрстку (титульник, формулы, таблицы, диаграммы и графики, библиографию и т.д.) как компоненты составного документа LaTeX.
  • После подготовки и вычитки всех материалов я верстаю их в единый документ LaTeX, добавляю содержание, приложения и т.п.
  • Профит!

И работа пошла, пусть поначалу со скрипом и неровно, но пошла! После нескольких дней ошибок, химик на удивление неплохо приноровился к незатейливому синтаксису Markdown, благо, редактор не слишком отличался от его излюбленного блокнота. Для удобства, текст публикации был разбит на несколько md-файлов, по числу основных разделов. Во избежание случайной утраты данных проект был помещён под контроль VCS; правда, мне приходилось рулить проектом сразу на двух машинах: на своём и, в ипостаси альтер-эго химика посредством TeamViewer на его компьютере.


Предлагая к использованию Markdown, я планировал воспользоваться всеми любимым pandocом и просто-напросто преобразовать md-файлы в исходники LaTeX, но время поджимало, и компоновку итогового документа пришлось начать, не дожидаясь полного завершения работ химиком. И вот тут-то Оказалось, я здорово недооценил перфекционизм и энтузиазм моего соавтора: просматривая очередной коммит проекта, я заметил массовые и довольно объёмные изменения в md-файлах, которые были давно вычитаны, исправлены, преобразованы в LaTeX и щедро нафаршированы формулами, таблицами и прочими кулинарными ингредиентами. Как выяснилось, в порыве творческого экстаза химик в очередной раз перечитал уже набранные разделы, остался не весьма ими доволен и, ничтоже сумняшеся, тут же устранил недочёты. Всю ночь возился! горделиво заявил он по скайпу в ответ на мои робкие попытки узнать, что же произошло.


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


Из этих двух вариантов всё более хотелось выбрать третий: пампасы! Тем более, что химик явно недоумевал, почему я не разделяю восторгов по поводу улучшений и украшений, несомненно нашёптанных ему его органико-химической музой в, разумеется, лучшие творческие минуты его жизни, что не оставляло сомнений в том, что муза посетит его ещё не раз и процесс внесения правок и изменений приобретает мрачноватую перспективу стать перманентным и всеобъемлющим.


И вдруг! Покопавшись в пакетах LaTeX, я с удивлением обнаружил среди прочих пакет с многообещающим названием markdown. Ещё не веря в удачу, я начал читать описание Да! Этот пакет позволял включать Markdown-файлы в документ LaTeX as is, без сторонних утилит, без дополнительных правок или излишних телодвижений, при этом позволяя использовать в Markdown-разметке конструкции LaTeX!


Теперь мне оставалось только прописать в md-текстах химика включение иллюстраций по месту (в виде tex-разметки), залить эти изменения на его компьютер и строго-настрого запретить ему править или выкидывать вот эти вот непонятные закорючечки. Остальной химиков текст ему позволялось изменять как угодно, в любое время дня и ночи, на пару с музой или без содействия оной. Простая пересборка LaTeXом подтягивала в итоговый документ все изменения, никак не отражающиеся на уже проделанной работе. Система контроля версий довершала глубоко эшелонированную линию обороны от возможных деструктивных поползновений.


Публикация была готова не совсем в срок, но до дедлайна уложиться удалось.


Ф-ф-у-у-у-ух.


Повторюсь, это вполне реальная история. Да, есть ещё люди, которые используют Word (или LibreOffice Writer, или AbiWord, или ) как пишущую машинку, не заморачиваясь стилями, параметрами абзацев и тому подобными, совершенно бессмысленными с их точки зрения, штуками. А почему нет? Это же вовсеушипрожужжанный WYSIWYG, они же видят перед собой что-то, вполне себе читаемое. Да, при этом они могут быть вполне успешными профессионалами в своей области. Да, им непросто объяснить суть проблемы, а научить правильной вёрстке непросто вдвойне. И да, порой им приходится готовить публикации...


Надеюсь, мой опыт работы в тандеме подобного толка пригодится ещё кому-то в сходной ситуации, или натолкнёт на нужное решение в какой-то иной. Более подробно ознакомиться с возможностями пакета markdown можно в обзорной статье.


Удачи!

Подробнее..
Категории: Верстка , Markdown , Latex

Категории

Последние комментарии

  • Имя: Макс
    24.08.2022 | 11:28
    Я разраб в IT компании, работаю на арбитражную команду. Мы работаем с приламы и сайтами, при работе замечаются постоянные баны и лаги. Пацаны посоветовали сервис по анализу исходного кода,https://app Подробнее..
  • Имя: 9055410337
    20.08.2022 | 17:41
    поможем пишите в телеграм Подробнее..
  • Имя: sabbat
    17.08.2022 | 20:42
    Охренеть.. это просто шикарная статья, феноменально круто. Большое спасибо за разбор! Надеюсь как-нибудь с тобой связаться для обсуждений чего-либо) Подробнее..
  • Имя: Мария
    09.08.2022 | 14:44
    Добрый день. Если обладаете такой информацией, то подскажите, пожалуйста, где можно найти много-много материала по Yggdrasil и его уязвимостях для написания диплома? Благодарю. Подробнее..
© 2006-2024, personeltest.ru