From a59f5d6affb241c3690624aaec7f9e8f6ed01bb9 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 25 Feb 2024 20:19:36 +0100 Subject: [PATCH 01/55] deprecate Contextual aliases --- Specification.pod6 | 96 ---------------------------------------------- 1 file changed, 96 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 65c8fba8..0712a87d 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2974,102 +2974,6 @@ text ever has to be changed, it need only be modified in a single place: =alias TERMS_URLS L =end code - -=head3 Contextual aliases - -If the C<=alias> directive is specified with only a single argument -(that is, with only its identifier), a D is created. In -this form, the C<=alias> directive must be followed immediately (on the -next non-blank line) by ambient code. - -The single argument is then used as the name of the alias being created, -and some portion of the following code is used as the value returned by the -alias macro. - -Note that the code block following the C<=alias> line is still treated -as real code by the Podlite parser, but its contents are I used to -create the replacement macro of the alias. This allows the developer to -reproduce chunks of actual source code directly in the documentation, -without having to copy it. - -If the code following the one-argument C<=alias> directive begins with a -sequence of one or more repetitions of any opening bracket character, -the replacement macro returns a string containing everything from the -end of that opening sequence to just before the corresponding closing -bracket sequence. For example: - -=begin code - - # This is actual code... - - sub hash_function ($key) - =alias HASHCODE - { - my $hash = 0; - for $key.split("") -> $char { - $hash = $hash*33 + $char.ord; - } - return $hash; - } - - =begin pod - An ancient (but fast) hashing algorithm is used: - - =begin code :allow - A - =end code - - =end pod -=end code - -This would produce: - -=begin nested -An ancient (but fast) hashing algorithm is used: - - my $hash = 0; - for $key.split("") -> $char { - $hash *= 33; - $hash += $char.ord; - } - return $hash; - -=end nested - -Alternatively, if the C<=alias> directive is I followed by an -opening bracket, it must be followed by a declarator (such as C, -C, C, etc.) The declared object then becomes the (read-only) -return value of the alias. For example: - -=begin code :allow - B<=alias CLASSNAME> - class Database::Handle { - B<=alias ATTR> - has IO $!handle; - - B<=alias OPEN> - my Bool method open ($filename?) {...} - - B<=alias DEFNAME> - constant Str DEFAULT_FILENAME = 'db.log'; - - =for para - Note that the B> method of class B> - stores the resulting low-level database handle - in its private B> attribute. By default, - handles are opened to the file "B>". - - } -=end code - -This would produce: - -=nested -Note that the C method of class C stores the -resulting low-level database handle in its private C<$!handle> -attribute. By default, handles are opened to the file "C". - - =begin SUMMARY =head2 Directives From 6716e4a3ddd56454b9d90103ed56a64b1b74bf93 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 25 Feb 2024 20:19:52 +0100 Subject: [PATCH 02/55] deprecate Contextual aliases --- Specification.pod6 | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index 0712a87d..f0833d2d 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -27,6 +27,10 @@ our L. =begin CHANGES +=head3 New: + +=head3 Deprecated/removed: + =item Contextual aliases =head2 1.0-beta2 =head3 New: =item embedding binary data into documents, C<=data>, C<:filename>, C<:encoding> From a9146140ece931729f426bc2e78a8d8278ac3d55 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 25 Feb 2024 20:20:50 +0100 Subject: [PATCH 03/55] fix align --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6e3e42d6..d11b8fe8 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Podlite aims to provide users with a means for creativity and expressing ideas i [The specification](https://github.com/podlite/podlite-specs/blob/main/Specification.pod6) for the Podlite markup language is written using Podlite markup itself. - +
##### specification @@ -66,3 +66,4 @@ Podlite aims to provide users with a means for creativity and expressing ideas i * [github.com/podlite](https://github.com/podlite/)
+
From 8a446ad3bd98b2304bec08ad1d362277db61e7e4 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Fri, 8 Mar 2024 08:51:18 +0100 Subject: [PATCH 04/55] rename FC to markup --- Specification.pod6 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index f0833d2d..798e4aef 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -801,18 +801,18 @@ code). Explicit C<=code> blocks may also contain empty lines. =head4 Formatting within code blocks -Although C<=code> blocks automatically disregard all L, occasionally you may still need to specify +Although C<=code> blocks automatically disregard all L, occasionally you may still need to specify some formatting within a code block. For example, you may wish to emphasize a particular keyword in an example (using a C> code). Or you may want to indicate that part of the example is metasyntactic (using the C> code). Or you might need to insert a non-ASCII character (using the C> code). -You can specify a list of formatting codes that should still be +You can specify a list of markup codes that should still be recognized within a code block using the C<:allow> option. The value of the C<:allow> option must be a list of the (single-letter) names of one -or more formatting codes. Those codes will then remain active inside the +or more markup codes. Those codes will then remain active inside the code block. For example: =begin code From 3566d7e0372a76a8969c32cdb5df419f90e3c006 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Fri, 8 Mar 2024 08:51:38 +0100 Subject: [PATCH 05/55] rename FC to markup --- Specification.pod6 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Specification.pod6 b/Specification.pod6 index 798e4aef..ceff9b00 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2145,7 +2145,7 @@ This block allows to seamlessly combine Podlite's structured blocks with the flexibility of Markdown. -=head2 Formatting codes +=head2 Markup codes Formatting codes provide a way to add inline mark-up to a piece of text within the contents of (most types of) Podlite block. Formatting codes are From 026eda5ec1a89425af1fab3f2d807625164fe1e9 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Fri, 8 Mar 2024 08:52:14 +0100 Subject: [PATCH 06/55] codes can contain only other markup codes --- Specification.pod6 | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index ceff9b00..4d79bb59 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2147,11 +2147,9 @@ the flexibility of Markdown. =head2 Markup codes -Formatting codes provide a way to add inline mark-up to a piece of text -within the contents of (most types of) Podlite block. Formatting codes are -themselves a type of block, and may nest other formatting codes. -other type of block (most often, other formatting codes). In particular, -you can nest comment blocks in the middle of a formatting code: +Markup codes enable inline markup within the text of (most) Pod block types. +They are a form of block that can contain only other markup codes. Specifically, +markup codes can nest: =begin code :allow V Date: Fri, 8 Mar 2024 08:52:34 +0100 Subject: [PATCH 07/55] rename FC to markup --- Specification.pod6 | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 4d79bb59..62f8ebc4 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2157,9 +2157,9 @@ markup codes can nest: and with emphasis.> =end code -All Podlite formatting codes consist of a single capital letter followed +All Podlite markup codes consist of a single capital letter followed immediately by a set of angle brackets. The brackets contain the text or -data to which the formatting code applies. You can use a set of single +data to which the markup code applies. You can use a set of single angles (C«<...>»), a set of double angles (C<«...»>), or multiple single-angles (C«<<<...>>>»). @@ -2366,24 +2366,24 @@ respective fonts should be used. =head3 Verbatim text -The C> formatting code treats its entire contents as being B, -disregarding every apparent formatting code within it. For example: +The C> markup code treats its entire contents as being B, +disregarding every apparent markup code within it. For example: - The B >> formatting code disarms other codes + The B >> markup code disarms other codes such as V< I<>, C<>, B<>, and M<> >. Note, however that the C> code only changes the way its contents are parsed, I the way they are rendered. That is, the contents are still wrapped and formatted like plain text, and the -effects of any formatting codes surrounding the C> code +effects of any markup codes surrounding the C> code are still applied to its contents. For example the previous example is rendered: =nested -The B >> formatting code disarms other codes +The B >> markup code disarms other codes such as V< I<>, C<>, B<>, and M<> >. -You can prespecify formatting codes that remain active within +You can prespecify markup codes that remain active within a C> code, using the L|#Formatting within code blocks> option. From d662419214ed07135a510b0ed68cf697dd8b99ac Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Fri, 8 Mar 2024 08:53:11 +0100 Subject: [PATCH 08/55] rename FC to markup --- Specification.pod6 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 62f8ebc4..1b13b32d 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2862,7 +2862,7 @@ information that is applied to every block of a particular type. =end code Here, two configurations are outlined. The first one sets -the language for code blocks to C and allows bold formatting +the language for code blocks to C and allows bold markup. The second establishes that all level 1 headings will be numbered. The general syntax for configuration directives is: @@ -2887,9 +2887,9 @@ previous example, to specify another langiage for code block: print(JSON.stringify([1,2]])); =end code -=head3 Pre-configuring formatting codes +=head3 Pre-configuring markup codes -You can also lexically preconfigure a L, +You can also lexically preconfigure a L, by naming it with a pair of angles as a suffix. For example: =begin code :allow @@ -2899,7 +2899,7 @@ by naming it with a pair of angles as a suffix. For example: B<=config C<> :allow> =end code -Note that, even though the formatting code is named using single-angles, +Note that, even though the markup code is named using single-angles, the preconfiguration applies regardless of the actual delimiters used on subsequent instances of the code. @@ -2909,7 +2909,7 @@ The C<=alias> directive provides a way to define lexically scoped synonyms for longer Podlite sequences, (meta)object declarators from the code, or even entire chunks of ambient source. These synonyms can then be inserted into subsequent Podlite using the -L formatting code>|#Alias placements>. +L markup code>|#Alias placements>. Note that C<=alias> is a fundamental Podlite directive, like C<=begin> or C<=for>; there are no equivalent paragraph or delimited forms. From 529e879b652b801c87724104128b5c646dfde77c Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Fri, 8 Mar 2024 08:53:32 +0100 Subject: [PATCH 09/55] tidy aliases --- Specification.pod6 | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 1b13b32d..42bbb58f 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2914,10 +2914,7 @@ L markup code>|#Alias placements>. Note that C<=alias> is a fundamental Podlite directive, like C<=begin> or C<=for>; there are no equivalent paragraph or delimited forms. -There are two forms of C<=alias> directive: macro aliases and contextual -aliases. Both forms are lexically scoped to the surrounding Podlite block. - -=head3 Macro aliases +Macro aliases are lexically scoped to the surrounding Podlite block. The simplest form of alias takes two arguments. The first is an identifier (which is usually specified in uppercase, though this is @@ -2926,7 +2923,7 @@ lines of replacement text. This creates a lexically scoped Podlite macro that can be invoked during document generation by placing the identifier (i.e. the first argument -of the alias) in an C> formatting code. This formatting code is then +of the alias) in an C> markup code. This markup code is then replaced by the text returned by new macro. The replacement text returned by the alias macro begins at the first From 142bfcbe1bc7920e91eb6631592028a372740e74 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Fri, 8 Mar 2024 08:53:44 +0100 Subject: [PATCH 10/55] rename FC to markup --- Specification.pod6 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 42bbb58f..86e8682a 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2390,7 +2390,7 @@ option. =head3 Inline comments -The C> formatting code indicates that its contents constitute a +The C> markup code indicates that its contents constitute a B, which should not be rendered by any renderer. For example: @@ -2407,7 +2407,7 @@ 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: +using a verbatim markup code: =begin code :allow In certain scenarios, the B«V>>» code is used to break up text that @@ -2422,7 +2422,7 @@ verbatim, which often eliminates the need for the C> as well: that would otherwise be considered mark-up. =end code -The C> formatting code is the inline equivalent of a +The C> markup code is the inline equivalent of a L block|#Comments>. =head3 Links From 5541bbcfa74c460464bc800b54acc48510b6591e Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Fri, 8 Mar 2024 08:54:29 +0100 Subject: [PATCH 11/55] C<> --- Specification.pod6 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 86e8682a..0d69b243 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -1965,8 +1965,8 @@ structure intact. The C<=include> block is followed by an L<"Selector"|#Selectors> that specifies the content to be included. -In this example, the content of the file "chapter01.pod6" located in the -"./includes" directory is included: +In this example, the content of the file C located in the +C<./includes> directory is included: =begin code =include file:./includes/chapter01.pod6 From f968f9d6b01061592565fdf05ec2556c57324a69 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Fri, 8 Mar 2024 08:55:37 +0100 Subject: [PATCH 12/55] rename FC to markup --- Specification.pod6 | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 0d69b243..bc6848c9 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2288,11 +2288,11 @@ term (or any of its specified synonyms) within a hypertext. =head3 Example specifiers -Podlite provides formatting codes for specifying inline examples of input, +Podlite provides markup codes for specifying inline examples of input, output, code, and metasyntax: =begin item -The C> formatting code specifies that the contained text is +The C> markup code specifies that the contained text is B; that is: something that a program might print out. Such content would typically be rendered in a T or with C< ... > tags. The contents of a C> code are always @@ -2302,25 +2302,25 @@ C<=output> block. =end item =begin item -The C> formatting code specifies that the contained text is +The C> markup code specifies that the contained text is B; that is: something that a user might type in. Such content would typically be rendered in a K (preferably a -different font from that used for the C> formatting code) or with +different font from that used for the C> markup code) or with C< ... > tags. The contents of a C> code are always L. The C> code is the inline equivalent of the C<=input> block. =end item =begin item -The C> formatting code specifies that the contained text is B; +The C> markup code specifies that the contained text is B; that is, something that might appear in a program or specification. Such content would typically be rendered in a C (preferably -a different font from that used for the C> or C> formatting +a different font from that used for the C> or C> markup codes) or with C< ... > tags. The contents of a C> code are L and L. The C> code is the inline equivalent of the C<=code> block. -To include other formatting codes in a C> code, you can lexically +To include other markup codes in a C> code, you can lexically L it: =begin code :allow @@ -2337,7 +2337,7 @@ at the top of the document =end item =begin item -The C> formatting code specifies that the contained text is a +The C> markup code specifies that the contained text is a B, a placeholder, or a metasyntactic variable. It is used to indicate a component of a syntax or specification that should eventually be replaced by an actual value. For example: From 908d3ab2c82f77e8ded47042cc2db6184ca8079b Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Fri, 8 Mar 2024 08:55:49 +0100 Subject: [PATCH 13/55] tidy --- Specification.pod6 | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index bc6848c9..ef8a1db7 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -472,15 +472,15 @@ values for the C<:lang> attribute: =begin table :caption("Matching languages and lang attribute values") - Programming Language Possible C<:lang> Values + Programming language Possible C<:lang> values - Python python - Raku raku - JavaScript javascript - Java java C++ cpp - HTML html CSS css + HTML html + Java java + JavaScript javascript + Python python + Raku raku =end table @@ -489,7 +489,7 @@ values for the C<:lang> attribute: =begin defn C<:allow> -This option expects a list of formatting codes that are to be recognized +This option expects a list of markup codes that are to be recognized within any C> codes that appear in (or are implicitly applied to) the current block. The option is most often used on C<=code> blocks to allow mark-up within those otherwise verbatim blocks, though it can be From 1aa1f7bb7babf20d432577a3768654b04eb8c285 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Fri, 8 Mar 2024 09:02:42 +0100 Subject: [PATCH 14/55] use block notation --- Specification.pod6 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Specification.pod6 b/Specification.pod6 index ef8a1db7..4a525b4e 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -544,7 +544,7 @@ between Podlite block names and their corresponding Markdown elements. Podlite Markdown Describtion _______________________________________ ______________ _____________________________________ - head1, head2, ... #, ##, ... Heading level 1,2... + C<=head1>, C<=head2>, ... #, ##, ... Heading level 1,2... C<=nested> ">" blockquote From 302d11386ab7bec49904abf0165674ffe7f641c1 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sat, 9 Mar 2024 19:27:41 +0100 Subject: [PATCH 15/55] rename FC to markup --- Specification.pod6 | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 4a525b4e..20ec9059 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -1362,7 +1362,6 @@ The preceding example could equally have been specified: B<=end nested> =end code - =head3 Tables Simple tables can be specified in Podlite using a C<=table> block. @@ -1408,7 +1407,7 @@ With header: Directive Specifies _________ ____________________________________________________ C<=begin> Start of an explicitly terminated block - C<=config> Lexical modifications to a block or formatting code + C<=config> Lexical modifications to a block or markup code =end table =end code @@ -2205,21 +2204,21 @@ user explicitly disables the warning). =head3 Significance indicators -Podlite provides three formatting codes that flag their contents with +Podlite provides three markup codes that flag their contents with increasing levels of significance: =item -The C> formatting code specifies that the contained text is +The C> markup code specifies that the contained text is B or distinctive; that it is of I. Typically such content would be rendered in an underlined style. =item -The C> formatting code specifies that the contained text is +The C> markup code specifies that the contained text is B; that it is of I. Such content would typically be rendered in italics or in C< ... > tags =item -The C> formatting code specifies that the contained text is the +The C> markup code specifies that the contained text is the B or focus of the surrounding text; that it is of I. Such content would typically be rendered in a bold style or in C< ... > tags. From 51fea387f5757b4c48475800750ae3edaa795f9a Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sat, 9 Mar 2024 19:28:17 +0100 Subject: [PATCH 16/55] fix M<> --- Specification.pod6 | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 20ec9059..8661803d 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2835,18 +2835,16 @@ 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 +In this example, the text C<"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. - 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. This feature enhances the flexibility and capability of Podlite documents, -enabling custom formatting and behavior that goes beyond standard markup features. - +enabling custom markup and behavior that goes beyond standard markup features. =head2 Block pre-configuration From 70d62ae4f1bb3c6752253bde8a4d0a85abbdfb57 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sat, 9 Mar 2024 19:28:33 +0100 Subject: [PATCH 17/55] rename FC to markup --- Specification.pod6 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 8661803d..3d38eff7 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2234,10 +2234,10 @@ mistake and should not be included in the document. =head3 Text positioning -Podlite provides two formatting codes that allow positioning characters or words. +Podlite provides two markup codes that allow positioning characters or words. =begin item -To create subscript text, you can use the C> formatting code, where 'J' represents +To create subscript text, you can use the C> markup code, where 'J' represents "Junior text." Subscript positions one or more characters slightly below the normal line of type. @@ -2248,7 +2248,7 @@ slightly below the baseline, as is often seen in chemical formulas like H₂O (w =end item =begin item -To create superscript text, it possible to use the C> formatting code, where 'H' +To create superscript text, it possible to use the C> markup code, where 'H' stands for "High text." Superscript positions one or more characters slightly above the normal line of type From 8cab54245a2fbd986620aa2382d2b2055bf3af64 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sat, 9 Mar 2024 19:30:25 +0100 Subject: [PATCH 18/55] rename FC to markup --- Specification.pod6 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 3d38eff7..e2ce3bfd 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -693,7 +693,7 @@ B<2.3.8.6.1.9. The Rescue of the Kobayashi Maru> Ordinary paragraph blocks consist of text that is to be formatted into a document at the current level of nesting, with whitespace -squeezed, lines filled, and any special L +squeezed, lines filled, and any special L applied. Ordinary paragraphs consist of one or more consecutive lines of text, @@ -754,7 +754,7 @@ blank lines are preserved. Code blocks are used to specify pre-formatted text (typically source code), which should be rendered without rejustification, without -whitespace-squeezing, and without recognizing any inline formatting +whitespace-squeezing, and without recognizing any inline markup codes. Code blocks also have an implicit L associated with them. Typically these blocks are used to show examples of code, mark-up, or other textual specifications, and are rendered @@ -2978,7 +2978,7 @@ text ever has to be changed, it need only be modified in a single place: Directive Specifies _________ ____________________________________________________ C<=begin> Start of an explicitly terminated block - C<=config> Lexical modifications to a block or formatting code + C<=config> Lexical modifications to a block or markup code C<=end> Explicit termination of a C<=begin> block C<=for> Start of an implicitly (blank-line) terminated block C<=alias> Define a Podlite macro @@ -3014,7 +3014,7 @@ text ever has to be changed, it need only be modified in a single place: =end table -=head2 Formatting codes +=head2 Inline markup codes =config C<> :allow =begin table :nested @@ -3041,7 +3041,7 @@ text ever has to be changed, it need only be modified in a single place: C> Space characters to be preserved C> Terminal output (typically rendered fixed-width) C> Unusual (typically rendered with underlining) - C<...>> Verbatim (internal formatting codes ignored) + C<...>> Verbatim (internal markup codes ignored) C> Contextual backlinks C> reserved C> Index entry (C|R,R;...>>) From 3b6d16f069fbcbe6072bd2d70e70cd31f0c46901 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sat, 9 Mar 2024 19:30:45 +0100 Subject: [PATCH 19/55] clean aliases --- Specification.pod6 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Specification.pod6 b/Specification.pod6 index e2ce3bfd..07dcb6be 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -127,7 +127,7 @@ within a Podlite block is treated as "ambient" material. Typically this 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>. +will I ignore such blocks. This is the D of the parser. All directives have a defined terminator and the Podlite parser always reverts to From e3ed4b8e4628e372f2366377f96bda590a8ed87d Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sat, 9 Mar 2024 19:31:33 +0100 Subject: [PATCH 20/55] rename FC to markup --- Specification.pod6 | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 07dcb6be..a057579b 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -832,8 +832,8 @@ would be rendered: =end code Note that the use of the C<:allow> option also makes it possible -for verbatim L (such as C> -and C>) to L. +for verbatim L (such as C> +and C>) to L. =head4 Assign programming language to code blocks @@ -1981,7 +1981,7 @@ of content from all the Markdown files: It's possible to include blocks from the same document being worked on. This feature proves valuable when reusing parts of existing content. -For instance, a semantic block "VERSION" can be included as demonstrated: +For instance, a semantic block C<=VERSION> can be included as demonstrated: =begin code :allow B<=include VERSION> @@ -2193,11 +2193,11 @@ or delimiters with more consecutive angles than your text contains: The Perl 5 heredoc syntax was: CB«<<<» <>>» =end code -A formatting code ends at the matching closing angle bracket(s), or at -the end of the enclosing block or formatting code in which the opening +A markup code ends at the matching closing angle bracket(s), or at +the end of the enclosing block or markup code in which the opening angle bracket was specified, whichever comes first (this includes paragraph and abbreviated blocks, ending with blank a line). Podlite parsers are -required to issue a warning whenever a formatting code is terminated by +required to issue a warning whenever a markup code is terminated by the end of an outer block rather than by its own delimiter (unless the user explicitly disables the warning). @@ -2261,7 +2261,7 @@ slightly above the baseline. This is commonly used for mathematical exponents, a =head3 Definitions -The C> formatting code indicates that the contained text is a +The C> markup code indicates that the contained text is a B, introducing a term that the adjacent text elucidates. It is the inline equivalent of a C<=defn> block. For example: @@ -2276,7 +2276,7 @@ A definition may be given synonyms, which are specified after a vertical bar and separated by semicolons: =begin code :allow - A B> provides a way + A B> provides a way to add inline mark-up to a piece of text. =end code From 92ffb383167ab582a843e618f86212a4e9ac316f Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 10:05:12 +0100 Subject: [PATCH 21/55] notification blocks --- Specification.pod6 | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/Specification.pod6 b/Specification.pod6 index a057579b..120af88c 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -28,7 +28,7 @@ our L. =begin CHANGES =head3 New: - + =item Notification blocks, C<:notify> attribute for C<=nested> blocks =head3 Deprecated/removed: =item Contextual aliases =head2 1.0-beta2 @@ -2970,6 +2970,25 @@ text ever has to be changed, it need only be modified in a single place: =alias TERMS_URLS L =end code +=head2 Notification blocks + +These blocks, often referred to as admonitions, callouts, or alerts, +serve to draw the reader's attention to different types of content, +such as tips, warnings, or important notes. + +To create specially formatted blocks to highlight information in Podlite +the =nested block and :notice attribute are utilized. + +For example: + +=begin code :allow + B<=begin nested> B<:notify> + Remember to always use oven mitts when handling hot bakeware + to prevent burns. + B<=end nested> +=end code + + =begin SUMMARY =head2 Directives From 96fe18bb3a12147b9d147e89ea560ecb0dfb8e5a Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 10:05:25 +0100 Subject: [PATCH 22/55] rename FC to markup --- Specification.pod6 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 120af88c..da5575fa 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -872,17 +872,17 @@ serifed for code, bold sans-serif for input, and regular sans-serif for output). Unlike C<=code> blocks, both C<=input> and C<=output> blocks honour any -nested formatting codes. This is particularly useful since a sample of +nested markup codes. This is particularly useful since a sample of input will often include prompts (which are, of course, output). Likewise a sample of output may contain the occasional interactive -component. Podlite provides L +component. Podlite provides L (C> and C>) to indicate embedded input or output, so you can use the block type that indicates the overall purpose of the sample (i.e. is it demonstrating an input operation or an output sequence?) and then use -the "contrasting" formatting code within the block. +the "contrasting" markup code within the block. For example, to include a small amount of input in a sample of output -you could use the C> formatting code: +you could use the C> markup code: =begin code :allow =begin output From 5ba9b252260558f6c979fc3a8eb47d656bd2e4c9 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 10:05:47 +0100 Subject: [PATCH 23/55] notification blocks --- Specification.pod6 | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index da5575fa..c2735bf6 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2989,6 +2989,19 @@ For example: =end code +It is possible to customize the title of the block and control the visibility +of the information using the foldable option. + +=begin code :allow + =begin nested B<:caption<"Astronaut's Reminder">> :notify B<:folded> + Space missions require meticulous planning and adherence to safety protocols. + Neglecting these can lead to mission failure or, worse, endanger lives. + =end nested +=end code + +Notification blocks are displayed with distinctive colors and +icons that indicate the significance of the content. + =begin SUMMARY =head2 Directives From ea6b5aec12e154ac8c319a7ed86f0de4a90ab7a9 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 10:06:06 +0100 Subject: [PATCH 24/55] types of notification blocks --- Specification.pod6 | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index c2735bf6..5b93d506 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2988,6 +2988,38 @@ For example: B<=end nested> =end code +Below is a table that outlines the different types of notification blocks +along with a brief description of each type. + +=begin table :caption<"Types of Notification blocks"> + + Type Description + ---------- ------------------------------------------------------ + note Provides additional information and context without + interrupting the flow of the main content + + tip Offers advice for doing things better or more easily + + important Signifies that the information is crucial for + understanding or success + + warning Indicates urgent information that requires immediate + attention to avoid potential problems + + caution Advises readers about potential negative outcomes or + risks associated with certain actions + +=end table + +=begin comment +TODO: +custom (e.g. `faq`, etc.)??? Allows for specifying the specific context or content. + + =begin nested :caption<"Foldable FAQ: Question 1"> :notice :folded + This is how you make content foldable for a cleaner look. + =end nested + +=end comment It is possible to customize the title of the block and control the visibility of the information using the foldable option. From e7c82374b6355ec7cc8f9567e198dea5ec663d48 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 16:12:32 +0100 Subject: [PATCH 25/55] itle-only callouts --- Specification.pod6 | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index 5b93d506..a749ca6f 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -3031,6 +3031,12 @@ of the information using the foldable option. =end nested =end code +It is possible to create title-only callouts by omitting the body. + +=begin code + =for nested :notify :folded :caption<"Title-only callout"> +=end code + Notification blocks are displayed with distinctive colors and icons that indicate the significance of the content. From fcc143b0eb58d3c4a9f1b275179ce092a93674e7 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 16:13:06 +0100 Subject: [PATCH 26/55] customize the title --- Specification.pod6 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Specification.pod6 b/Specification.pod6 index a749ca6f..02531050 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -3021,8 +3021,9 @@ custom (e.g. `faq`, etc.)??? Allows for specifying the specific context or =end comment +By default, the title of the notification block is its type identifier in title case. It is possible to customize the title of the block and control the visibility -of the information using the foldable option. +of the information using the C<:caption> and C<:folded> options. =begin code :allow =begin nested B<:caption<"Astronaut's Reminder">> :notify B<:folded> From c4206ab39bc7e3d7f07c5424cec953bddc316f6b Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 16:13:51 +0100 Subject: [PATCH 27/55] =toc :folded-levels attribute --- Specification.pod6 | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index 02531050..2e448df7 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -1947,6 +1947,17 @@ Note also that all L are treated as equivalent to C headings, and the C<=item1>/C<=item> equivalence is preserved. +The C<:folded-levels> attribute indicates which level of the TOC should +be folded. + +=begin code :allow + =for toc :folded-levels[2,3] :caption('Table of contents') + head1, head2, item1 +=end code + + +This allows for a highly customized folding configuration within the TOC. + The TOC is inserted at the location of the C<=toc> block. To enable the autogenerated TOC, controlled and maintained by render, set the C<:toc> From b1fea3628577fe7463f8086c7b74abc46fed7867 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 16:17:43 +0100 Subject: [PATCH 28/55] key-value pairs for :folded-levels --- Specification.pod6 | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index 2e448df7..c2484646 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -29,6 +29,7 @@ our L. =head3 New: =item Notification blocks, C<:notify> attribute for C<=nested> blocks + =item C<:folded-levels> for C<=toc> block =head3 Deprecated/removed: =item Contextual aliases =head2 1.0-beta2 @@ -1955,6 +1956,19 @@ be folded. head1, head2, item1 =end code +If the C<:folded-levels> attribute is provided with a set +of key-value pairs, it indicates the folding state of each +specified level. + +For example: + +=begin code :allow + =for toc B« :folded-levels< 2=>1, 4 => 1, 3=>0 > » + head1, head2, head3, item1, item2 +=end code + +The value C<0> for to level C<3> indicates that this level should +remain unfolded. Levels C<2> and C<4> are folded. This allows for a highly customized folding configuration within the TOC. From abb629408bb8aa2f64ba08b039333fe01c58c976 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 16:18:28 +0100 Subject: [PATCH 29/55] :folded attribute --- Specification.pod6 | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index c2484646..ba88417b 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -29,6 +29,7 @@ our L. =head3 New: =item Notification blocks, C<:notify> attribute for C<=nested> blocks + =item C<:folded> attribute =item C<:folded-levels> for C<=toc> block =head3 Deprecated/removed: =item Contextual aliases @@ -461,6 +462,15 @@ in the final rendered document. =end defn +=begin defn +C<:folded> + +This option specifies whether the block is foldable and, if specified, +whether it should be collapsed or expanded by default. This feature is +useful in managing the length of documents and focusing the reader's +attention on certain sections as needed. +=end defn + =begin defn C<:lang> From 027dd7735c823c9772cad934e54b7698ac1df1ed Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 16:19:07 +0100 Subject: [PATCH 30/55] :folded attribute --- Specification.pod6 | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index ba88417b..0d2d2c59 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -469,6 +469,29 @@ This option specifies whether the block is foldable and, if specified, whether it should be collapsed or expanded by default. This feature is useful in managing the length of documents and focusing the reader's attention on certain sections as needed. + +A C<:!folded> or C<:folded(0)> expands the callout by default, and a +C<:folded> or C<:folded(1)> collapses it instead. + +=begin code :allow + =for table B<:folded> :caption('Culinary Techniques for Sustainability') + Sous-vide Low energy consumption + ---------- ------------------------- + Steaming Preserves nutrients + Baking Efficient for batch cooking +=end code + +When applied to a block element, such as a heading, the attribute typically +affects all headings with lower-level content, creating a hierarchical +folding effect. + +For example: + +=begin code :allow + =for B + Green Energy Overview +=end code + =end defn =begin defn From fa315f186ede36d4d2ff5a8fd66c9b07cc0715d5 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 16:19:41 +0100 Subject: [PATCH 31/55] add comments --- Specification.pod6 | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index 0d2d2c59..351992e2 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -492,6 +492,25 @@ For example: Green Energy Overview =end code +=begin comment +TODO: my be it may sense to add a C<:folded-caption> attribute to +define a custom title for the collapsed block. + +The C<:folded-caption> attribute allows for defining a custom title +for the collapsed block. If no caption is provided, rendering systems +may automatically use the C<:caption> attribute. If the C<:caption> +attribute is not present, the first line or paragraph of the block +is used as the default title. For semantic blocks, the name of the +block can be used as the default title. + + +=begin code + =picture :folded(1) :folded-caption("Wind Turbine Fields") + Images/wind_turbines.jpg + Wind turbines stand tall against the sky, harnessing + the power of the wind to generate energy +=end code +=end comment =end defn =begin defn From 4fa9f3302c850728890e30aa3cded52d1117d69d Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 16:20:14 +0100 Subject: [PATCH 32/55] add examples for =config --- Specification.pod6 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Specification.pod6 b/Specification.pod6 index 351992e2..e64f0f41 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2026,7 +2026,7 @@ This allows for a highly customized folding configuration within the TOC. The TOC is inserted at the location of the C<=toc> block. -To enable the autogenerated TOC, controlled and maintained by render, set the C<:toc> +To enable the autogenerated TOC, controlled and maintained by render, set the C<:toc> document attribute for C<=pod> block. In this case, the specific configuration and outcome of the TOC are influenced by the settings of the concrete render implementation. @@ -2932,6 +2932,7 @@ information that is applied to every block of a particular type. =config code :lang :allow =config head1 :numbered + =config head2 :folded =end code From 06a71f8135807ea242c981751566149423dbd422 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 19:34:40 +0100 Subject: [PATCH 33/55] tidy --- Specification.pod6 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index e64f0f41..9e6abaab 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -351,8 +351,8 @@ applied uniformly to any built-in block type. These include: =begin defn C<:caption> -This option specifies that the block may be given an associated description or title using the -C<:caption> option. +This option specifies that the block may be given an associated description or +title using the C<:caption> option. Usually, this description uses for build L. From 6dcde74d97ef6e70e045e607673b46cf9a2a8d76 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 19:35:22 +0100 Subject: [PATCH 34/55] Clarification for doc: scheme --- Specification.pod6 | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 9e6abaab..ca2dbdf9 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2587,15 +2587,20 @@ A link to the system manpages. For example: =begin defn C -A link to some other documentation, typically a module or part of the -core documentation. +A link to other documents by utilizing semantic blocks +such as C<=TITLE> or C<=NAME> as anchor points for these links. + For example: =begin code :allow - You may wish to use L> to - view the results. See also: L>. + + B<=NAME Dumper> + + You may wish to use L> to + view the results. =end code + =end defn =begin defn From d6acc76d85828405507582b8323c989f5503a342 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 19:35:43 +0100 Subject: [PATCH 35/55] linking for doc: scheme --- Specification.pod6 | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index ca2dbdf9..ef9087e8 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2600,6 +2600,23 @@ For example: view the results. =end code +Moreover, the C scheme allows the use of an C<:id> attribute within +the C<=TITLE> or C<=NAME> blocks to create unique identifiers for document +linking. This ensures precision in navigation, as each identifier +corresponds to a specific part of the document set. An example would be: + +=begin code :allow + =for TITLE :id + The Specification of Podlite + + ... + + Read the L. + + ... +=end code + + =end defn From df279cb4a069ae3cd3c7c36e8ccc56880615d41d Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 19:36:04 +0100 Subject: [PATCH 36/55] Clarification for doc: scheme --- Specification.pod6 | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index ef9087e8..946b1f92 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2616,7 +2616,27 @@ corresponds to a specific part of the document set. An example would be: ... =end code +When Podlite processes a link, it can automatically use the document's title +from the C<=TITLE> or C<=NAME> blocks as the display text for the hyperlink if no +explicit text is provided. For example: +=begin code :allow + + =for TITLE :id + The Specification of Podlite + + =para + Please read "B>". + +=end code + +... will be rendered as: + +=begin code :allow + + Please read "B". + +=end code =end defn From 64719ea8175ef4cec659744cef2ac11088e27b1e Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Mar 2024 19:36:33 +0100 Subject: [PATCH 37/55] defailt value for :lang --- Specification.pod6 | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index 946b1f92..c3fa8af0 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -537,6 +537,9 @@ values for the C<:lang> attribute: =end table +If the language is not specified, the default language is used based +on the file extension or mime type of the current document. + =end defn =begin defn From 2f1099d52c779df7cc79f53f6efc61d8bcd631ac Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 17 Mar 2024 19:48:20 +0100 Subject: [PATCH 38/55] refactor Custom Blocks --- Specification.pod6 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Specification.pod6 b/Specification.pod6 index c3fa8af0..8d69327f 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -1688,7 +1688,7 @@ For example: =end code -=head3 Named blocks +=head3 Custom blocks Blocks whose names contain at least one uppercase and one lowercase letter are assumed to be destined for specialized renderers or parser @@ -1706,6 +1706,9 @@ or: =Image http://www.perlfoundation.org/images/perl_logo_32x104.png =end code +Alongside the verbatim or placeholder content, the renderer could provide +an unobtrusive yet informative error message, explaining that the Custom block +could not be processed. Note that all block names consisting entirely of lowercase or entirely of uppercase letters are reserved. See L<#Semantic blocks>. From fa3ccd3279cc16b8c3cc36b0c419bfff2a5f1c64 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Tue, 19 Mar 2024 08:34:01 +0100 Subject: [PATCH 39/55] tidy formatiing --- Specification.pod6 | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 8d69327f..c30248de 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -758,22 +758,22 @@ each of which starts with a non-whitespace character at (virtual) column directive. For example: =begin code - =head1 This is a heading block - - This is an ordinary paragraph. - Its text will be squeezed and - short lines filled. It is terminated by - the first blank line. - - This is another ordinary paragraph. - Its text will also be squeezed and - short lines filled. It is terminated by - the trailing directive on the next line. - =head2 This is another heading block - - This is yet another ordinary paragraph, - at the first virtual column set by the - previous directive + =head1 This is a heading block + + This is an ordinary paragraph. + Its text will be squeezed and + short lines filled. It is terminated by + the first blank line. + + This is another ordinary paragraph. + Its text will also be squeezed and + short lines filled. It is terminated by + the trailing directive on the next line. + =head2 This is another heading block + + This is yet another ordinary paragraph, + at the first virtual column set by the + previous directive =end code Within a C<=pod>, C<=item>, C<=defn>, C<=nested>, or From e673898b12097811e13fb22d09fa4bcac89ca7c7 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Tue, 19 Mar 2024 08:34:25 +0100 Subject: [PATCH 40/55] tidy formatiing --- Specification.pod6 | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index c30248de..68163ca1 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -144,15 +144,15 @@ To keep the parser in "pod" mode, enclose the desired Podlite region in a C block: =begin code :allow - B<=begin pod> + B<=begin pod> - =head1 A heading + =head1 A heading - This is Podlite too. Specifically, this is a simple C block + This is Podlite too. Specifically, this is a simple C block - $this = pod('also'); # Specifically, a code block + $this = pod('also'); # Specifically, a code block - B<=end pod> + B<=end pod> =end code The contents of files with the extensions '.podlite' and '.pod6' are @@ -835,17 +835,17 @@ There is also an explicit C<=code> block (which can be specified within I other block type, not just C<=pod>, C<=item>, etc.): =begin code :allow - The C subroutine adds feedback: + The C subroutine adds feedback: - B<=begin code> + B<=begin code> - sub loud_update ($who, $status) { - say "$who -> $status"; + sub loud_update ($who, $status) { + say "$who -> $status"; - silent_update($who, $status); - } + silent_update($who, $status); + } - B<=end code> + B<=end code> =end code As the previous example demonstrates, within an explicit C<=code> block From 44797a7cc2d40034c79e80378b2276e92631a2c9 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Tue, 19 Mar 2024 08:35:33 +0100 Subject: [PATCH 41/55] uniform style of instruction --- Specification.pod6 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 68163ca1..c696f730 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -141,7 +141,7 @@ 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: +in a C<=pod> block: =begin code :allow B<=begin pod> @@ -1760,7 +1760,7 @@ use the following syntax: 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: +the C schema. For example: =begin code =begin data :key :mime-type @@ -2326,8 +2326,8 @@ line of type. HJ<2>O -This code renders as "H2O," which signifies that the '2' is positioned -slightly below the baseline, as is often seen in chemical formulas like H₂O (water). +This code renders as C2O>, which signifies that the '2' is positioned +slightly below the baseline, as is often seen in chemical formulas like C (water). =end item =begin item @@ -2337,8 +2337,8 @@ above the normal line of type XH<2> -This code renders as "X2," indicating that the '2' is positioned -slightly above the baseline. This is commonly used for mathematical exponents, as in X². +This code renders as C2>, indicating that the C<'2'> is positioned +slightly above the baseline. This is commonly used for mathematical exponents, as in C. =end item From 2345cbff33f85a16b717ea18f63f7df10659aa4a Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Tue, 19 Mar 2024 08:36:03 +0100 Subject: [PATCH 42/55] tidy formatiing examples --- Specification.pod6 | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index c696f730..7510fdec 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -941,19 +941,19 @@ For example, to include a small amount of input in a sample of output you could use the C> markup code: =begin code :allow - =begin output - Name: Baracus, B.A. - Rank: Sgt - Serial: 1PTDF007 - - Do you want additional personnel details? B> - - Height: 180cm/5'11" - Weight: 104kg/230lb - Age: 49 - - Print? B> - =end output + =begin output + Name: Baracus, B.A. + Rank: Sgt + Serial: 1PTDF007 + + Do you want additional personnel details? B> + + Height: 180cm/5'11" + Weight: 104kg/230lb + Age: 49 + + Print? B> + =end output =end code @@ -2978,9 +2978,9 @@ information that is applied to every block of a particular type. =begin code - =config code :lang :allow - =config head1 :numbered - =config head2 :folded + =config code :lang :allow + =config head1 :numbered + =config head2 :folded =end code From dd1586e8bae9376de9e97977b1c8c92677b26e4e Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 20 Mar 2024 09:05:17 +0100 Subject: [PATCH 43/55] tidy formatiing examples --- Specification.pod6 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 7510fdec..b89dec55 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -3016,10 +3016,10 @@ You can also lexically preconfigure a L, by naming it with a pair of angles as a suffix. For example: =begin code :allow - =comment Always allow E<> codes in any (implicit or explicit) V<> code... - B<=config V<> :allow> - =comment All inline code allows I<> - B<=config C<> :allow> + =comment Always allow E<> codes in any (implicit or explicit) V<> code... + B«=config V<> :allow» + =comment All inline code allows I<> + B«=config C<> :allow» =end code Note that, even though the markup code is named using single-angles, From ae4350ae12024de25588562492369605fd03b1fb Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 20 Mar 2024 09:05:48 +0100 Subject: [PATCH 44/55] use notification block --- Specification.pod6 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index b89dec55..5bc2c2b0 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -5,8 +5,7 @@ This file is deliberately specified in Podlite format =TITLE Podlite - a lightweight markup language -=begin nested -B +=begin nested :notify :caption('This document is still being worked on!') It's not finished yet, but it's available for everyone to see and comment on. This way, it can get better with everyone's input. From a88395b635806728293333284bc030aa7d854786 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 20 Mar 2024 09:10:28 +0100 Subject: [PATCH 45/55] tidy formatiing examples --- Specification.pod6 | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 5bc2c2b0..57e873e5 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -2050,7 +2050,7 @@ In this example, the content of the file C located in the C<./includes> directory is included: =begin code - =include file:./includes/chapter01.pod6 +=include file:./includes/chapter01.pod6 =end code A wildcard L<"Selector"|#Selectors> serves this purpose, enabling inclusion @@ -2532,7 +2532,7 @@ A standard web URL. For example: =begin code :allow This module needs the LAME library - (available from LZ<>>) + (available from L>) =end code If the link does not start with C it is treated as being relative to @@ -2598,11 +2598,10 @@ such as C<=TITLE> or C<=NAME> as anchor points for these links. For example: =begin code :allow - - B<=NAME Dumper> - - You may wish to use L> to - view the results. + B<=NAME Dumper> + + You may wish to use L> to + view the results. =end code Moreover, the C scheme allows the use of an C<:id> attribute within @@ -2627,8 +2626,8 @@ explicit text is provided. For example: =begin code :allow - =for TITLE :id - The Specification of Podlite + =for TITLE :id + The Specification of Podlite =para Please read "B>". From 4cdf0e4171dcbd58d5ca0234095f14987bc1f069 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 20 Mar 2024 09:11:11 +0100 Subject: [PATCH 46/55] tidy formatiing examples --- Specification.pod6 | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 57e873e5..45c04f73 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -993,15 +993,15 @@ C<=item1>, C<=item2>, C<=item3>, etc. blocks. Note that C<=item> is just an abbreviation for C<=item1>. For example: =begin code - =item1 Animal - =item2 Vertebrate - =item2 Invertebrate - - =item1 Phase - =item2 Solid - =item2 Liquid - =item2 Gas - =item2 Chocolate + =item1 Animal + =item2 Vertebrate + =item2 Invertebrate + + =item1 Phase + =item2 Solid + =item2 Liquid + =item2 Gas + =item2 Chocolate =end code which would be rendered something like: @@ -3001,7 +3001,7 @@ block or file in which it is specified. Note that, if a particular block later explicitly specifies a configuration option with the same key, that option overrides the pre-configured option. For example, given the code blocks configurations in the -previous example, to specify another langiage for code block: +previous example, to specify another language for code block: =begin code =for code :lang From f187bb57d1093d3a635757767f7fe8e6e6860404 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 20 Mar 2024 09:11:35 +0100 Subject: [PATCH 47/55] tidy formatiing examples --- Specification.pod6 | 48 +++++++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 45c04f73..3e1d780c 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -632,13 +632,13 @@ Podlite provides an unlimited number of levels of heading, specified by the C<=head>R block marker. For example: =begin code - =head1 A Top Level Heading + =head1 A Top Level Heading - =head2 A Second Level Heading + =head2 A Second Level Heading - =head3 A third level heading + =head3 A third level heading - =head86 A "Missed it by I much!" heading + =head86 A "Missed it by I much!" heading =end code While Podlite parsers are required to recognize and distinguish all levels @@ -655,26 +655,26 @@ You can specify that a heading is numbered using the C<:numbered> option. For example: =begin code - =for head1 :numbered - The Problem - - =for head1 :numbered - The Solution - - =for head2 :numbered - Analysis - - =for head3 - Overview - - =for head3 - Details - - =for head2 :numbered - Design - - =for head1 :numbered - The Implementation + =for head1 :numbered + The Problem + + =for head1 :numbered + The Solution + + =for head2 :numbered + Analysis + + =for head3 + Overview + + =for head3 + Details + + =for head2 :numbered + Design + + =for head1 :numbered + The Implementation =end code which would produce: From 303819b40deddff7b1888877c1558304844e8b6c Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 20 Mar 2024 09:12:00 +0100 Subject: [PATCH 48/55] tidy formatiing examples --- Specification.pod6 | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 3e1d780c..5f818fc7 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -721,13 +721,13 @@ in a heading consists of a single literal C<#> character, the C<#> is removed and the heading is treated as if it had a C<:numbered> option: =begin code - =head1 # The Problem - =head1 # The Solution - =head2 # Analysis - =head3 Overview - =head3 Details - =head2 # Design - =head1 # The Implementation + =head1 # The Problem + =head1 # The Solution + =head2 # Analysis + =head3 Overview + =head3 Details + =head2 # Design + =head1 # The Implementation =end code Note that, even though renderers are not required to distinctly render @@ -963,15 +963,15 @@ special "container" directives or other delimiters are required to enclose the entire list. For example: =begin code - The seven suspects are: - - =item Happy - =item Dopey - =item Sleepy - =item Bashful - =item Sneezy - =item Grumpy - =item Keyser Soze + The seven suspects are: + + =item Happy + =item Dopey + =item Sleepy + =item Bashful + =item Sneezy + =item Grumpy + =item Keyser Soze =end code List items have one implicit level of nesting: From 98948207d4253111988e16bf8ecdfdb9a5fa734f Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 20 Mar 2024 09:12:35 +0100 Subject: [PATCH 49/55] tidy formatiing examples --- Specification.pod6 | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 5f818fc7..f73fd269 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -781,23 +781,23 @@ an explicit marker or delimiters, but there is also an explicit C marker (which may be used anywhere): =begin code :allow - B<=para> - This is an ordinary paragraph. - Its text will be squeezed and - short lines filled. + B<=para> + This is an ordinary paragraph. + Its text will be squeezed and + short lines filled. =end code and likewise the longer C<=for> and C<=begin>/C<=end> forms. For example: =begin code :allow - B<=begin para> - This is an ordinary paragraph. - Its text will be squeezed and - short lines filled. - - This is I part of the same paragraph, - which continues until an... - B<=end para> + B<=begin para> + This is an ordinary paragraph. + Its text will be squeezed and + short lines filled. + + This is I part of the same paragraph, + which continues until an... + B<=end para> =end code As the previous example implies, when any form of explicit C block From ba19648d2427f7f11ecc099065a62203088642fd Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 20 Mar 2024 09:13:03 +0100 Subject: [PATCH 50/55] uniform style of instruction --- Specification.pod6 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index f73fd269..e932f581 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -154,10 +154,10 @@ in a C<=pod> block: B<=end pod> =end code -The contents of files with the extensions '.podlite' and '.pod6' are +The contents of files with the extensions C<.podlite> and C<.pod6> are implicitly wrapped in a C<=pod> directive. -For '.md' and '.markdown' files, the parser operates in D<"Markdown" +For C<.md> and C<.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. @@ -800,7 +800,7 @@ and likewise the longer C<=for> and C<=begin>/C<=end> forms. For example: B<=end para> =end code -As the previous example implies, when any form of explicit C block +As the previous example implies, when any form of explicit C<=para> block is used, any whitespace at the start of each line is removed during rendering. In addition, within a delimited C<=begin para>/C<=end para> block, any blank lines are preserved. From 27290510072a0465502d759b2add51e01bc70a10 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 20 Mar 2024 09:13:20 +0100 Subject: [PATCH 51/55] tidy formatiing examples --- Specification.pod6 | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index e932f581..bc6a0086 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -703,17 +703,17 @@ It is usually better to preset a numbering scheme for each heading level, in a series of L: =begin code :allow - B<=config head1 :numbered - Z<>=config head2 :numbered - Z<>=config head3 :!numbered> - - =head1 The Problem - =head1 The Solution - =head2 Analysis - =head3 Overview - =head3 Details - =head2 Design - =head1 The Implementation + B<=config head1 :numbered + Z<>=config head2 :numbered + Z<>=config head3 :!numbered> + + =head1 The Problem + =head1 The Solution + =head2 Analysis + =head3 Overview + =head3 Details + =head2 Design + =head1 The Implementation =end code Alternatively, as a short-hand, if the first whitespace-delimited word From 7618a92b7f8d354016f5d609c0ffa383fea0451f Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Thu, 21 Mar 2024 09:00:36 +0100 Subject: [PATCH 52/55] adjust formatting --- Specification.pod6 | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index bc6a0086..277be4ca 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -34,16 +34,16 @@ our L. =item Contextual aliases =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 + =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 C> - extends inline markup features. =head3 Deprecated/removed: - =item C<=finish> - =item markers in comments + =item C<=finish>, + =item markers in comments. =head2 1.0-beta1 =head3 New: @@ -54,13 +54,13 @@ our L. =item include block, C<=include>, =item inserting pictures, C<=picture>, C>, =item mathematical formulas, C<=formula>, C>, - =item Markdown support, C<=markdown> + =item Markdown support, C<=markdown>, =item mistake marking, C>, =item text positioning, C>, C>, =item Emoji, C>, - =item contextual backlinks, C> + =item contextual backlinks, C>, =item advanced table format, C<=row>,C<=cell> blocks, - C<:header>, C<:rowspan>, C<:colspan> attributes, + C<:header>, C<:rowspan>, C<:colspan> attributes. =head3 Deprecated/removed: =item C<:margin> attribute, @@ -70,7 +70,7 @@ our L. =item C> - placement links, =item Declarator block, =item C<:formatted> attribute, - =item C<:like> attribute + =item C<:like> attribute. =end CHANGES @@ -821,10 +821,10 @@ left margin. The implicit code block is then terminated by a blank line. For example: =begin code - This ordinary paragraph introduces a code block: + This ordinary paragraph introduces a code block: - $this = 1 * code('block'); - $which.is_specified(:by); + $this = 1 * code('block'); + $which.is_specified(:by); =end code Implicit code blocks may only be used within C<=pod>, C<=item>, C<=defn>, From 9366e2456960d1e88d52a5f80473501e6e235289 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Thu, 21 Mar 2024 09:01:57 +0100 Subject: [PATCH 53/55] update CHANGES --- Specification.pod6 | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Specification.pod6 b/Specification.pod6 index 277be4ca..58f0e2a9 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -27,6 +27,9 @@ our L. =begin CHANGES =head3 New: + =item Notification blocks, C<:notify> attribute for C<=nested> blocks, + =item C<:folded> attribute, + =item C<:folded-levels> for C<=toc> block, =item Notification blocks, C<:notify> attribute for C<=nested> blocks =item C<:folded> attribute =item C<:folded-levels> for C<=toc> block From d565b2838166adf63e619af3c574754ff56ef7c2 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Tue, 26 Mar 2024 08:32:52 +0100 Subject: [PATCH 54/55] tidy --- Specification.pod6 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index 58f0e2a9..b179dcc2 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -22,10 +22,11 @@ our L. =item Aliaksandr Zahatski |mailto:zag@cpan.org>> =end AUTHORS -=VERSION 1.0-beta2 +=VERSION 1.0-beta3 =begin CHANGES +=head2 1.0-beta3 =head3 New: =item Notification blocks, C<:notify> attribute for C<=nested> blocks, =item C<:folded> attribute, @@ -2310,7 +2311,7 @@ in C< ... > tags. =head3 Mistake marking -It possible strikethrough words using the code C, where 'O' stands +It possible strikethrough words using the code C>, where 'O' stands for "Overstrike." This is a way to indicate that certain words are a mistake and should not be included in the document. From cae636d5adf0548a2b6dbd46f3e0a8459210f0e1 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Tue, 26 Mar 2024 08:38:20 +0100 Subject: [PATCH 55/55] fix changes --- Specification.pod6 | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Specification.pod6 b/Specification.pod6 index b179dcc2..5e121a32 100644 --- a/Specification.pod6 +++ b/Specification.pod6 @@ -31,9 +31,7 @@ our L. =item Notification blocks, C<:notify> attribute for C<=nested> blocks, =item C<:folded> attribute, =item C<:folded-levels> for C<=toc> block, - =item Notification blocks, C<:notify> attribute for C<=nested> blocks - =item C<:folded> attribute - =item C<:folded-levels> for C<=toc> block + =item Refactor custom blocks and markup codes, C>. =head3 Deprecated/removed: =item Contextual aliases =head2 1.0-beta2