diff --git a/README.md b/README.md index 076dcaec..6e3e42d6 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ -**Podlite is a block-based markup language designed for flexibility and ease of use.** +**Podlite is a lightweight block-based markup language designed for flexibility and ease of use.** Unbound by any specific domain, programming language, or concept, Podlite stands out as a universal markup language. It's versatile enough to be successfully implemented across various development fields, from web development to scientific research. @@ -18,3 +18,51 @@ One of the key features of Podlite is its extensibility. This allows for definin Its flexibility makes it an ideal tool for creating documentation, blogs, educational materials, and much more. Podlite aims to provide users with a means for creativity and expressing ideas in a structured form, while ensuring ease of use and high flexibility in content creation. + + +[The specification](https://github.com/podlite/podlite-specs/blob/main/Specification.pod6) for the Podlite markup language is written using Podlite markup itself. + + +
+ +##### specification + +
+ +* [Source](https://github.com/podlite/podlite-specs) +* [in HTML](https://podlite.org/specification) +* [Discussions](https://github.com/podlite/podlite-specs/discussions) +* [Implementation](https://github.com/podlite/podlite) + +
+ +##### publishing system + +
+ +* [Podlite-web](https://github.com/podlite/podlite-web) +* [How-to article](https://zahatski.com/2022/8/23/1/start-you-own-blog-site-with-podlite-for-web) +* [Issues](https://github.com/podlite/podlite-specs/issues) + +
+ +##### desktop viewer/editor + +
+ +* [Podlite-desktop](https://github.com/podlite/podlite-desktop) +* [Releases](https://github.com/podlite/podlite-desktop/releases) +* [Issues](https://github.com/podlite/podlite-desktop/issues) + +
+ +##### online resurces + +
+ + +* [podlite.org](https://podlite.org) +* [pod6.in](https://pod6.in/) +* [github.com/podlite](https://github.com/podlite/) + +
diff --git a/S26-documentation.pod6 b/Specification.pod6 similarity index 91% rename from S26-documentation.pod6 rename to Specification.pod6 index 8d99d2e1..65c8fba8 100644 --- a/S26-documentation.pod6 +++ b/Specification.pod6 @@ -16,18 +16,31 @@ you're welcome to suggest changes or start a conversation on our L. =end nested -=Toc head1, head2,head3 +=toc head1, head2, head3 =begin AUTHORS =item Damian Conway |mailto:damian@conway.org>> =item Aliaksandr Zahatski |mailto:zag@cpan.org>> =end AUTHORS -=VERSION 1.0.0-beta1 +=VERSION 1.0-beta2 =begin CHANGES -=head2 1.0.0-beta1 +=head2 1.0-beta2 +=head3 New: + =item embedding binary data into documents, C<=data>, C<:filename>, C<:encoding> + =item C<:mime-type> attribute for C<=include> and C<=data> blocks + =item introduce С schema for use in =picture and C<=table> + =item render tables from CSV files, C<=table> + =item new markdown mode for parser + =item M<> - extends inline markup features + +=head3 Deprecated/removed: + =item C<=finish> + =item markers in comments + +=head2 1.0-beta1 =head3 New: =item add C<:id>, C<:caption>, C<:lang> attributes, =item task lists, C<=item> and C<:checked> attribute, @@ -111,11 +124,18 @@ would be the source code of the program that the Podlite is documenting. Podlite parsers still parse this text into the internal representation of the file, representing it as a "ambient" block. Renderers will I ignore such blocks, but see L<#Aliases>. +This is the D of the parser. All directives have a defined terminator and the Podlite parser always reverts to D<"ambient"|Ambient mode; parser modes> at the end of each Podlite directive or -block. To cause the parser to remain in "Pod" mode, you must enclose the desired -Podlite region in a C block: +block. + +The C<=pod> block puts the parser in D<"pod" mode|Pod mode; parser modes>, +treating all text between blocks as implicit paragraph Podlite, even if +it's not inside an explicit block. + +To keep the parser in "pod" mode, enclose the desired Podlite region +in a C block: =begin code :allow B<=begin pod> @@ -129,15 +149,17 @@ Podlite region in a C block: B<=end pod> =end code -The contents of files with the extensions '.pod6' and '.podlite' are -implicitly wrapped in a C<=pod> directive. This puts the parser in -D<"Pod" mode|Pod mode; parser modes> for the entire file, treating - all text as Podlite even if it's not inside an explicit block. +The contents of files with the extensions '.podlite' and '.pod6' are +implicitly wrapped in a C<=pod> directive. For '.md' and '.markdown' files, the parser operates in D<"Markdown" mode|Markdown mode; parser modes> for the entire file, treating all text as markdown even if it is not inside an C<=markdown> block. +Any other file extension puts the parser in default mode. The L +block|#Include block > has a mechanism to override this behavior by using +the C<:mime-type> attribute for the included files. + =head3 Delimited blocks Delimited blocks are bounded by C<=begin> and C<=end> markers, both of @@ -694,7 +716,7 @@ directive. For example: previous directive =end code -Within a C<=pod>, C<=item>, C<=defn>, C<=nested>, C<=finish>, or +Within a C<=pod>, C<=item>, C<=defn>, C<=nested>, or L block, ordinary paragraphs do not require an explicit marker or delimiters, but there is also an explicit C marker (which may be used anywhere): @@ -747,7 +769,7 @@ For example: =end code Implicit code blocks may only be used within C<=pod>, C<=item>, C<=defn>, -C<=nested>, C<=finish>, or L blocks. +C<=nested>, or L blocks. There is also an explicit C<=code> block (which can be specified within I other block type, not just C<=pod>, C<=item>, etc.): @@ -790,19 +812,19 @@ or more formatting codes. Those codes will then remain active inside the code block. For example: =begin code - =begin code :allow< B R > - sub demo { - B 'Hello R'; - } - =end code + =begin code :allow< B R > + sub demo { + B 'Hello R'; + } + =end code =end code would be rendered: =begin code :allow< B R > -sub demo { - B 'Hello R'; -} + sub demo { + B 'Hello R'; + } =end code Note that the use of the C<:allow> option also makes it possible @@ -819,11 +841,11 @@ renderers or syntax highlighting tools. For example: =begin code :allow - =begin code B<:lang> - sub demo { - say 'Hello R'; - } - =end code + =begin code B<:lang> + sub demo { + say 'Hello R'; + } + =end code =end code @@ -1144,8 +1166,8 @@ attribute to C<=item> block. The rendered output looks like this: - [ ] Buy groceries - [X] Clean the garage + [X] Buy groceries + [ ] Clean the garage Alternatively, if item content starts with brackets with space (C<[ ]>) the item is treated as having a C<:!checked> attribute. @@ -1154,8 +1176,8 @@ of C<:checked> attribute. For example: =begin code :allow - =item B<[ ]> Buy groceries - =itme B<[x]> Clean the garage + =item B<[x]> Buy groceries + =itme B<[ ]> Clean the garage =end code It possiible to create multilevel to-do lists, which permits the @@ -1392,14 +1414,15 @@ Or: =begin code =begin table - Programming Language Possible Values + Energy Source Benefit - Python python - Raku raku - HTML html - CSS css - - =end table + Solar power Reduces electricity bills + Wind energy Clean power source + Hydroelectric power Highly efficient + Geothermal energy Low emissions + Biomass Reduces waste + +=end table =end code or line-by-line with multi-line headers: @@ -1545,7 +1568,7 @@ It draw somethink like this: | Item and Quantity | Description | |----------------------------------|--------------------------| | Apples | 5 | | - |--------------|-------------------| Fruit for snacking | + |--------------|-------------------| Fruit for snacking | | Bananas | 3 | | --------------------------------------------------------------- @@ -1582,6 +1605,30 @@ For example: =end code +=head4 Table from CSV files or data blocks + +It is possible to create tables from files or data blocks. +To do this, use the C or C schema in the first non-blank line +to specify the source of the table data. +For example: + +=begin code :allow + =table B + + =for table :caption('Basic cake recipe ingredients') + B + + =begin data :key :mime-type + ingredient,quantity,unit + flour,2,cups + sugar,1,cups + eggs,2,items + butter,0.5,cups + baking powder,2,teaspoons + =end data +=end code + + =head3 Named blocks Blocks whose names contain at least one uppercase and one lowercase @@ -1632,79 +1679,126 @@ and for temporarily removing parts of a document: B<=end comment> =end code -=head3 The C<=finish> block +=head3 Data blocks -The C<=finish> block is special in that all three of its forms -(L, L, and -L) are terminated only by the end of the -current file. That is, neither C<=finish> nor C<=for finish> are terminated by the -next blank line, and C<=end finish> has no effect within a C<=begin finish> block. -A warning is issued if an explicit C<=end finish> appears within a document. +The C<=data> block is used to embed various types of data directly into a document. -An C<=finish> block indicates the end-point of any ambient material within -the document. This means that the parser will treat all the remaining -text in the file as Pod, even if it is not inside an explicit block. In -other words, apart from its special end-of-file termination behaviour, -an C<=finish> block is in all other respects identical to a C<=pod> block. +For example, to include a CSV file in a document, it is possible to +use the following syntax: +=begin code :allow -=head3 Data blocks + =begin data :key :mime-type + name,month,amount + John Doe,January,1000 + Jane Doe,February,1500 + =end data -This section is not yet implemented +=end code -=begin comment +Each C<=data> block can be given a C<:key> option, to name it. The contents +of any C<=data> block with a key are addressable via +the C schema. For example: -Named Podlite blocks whose typename is C are the Podlite equivalent of -the Perl 5 C<__DATA__> section. The difference is that C<=data> blocks are -just regular Podlite blocks and may appear anywhere within a source file, and as -many times as required. +=begin code + =begin data :key :mime-type + id,name,position,department + 1,John Doe,Manager,Marketing + 2,Jane Smith,Developer,Engineering + 3,Bob Brown,Designer,Product + =end data -There is a corresponding variable, C<$=data>, from which each C<=data> block -can be retrieved. C<$=data> holds an object that does both the Associative -and Positional roles. + =table data:employee_data -Each C<=data> block can be given a C<:key> option, to name it. The contents -of any C<=data> block with a key are accessible (as a single string) via -the Associative aspect of C<$=data> object. For example: +=end code -=begin code :allow +Each =data block can include several attributes to provide additional information +about the contained data: - =begin data :key - Laziness - Impatience - Hubris - =end data +=begin defn +C<:filename> - say 'The three virtues are:'; - say $=data; +This option specifies the original file name of the embedded data, which +can be used to hint at the type of data contained if the C<:mime/type> is not +explicitly provided. +=end defn -=end code +=begin defn +C<:mime-type> + +This option indicates the MIME type of the data, such as C for PNG images, +which helps in determining how the data should be interpretered and processed. + +Here is a list of few well-known mime types and their corresponding file extensions: + +=table + MIME Type | File Extension + ------------------ | -------------- + text/plain | .txt + text/markdown | .md, .markdown + text/podlite | .podlite, .pod6 + application/json | .json + application/xml | .xml + image/jpeg | .jpg, .jpeg + image/png | .png + application/pdf | .pdf + application/zip | .zip + audio/mpeg | .mp3 + video/mp4 | .mp4 + application/msword | .doc, .docx + text/csv | .csv + text/tab-separated-values | .tsv, .tab -The contents of any C<=data> block that does not have a C<:key> are -accessible (as a single string) via the Positional aspect of -C<$=data>. Unkeyed C<=data> blocks are stored in the same order -they appear in the file. For example: +=end defn + +=begin defn +C<:access-time> and C<:modify-time> + +This attributes record time for when the data was last accessed or +edited. + +=end defn + +=begin defn +C + +This option specifies the encoding method used to store the data. +For non-text data, such as images in the PNG format, +the encoding method C is used. +=end defn + +Example of storing images in C<=data> blocks: =begin code :allow - say 'The second anti_Virtue is: ', $=data[1]; + =begin data :key :filename :mime-type + = :access-time<2022-01-01T00:00:00Z> :modify-time<2022-01-02T10:00:00Z> + = :encoding + iVBORw0KGgoAAAANSUhEUgAAAAMAAAAFCAYAAACAcVaiAAAAS0lEQVR4AWPOPfjpvWZSW4db + ZLk+kwTHP24HUQYGfi4WTiZVAcYfDtIMDCJc/38xK6TWth37wcrw7cufF8yeeWUGrL8Z33Ey + /t0HAMBnF2nt5sNRAAAAAElFTkSuQmCC + =end data - =data Industry - =data Patience - =data Humility + =picture data:Logo =end code +In the example above, we have a C<=data> block with C<:id> C that stores +the base64-encoded image data. We also specify the filename, mime type, +access time, and edit time as attributes of the C<=data> block. + +The image can then be referenced using the `=picture` block with the scheme +C and the block name C. + + +The C<=data> blocks are just regular Podlite blocks and may appear anywhere +within a source file, and as many times as required. + Note that in Podlite, it is possible to specify C<=data> blocks I the point in the source where their contents will be used. -When C<$=data> itself is stringified, it returns the concatenation of all -the unkeyed C<=data> blocks the parser has seen. - C<=data> blocks are never rendered by the standard Podlite renderers. - -=end comment =head3 Semantic blocks All uppercase block typenames are reserved for specifying standard @@ -1898,6 +1992,22 @@ or, equivalently: =VERSION 1.0.0 =end code +Podlite detects type of the included file by its extension. +For example, if the included file has a C<.md> extension, +it is treated as a Markdown file. + +To override the type of the included file by extension, you can use the C<:mime-type> +attribute. This attribute allows you to specify the MIME type of the included file. +For example: + +=begin code + =for include :mime-type('text/podlite') + file:./includes/text.txt +=end code + +The C<:mime-type> attribute is particularly useful when including files with +extensions that do not match their actual MIME type. + It's crucial to think about security concerns, as adding content from external sources could potentially create vulnerabilities such as injecting harmful code or malicious material. Tools responsible for displaying and handling the content @@ -1918,7 +2028,8 @@ The first non-blank line of content within the C<=picture> block specifies the source of the image and the remaining content is treated as caption. This source can be either local or remote, and it can be -indicated using different schemas: C for remote images or C for local ones. +indicated using different schemas: C for remote images, C for +local ones, or C for L in to the document. If no schema is provided, it defaults to C. =begin code :allow @@ -1926,6 +2037,7 @@ If no schema is provided, it defaults to C. =picture file:/local/image.png =picture /local/image.png =picture ../image.png + =picture data:Logo =end code Following the source line, it possible to include an image caption. @@ -2025,7 +2137,7 @@ content within Podlite documents. This is achieved using the C<=markdown> block. =end markdown =end code -This block allows to seamlessly combine Pod's structured blocks with +This block allows to seamlessly combine Podlite's structured blocks with the flexibility of Markdown. @@ -2285,20 +2397,19 @@ For example: to quit all applications. =end code -In Perl 5 POD, the C> code was widely used to break up text that would -otherwise be considered mark-up: - +In certain scenarios, the C> code is used to break up text that +would otherwise be considered mark-up: =begin code :allow - In Perl 5 POD, the ZB><> code was widely used to break up text - that would otherwise be considered mark-up. + In certain scenarios, the ZB><> code is used to break up text that + would otherwise be considered mark-up. =end code That technique still works, but it's now easier to accomplish the same goal using a verbatim formatting code: =begin code :allow - In Perl 5 POD, the B«V>>» code was widely used to break up text - that would otherwise be considered mark-up. + In certain scenarios, the B«V>>» code is used to break up text that + would otherwise be considered mark-up. =end code Moreover, the C> code automatically treats its contents as being @@ -2312,24 +2423,6 @@ verbatim, which often eliminates the need for the C> as well: The C> formatting code is the inline equivalent of a L block|#Comments>. -=head4 Comments as category markers - -Most Podlite renderers will provide a mechanism that allows particular Pod -blocks to be explicitly excluded or included if they match a particular -pattern. For example, a renderer might be instructed to omit any block -that contains the pattern C. Corresponding "invisibility -markers" can then be placed inside C> comments within any block that -should not normally be displayed. For example: - -=for code :allow - class Widget is Bauble - { - has $.things; #= a collection of other stuff - #={ Z - This variable needs to be replaced for political reasons - } - } - =head3 Links The C> code is used to specify all kinds of links, filenames, citations, @@ -2465,7 +2558,7 @@ Serial Number for a publication. For example: =end defn -To refer to a specific section within a webpage, manpage, or Pod +To refer to a specific section within a webpage, manpage, or Podlite document, add the name of that section after the main link, separated by a C<#>. For example: @@ -2719,42 +2812,40 @@ E Plants grow without soil, using mineral nutrient solutions. =end nested -=head3 Module-defined formatting codes +=head3 Module-defined handler for extends markup features -This section is not yet implemented +The C> code in Podlite extends the language's capabilities by allowing users +to specify additional processing instructions within their documents. +This is achieved by combining content text with a custom scheme specifier, +followed by extra content that is passed verbatim to a handler function. -=begin comment -Modules loaded with a L|#How Podlite is parsed and processed> -can define classes that implement new formatting codes, which can -then be specified using the C> code. An C> code must start with -a colon-terminated scheme specifier. The rest of the enclosed text is -treated as the (verbatim) contents of the formatting code. For example: +The structure of the C> markup code as follows: -=begin code :allow - DOC use Pod::TT; + M< CONTENT-TEXT|SCHEME: VERBATIM_EXTRA_CONTENT> - =head1 Overview of the B> class - (version B>) +This syntax includes an optional CONTENT-TEXT section, followed by a + scheme specifier (SCHEME:) and then the VERBATIM_EXTRA_CONTENT. +The scheme specifier should follow the same rules as for L. +The scheme specifier allows the verbatim extra content (VERBATIM_EXTRA_CONTENT), +which may include additional attributes or instructions for the markup code handler. + +An example of how this code might be used is : + +=for code :allow + B This text is highlighted in yellowB<|Marker: yellow>>. + +In this example, the text s "This text is highlighted in yellow"> is subject +to special handling specified by the C scheme and C, indicating +that the textshould be highlighted in yellow. - B> -=end code -The C> formatting code is the inline equivalent of a -L. +If the C is unrecognized, the content text (CONTENT-TEXT) should be +rendered as ordinary text. This ensures that documents remain readable even +if specific processing instructions cannot be executed. -Internally an C> code is converted to an object derived from the -C class. The name of the scheme becomes -the final component of the object's classname. For instance, the C> -code in the previous example would be converted to a -C object, whose C<.typename> -method retrieves the string C<"TT"> and whose C<.contents> -method retrieves a list of the formatting code's (verbatim, -unformatted) contents. +This feature enhances the flexibility and capability of Podlite documents, +enabling custom formatting and behavior that goes beyond standard markup features. -If the formatting code is unrecognized, the contents of the code (i.e. -everything after the first colon) would normally be rendered as -ordinary text. -=end comment =head2 Block pre-configuration @@ -3013,7 +3104,6 @@ attribute. By default, handles are opened to the file "C". C<=pod> No "ambient" blocks inside C<=table> Simple rectangular table C<=data> Data section - C<=finish> No ambient blocks after this point C<=toc> Autogenerated table of contents C<=include> Include other blocks, documents C<=picture> Inserting pictures diff --git a/assets/bigtitle-social-logo.png b/assets/bigtitle-social-logo.png new file mode 100644 index 00000000..a7c8d5d8 Binary files /dev/null and b/assets/bigtitle-social-logo.png differ