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

    Спасибо