Despite Pod6 remaining unchanged for an long time, the fact that its relevance is being addressed and progress is being made deserves admiration.


TITLE

DESCRIPTION

Today is a great day because I feel that some interesting changes are happening in an important aspect of my work.


Recently, I've become involved in the process of working on a new specification for the Pod6 markup language. Documentation is a crucial part of any programming language, and despite that, Pod6 has remained unchanged for quite a while. So, the fact that the relevance of Pod is being addressed and taking a step forward is truly commendable. I want to extend my sincere appreciation to you, Richard, for this.


As I started reviewing early version of Rakudoc, which Richard sent to me, I realized that I have a wealth of ideas and experience with Pod6 that I've been preparing for this moment. Z<However, these thoughts are currently swirling in my head, making it a bit challenging to take the first steps.>
They are needs to be organized, put into the text, and shared. It would also be beneficial to review ideas, previous work, revisit all the discussions that have taken place in the Raku/Doc community, which will require some time.

So, I've informed Richard that I'll be preparing my version of spec of the "next Pod". 


I estimate that this process will take around 3 weeks. Maybe a little bit less, or more.


I believe that considering multiple viewpoints will be highly beneficial, especially at this early stage.


To keep things focused and avoid any unintended consequences due to my own oversight, I've decided to work on this project in a quiet mode and will share a diary of my progress once the work is completed.


In addition to my work on the new Pod6 specification, I've also decided to take a pause on working on the next release of L<Podlite editor|https://github.com/podlite/podlite-desktop>.

root

Reinventing Pod6: Moving Forward


L<Podlite|https://podlite.org/> was born as a lightweight implementation of Raku Pod (also known as pod6), and over time, it has evolved into one of the most comprehensive implementations.

Podlite: Modernizing and Extending abandoned Raku Pod (ака pod6)


L<Podlite|https://podlite.org/> was born as a lightweight implementation of Raku Pod (also known as pod6), and over time, it has evolved into one of the most comprehensive implementations. It encompasses:

item

What's more, Podlite also supports Diagrams, auto-generated Table of Contents, and has built-in Markdown support.


I've been keeping daily journals in Raku Pod format for years and using Podlite to write blog articles. 


At this point, I've accumulated a bunch of ideas that go beyond the standard Raku Pod (aka pod6) L<specification|https://github.com/perl6/specs/blob/master/S26-documentation.pod>, along with some ideas I've been wanting to implement for a while. I've brought them all together, and I'd like to share the key ones in detail.

head

Podlite selectors are, in essence, quite similar to CSS selectors. They help identify and filter specific blocks within documents. Each selector pattern can contain optional block sources and block names.


code

=begin code :allow< R >
<EXTERNAL_SOURCE>
or
[ <EXTERNAL_SOURCE> | ] <BLOCKS_SELECTOR>
=end code

Selectors can be used not only to describe blocks within the current document but also in external documents:


table_head

    _______________________________________         ___________________________________________________


table_row

table

=begin table :nested

    Selector                                        Description
    _______________________________________         ___________________________________________________
    head1, head2, item1                             All head1, head2 and item1 blocks from document

    file:article.rakudoc | head1, head2                All head1 and head2 blocks from article.rakudoc file

    file:./includes/*.pod6 | head1, head2           All head1 and head2 blocks from pod6 files placed 
                                                    in includes directory

    doc:Data::Dumper | code                         All code blocks from a module documentation

    file:/docs/**/*.md | head1                      Search for first-level headers in all ".md" files within the "docs" directory and its subdirectories.
=end table


Selectors are an essential part that will be used in other sections.


=begin code :allow 

 Z<>=toc <SELECTOR>

=end code

The C<=toc> block is used to create an autogenerated table of contents (TOC) in a document. The TOC serves as an index of section titles within the document, and its structure is determined by the organization of the document.

=begin code
 =toc head1, head2, head3, item1, item2, table
=end code


In this block, a selector is used to describe the blocks used to build the TOC.


You can create lists of tables or even images:


=begin code :allow 

=for toc :title('List of tables')
table

=for toc :title('List of media')
Image, Diagram

=end code

=begin code :allow 

	=include <SELECTOR>

=end code

The C<=include> block is a powerful tool for reusing specific parts of documents within project sources. This is particularly handy
when dealing with complex documents that require to include certain 
sections from different files while keeping the overall context and 
structure intact.

This block is perfect for creating books. Combined with I<Selectors>, it allows you to include arbitrary blocks from other documents and files.

Z<>=picture, C< P<> > - Inserting pictures

To insert pictures, you can use the C<=picture> block:

=begin code :allow 

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

=end code

Image

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

=end code

To include emoji codes, you can use the C<E<>> code along 
with the colon-prefixed and postfix emoji shortname:

=begin code :allow 

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

=end code

caption

formula

The most exciting version of Podlite is available!
L<Podlite|https://github.com/zag/podlite-desktop> - 
 open-source desktop pod6 editor for Windows, Linux, and Mac.

The most important feature of this version is the support of another markup language!


C<=Markdown> block supports GitHub Flavored Markdown(L<GFM|https://github.github.com/gfm/>). It is the most popular Markdown variant and is used on Github.

L<Try it at Pod6.in|https://pod6.in/#p=%3Dbegin+Markdown%0A%0A++%23+%F0%9F%91%8B+here%21%0A++%0A++Now+**Markdown**+is+part+of+_Podlite_%21%0A++%0A++%7C+Syntax++++++%7C+Description+%7C%0A++%7C+-----------+%7C+-----------+%7C%0A++%7C+Header++++++%7C+Title+++++++%7C%0A++%7C+Paragraph+++%7C+Text++++++++%7C%0A++%0A++%60%60%60diagram+%0A++graph+LR%0A++++++++++A--%3EB%0A++++++++++B--%3EC%0A++++++++++C--%3EA%0A++++++++++D--%3EC%0A++%60%60%60%0A%0A%3Dend+Markdown%0A>

If you type the "=" symbol in the C<=Markdown> block, markdown templates will be suggested to you.

All features also available across the following tools: 


To get the latest version, please download it directly from L<Podlite releases page| https://github.com/podlite/podlite-desktop/releases>. It has a built-in auto-update feature and you will get updates as soon as possible.

Pre-build files: L<Podlite releases|https://github.com/zag/podlite-desktop/releases>.

React

=begin React :component<HeaderCol>
=for Image :link<https://www.microsoft.com/store/apps/9NVNT9SNQJM8>
ms-badge.png
=for Image :link<https://snapcraft.io/podlite>
snap-badge.png
=for Image :link<https://apps.apple.com/us/app/podlite/id1526511053>
mas_badge_black.png
=end React

Source code repository: L<Source code|https://github.com/zag/podlite-desktop>.

nested

Will look forward to your feedback on L<GitHub issue|https://github.com/zag/podlite-desktop/issues> page.