Podlite: Идеи для модернизации Raku Pod (ака pod6)

Podlite родился как облегченная реализация Raku Pod (также известного как pod6), и со временем он превратился в самую полную реализацию этого языка разметки. Podlite включает в себя:

  • Библиотеки для TypeScript

  • Веб-редактор - pod6.in

  • Бесплатный десктоп редактор - Podlite-desktop

  • Пакет для создания современных веб-приложений: Podlite for Web

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

Я веду ежедневные журналы в формате Raku Pod уже много лет и использую Podlite ведения блогов.

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

Селекторы

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

Общий синтаксис следующий: 

<EXTERNAL_SOURCE>
or
[ <EXTERNAL_SOURCE> | ] <BLOCKS_SELECTOR>

For example:

  • head1, head2

    Этот селектор определяет все блоки заголовков уровня 1 и уровня 2.

  • para,code

    Этот селектор определяет все блоки абзацев и примеров кода.

Селекторы можно использовать не только для описания блоков в текущем документе, но и во внешних документах:

  • file:article.rakudoc

    Этот селектор указывает на все блоки в файле article.rakudoc.

  • file:article.rdoc | head1, head2

    Все блоки head1 и head2 из файла article.rdoc.

Вот еще несколько примеров:

Selector Description
head1, head2, item1 Все блоки head1, head2 и item1 из текущего документа
file:article.rakudoc | head1, head2 Все блоки head1 и head2 из файла article.rakudoc.
file:./includes/*.pod6 | head1, head2 Все блоки head1 и head2 из pod6 фалов, размещенных в каталоге includes
doc:Data::Dumper | code Все блоки code из документации к модулю Data::Dumper
file:/docs/**/*.md | head1 Поиск всех заголовков первого уровня во всех Markdown файлах из каталога "docs" и его дочерних папок.

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

    
 =toc <SELECTOR>

    Блок =toc используется для создания автоматически созданного оглавления (TOC) в документе. TOC служит в качестве индекса заголовков разделов в документе, и его структура определяется организацией документа.

    Например: 

     =toc head1, head2, head3, item1, item2, table

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

    Можно создавать списки таблиц или даже изображений: 

    
=for toc :title('Список таблиц')
table

=for toc :title('Список изображений')
Image, Diagram

    =include - Вставка блоков 

    
 =include <SELECTOR>

    Блок =include - мощный инструмент для повторного использования конкретных частей документов в исходных файлах проекта. Это особенно удобно при работе с сложными документами, которые требуют включения определенных разделов из разных файлов, сохраняя общий контекст и структуру.

    Этот блок отлично подходит для создания книг. Совместно с Селекторами он позволяет включать произвольные блоки из других документов и файлов.

    =picture, P< > - Вставка изображений

    Для вставки изображений можно использовать блок =picture: 

    
=picture site-menu.png
This is the menu rendered by the React component

    Может быть отрисовано так:

    Пример inline использования: 

     =para In the vast expanse of the cosmos, an intrepid P<astronaut|astronaut.png>
 floats weightlessly above the Earth.

    E<:hugging face:> - emoji 🤗

    Чтобы вставить коды эмодзи, вы можете использовать код E<> вместе с двоеточием и коротким именем эмодзи: 

    
    Podlite uses emoji codes to express emotions and actions,
    such as E<:thumbsup:> for approval and E<:smile:> for happiness.

    это отрисовывается как:

    Прототип встраивания кода E<>

    Для вставки математических формул используйте блок =formula с inline кодом F<>.

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

    Например: 

      =formula
  x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

  In a right triangle, the length of the hypotenuse can be calculated 
  using the Pythagorean theorem: F<a^2 + b^2 = c^2>.

  Euler's identity, F<e^{i\pi} + 1 = 0>, is a fundamental equation in
  complex analysis.

    может быть отрисовано как:

    Прототип отрисовки формул 

      =formula  :caption<Quadratic Formula> 
  x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

    может быть отрисовано как:

    Прототип формул с подписью

    =item, :checked - Списки задач

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

    Чтобы создать элемент списка задач, просто примените атрибут :checked к блоку =item. 

     =for item :checked
 Buy groceries
 =for item :!checked
 Clean the garage

    or 

     =item1 [ ] Work
   =item2 [ ] Prepare the presentation
   =item2 [x] Send emails
 =item1 [ ] Home
   =item2 [ ] Vacuum the living room
   =item2 [ ] Water the plants

    Что может выглядеть примерно так:

    Прототип чеклиста

    Вообще атрибут :checked может быть применен к любому типу блока. Например, к параграфу или заголовку )

    Контекстные обратные ссылки

    Да, это одна из идей, о которой я размышлял в последнее время.

    Контекстные обратные ссылки W<> (или contextual backlinks) улучшают традиционный механизм ссылок, позволяя не только ссылаться на другое место, но и предоставлять конкретный контекст вокруг этой ссылки.

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

    Например: 

     Этот текст может раскрывать значение W<glossoligation|defn:glossoligation>

    или: 

     Мы обсуждаем здесь W<doc:perldata>.

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

    • Интеграция с Markdown

    С прошлого года Podlite нативно поддерживает Markdown с использованием блока =Markdown. Это означает, что элементы Markdown переводятся в AST Podlite, что позволяет использовать функции, недоступные в Markdown, такие как автоматически создаваемые оглавления.

    Например: 

    =Toc head1, head2, head3

=head1 This is header1
=head2 Another header

=begin Markdown

# this is markdown header
## and this!

=end Markdown

    Этот документ будет выглядеть так:

    Автоматически созданное оглавление для Markdown

    Вы можете поиграть с примером здесь.

    Вот еще один пример, который я хотел бы воплотить: 

    
=include article.md
=include file:./includes/*.md

    Мне нравится идея дальнейшей интеграции c Markdown.

    Заключение

    Это некоторые из основных улучшений, которые приносит Podlite. Многие из этих предложений уже реализованы в Podlite и доказали свою практическую полезность.

    Я взял текущую спецификацию для Raku Pod (также известную как Synopsis 26), обновил и поместил все свои идеи в нее. Также представил ее как вариант для языка разметки Rakudoc.

    В результате получил:

    • 100% совместимый язык разметки с уже существующим форматом

    • такой же простой и элегантный язык разметки

    • так же расширяемый.

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

    Если есть у кого-то идеи, буду рад если пришлете их на адрес zag(at)cpan.org

    Спасибо

    Создание сайта/блога с помощью Podlite для Web
    ←↑→