34 |
35 | ##### specification
36 |
37 |
38 |
39 | * [Source](https://github.com/podlite/podlite-specs)
40 | * [in HTML](https://podlite.org/specification)
41 | * [Discussions](https://github.com/podlite/podlite-specs/discussions)
42 | * [Implementation](https://github.com/podlite/podlite)
43 |
44 | |
45 |
46 | ##### publishing system
47 |
48 |
49 |
50 | * [Podlite-web](https://github.com/podlite/podlite-web)
51 | * [How-to article](https://zahatski.com/2022/8/23/1/start-you-own-blog-site-with-podlite-for-web)
52 | * [Issues](https://github.com/podlite/podlite-specs/issues)
53 |
54 | |
55 |
56 | ##### desktop viewer/editor
57 |
58 |
59 |
60 | * [Podlite-desktop](https://github.com/podlite/podlite-desktop)
61 | * [Releases](https://github.com/podlite/podlite-desktop/releases)
62 | * [Issues](https://github.com/podlite/podlite-desktop/issues)
63 |
64 | |
65 |
66 | ##### online resurces
67 |
68 |
69 |
70 |
71 | * [podlite.org](https://podlite.org)
72 | * [pod6.in](https://pod6.in/)
73 | * [github.com/podlite](https://github.com/podlite/)
74 |
75 | |
. Indented text is only treated as code within
194 | C<=pod>, L|#Nesting blocks>, L|#Lists>, C<=code>,
195 | and L blocks.
196 |
197 | The general syntax is:
198 |
199 | =begin code :allow< R >
200 | =begin R R
201 | = R
202 | R
203 | =end R
204 | =end code
205 |
206 | For example:
207 |
208 | =begin code
209 | =begin table :caption
210 | Constants 1
211 |
212 | Variables 10
213 |
214 | Subroutines 33
215 |
216 | Everything else 57
217 | =end table
218 |
219 | =begin Name :required
220 | = :width(50)
221 | The applicant's full name
222 | =end Name
223 |
224 | =begin Contact :optional
225 | The applicant's contact details
226 | =end Contact
227 | =end code
228 |
229 | Note that no blank lines are required around the directives; blank
230 | lines within the contents are always treated as part of the contents.
231 | This is a universal feature of Podlite.
232 |
233 | Note also that in the following specifications, a "blank line" is a line
234 | that is either empty or that contains only whitespace characters. That
235 | is, a blank line matches the following pattern: C. Podlite uses
236 | blank lines as delimiters, rather than empty lines, to minimize unpleasant
237 | surprises when stray spaces or tabs mysteriously turn up in hitherto
238 | empty lines.
239 |
240 |
241 | =head3 Paragraph blocks
242 |
243 | Paragraph blocks are introduced by a C<=for> marker and terminated by
244 | the next Podlite directive or the first blank line (which is I
245 | considered to be part of the block's contents). The C<=for> marker is
246 | followed by the name of the block and optional configuration
247 | information. The general syntax is:
248 |
249 | =begin code :allow< R >
250 | =for R R
251 | = R
252 | R
253 | =end code
254 |
255 | For example:
256 |
257 | =begin code
258 | =for table :caption
259 | Constants 1
260 | Variables 10
261 | Subroutines 33
262 | Everything else 57
263 |
264 | =for Name :required
265 | = :width(50)
266 | The applicant's full name
267 |
268 | =for Contact :optional
269 | The applicant's contact details
270 |
271 | =end code
272 |
273 |
274 | =head3 Abbreviated blocks
275 |
276 | Abbreviated blocks are introduced by an C<'='> sign in the
277 | first column, which is followed immediately by the typename of the
278 | block. The rest of the line is treated as block data, rather than as
279 | configuration. The content terminates at the next Podlite directive or the
280 | first blank line (which is not part of the block data). The general
281 | syntax is:
282 |
283 | =begin code :allow< R >
284 | =R R
285 | R
286 |
287 | =end code
288 |
289 | For example:
290 |
291 | =begin code
292 | =table
293 | Constants 1
294 | Variables 10
295 | Subroutines 33
296 | Everything else 57
297 |
298 | =Name The applicant's full name
299 | =Contact The applicant's contact details
300 |
301 | =end code
302 |
303 | Note that abbreviated blocks cannot specify configuration information. If
304 | configuration is required, use a C<=for> or C<=begin>/C<=end> instead.
305 |
306 |
307 | =head3 Block equivalence
308 |
309 | The underlying documentation model treats all block
310 | specifications (delimited, paragraph, and abbreviated) the same way.
311 | It is possible to choose the form is most convenient for a particular
312 | documentation task. In the descriptions that follow, the abbreviated
313 | form will generally be used, but should be read as standing for all
314 | three forms equally.
315 |
316 | For example, although L<#Headings> shows only:
317 |
318 | =begin code
319 | =head1 Top Level Heading
320 | =end code
321 |
322 | this automatically implies that you could also write that block as:
323 |
324 | =begin code
325 | =for head1
326 | Top Level Heading
327 | =end code
328 |
329 | or:
330 |
331 | =begin code
332 | =begin head1
333 | Top Level Heading
334 | =end head1
335 | =end code
336 |
337 |
338 | =head3 Standard configuration options
339 |
340 | Podlite predefines a small number of standard configuration options that can be
341 | applied uniformly to any built-in block type. These include:
342 |
343 | =begin defn
344 | C<:caption>
345 |
346 | This option assigns a title to the given block, which is typically used to create
347 | a L.
348 |
349 | =end defn
350 |
351 | =begin defn
352 | C<:id>
353 |
354 | This option enables the explicit definition of identifiers for blocks and use those
355 | IDs for linking purposes (see L<#Links>).
356 |
357 | =end defn
358 |
359 | =begin defn
360 | C<:nested>
361 |
362 | This option specifies that the block is to be nested within its current
363 | context. For example, nesting might be applied to block quotes, to textual
364 | examples, or to commentaries. In addition the L|#Code blocks>,
365 | L|#Lists>, L|#I/O blocks>, and L|#I/O blocks>
366 | blocks all have implicit nesting.
367 |
368 | Nesting of blocks is usually rendered by adding extra indentation to the
369 | block contents, but may also be indicated in other ways:
370 | by boxing the contents, by changing the font or size of the nested text,
371 | or even by folding the text (so long as a visible placeholder is provided).
372 |
373 | Occasionally it is desirable to nest content by more than one level:
374 |
375 | =begin code
376 | =begin para :nested
377 | =begin para :nested
378 | =begin para :nested
379 | "We're going deep, deep, deep undercover!"
380 | =end para
381 | =end para
382 | =end para
383 | =end code
384 |
385 | This can be simplified by giving the C<:nested> option a positive integer
386 | value:
387 |
388 | =begin code :allow
389 | =begin para B<:nested(3)>
390 | "We're going deep, deep, deep undercover!"
391 | =end para
392 | =end code
393 |
394 | You can also give the option a value of zero, to defeat any implicit
395 | nesting that might normally be applied to a paragraph. For example, to
396 | specify a block of code that should appear I its usual
397 | nesting:
398 |
399 | =begin code :allow
400 | =comment Don't nest this code block in the usual way...
401 | B<=begin code :nested(0)>
402 |
403 | 1 2 3 4 5 6
404 | 123456789012345678901234567890123456789012345678901234567890
405 | |------|-----------------------|---------------------------|
406 | line instruction comments
407 | number code
408 |
409 | V<=end code>
410 | =end code
411 |
412 | Note that C<:!nested> could also be used for this purpose:
413 |
414 | =begin code
415 | =Z<>begin code :!nested
416 | =end code
417 |
418 | =end defn
419 |
420 | =begin defn
421 | C<:numbered>
422 |
423 | This option specifies that the block is to be numbered. The most common
424 | use of this option is to create L and
425 | L, but it can be applied to any block.
426 |
427 | The numbering conventions for headings and lists are specified in those
428 | sections, but it is up to individual renderers to decide how to display
429 | any numbering associated with other types of blocks.
430 |
431 | Note that numbering is never explicit; it is always implied by context.
432 |
433 | =end defn
434 |
435 | =begin defn
436 | C<:checked>
437 |
438 | This attribute indicates that a checkbox should be added to that block.
439 | It is possible to apply a C<:checked> attributes to any block.
440 | The most common use of this option is to create L.
441 |
442 | For an unchecked checkbox the C<:!checked> is used.
443 |
444 | The task list item marker (checkbox) is added to the output.
445 | In HTML output, this would be represented as an
446 | C<> element.
447 |
448 | The specification does not define how these checkboxes are interacted with.
449 | Implementors are free to choose whether they render them as disabled,
450 | unchangeable elements, or handle dynamic interactions like checking and unchecking
451 | in the final rendered document.
452 |
453 | =end defn
454 |
455 | =begin defn
456 | C<:folded>
457 |
458 | This option specifies whether the block is foldable and, if specified,
459 | whether it should be collapsed or expanded by default. This feature is
460 | useful in managing the length of documents and focusing the reader's
461 | attention on certain sections as needed.
462 |
463 | A C<:!folded> or C<:folded(0)> expands the callout by default, and a
464 | C<:folded> or C<:folded(1)> collapses it instead.
465 |
466 | =begin code :allow
467 | =for table B<:folded> :caption('Culinary Techniques for Sustainability')
468 | Sous-vide Low energy consumption
469 | ---------- -------------------------
470 | Steaming Preserves nutrients
471 | Baking Efficient for batch cooking
472 | =end code
473 |
474 | When applied to a block element, such as a heading, the attribute typically
475 | affects all headings with lower-level content, creating a hierarchical
476 | folding effect.
477 |
478 | For example:
479 |
480 | =begin code :allow
481 | =for B
482 | Green Energy Overview
483 | =end code
484 |
485 | =begin comment
486 | TODO: my be it may sense to add a C<:folded-caption> attribute to
487 | define a custom title for the collapsed block.
488 |
489 | The C<:folded-caption> attribute enables the definition of a custom title
490 | for the collapsed block. If no caption is provided, rendering systems
491 | may automatically use the C<:caption> attribute. In the absence of
492 | the C<:caption> attribute, the first line or paragraph of the block
493 | serves as the default title. For semantic blocks, the name of the block
494 | may be used as the default title.
495 |
496 |
497 | =begin code
498 | =picture :folded(1) :folded-caption("Wind Turbine Fields")
499 | Images/wind_turbines.jpg
500 | Wind turbines stand tall against the sky, harnessing
501 | the power of the wind to generate energy
502 | =end code
503 | =end comment
504 | =end defn
505 |
506 | =begin defn
507 | C<:lang>
508 |
509 | This option is used to L about the programming language used in a specific code block.
511 | This helps ensure that the code is displayed and interpreted correctly
512 | by rendering engines or syntax highlighters.
513 |
514 | Here's a table that lists a few programming languages along with their possible
515 | values for the C<:lang> attribute:
516 |
517 | =begin table :caption("Matching languages and lang attribute values")
518 |
519 | Programming language Possible C<:lang> values
520 | -------------------- -------------------------
521 | C++ cpp
522 | CSS css
523 | HTML html
524 | Java java
525 | JavaScript javascript
526 | Python python
527 | Raku raku
528 |
529 | =end table
530 |
531 | If the language is not specified, the default language is used based
532 | on the file extension or mime type of the current document.
533 |
534 | =end defn
535 |
536 | =begin defn
537 | C<:allow>
538 |
539 | This option expects a list of markup codes that are to be recognized
540 | within any C> codes that appear in (or are implicitly applied to)
541 | the current block. The option is most often used on C<=code> blocks to
542 | allow mark-up within those otherwise verbatim blocks, though it can be
543 | used in I block that contains verbatim text. See L<#Formatting
544 | within code blocks>.
545 |
546 | =end defn
547 |
548 | =head2 Selectors
549 |
550 | Selectors consist of patterns that help identify and filter specific blocks
551 | within documents. Each pattern contains optional source of blocks and block names.
552 |
553 | The general syntax is:
554 |
555 | =begin code :allow< R >
556 | R
557 | or
558 | [ R | ] R
559 | =end code
560 |
561 | ...where
562 |
563 | =item EXTERNAL_SOURCE - optional source of blocks for filtering, default current document,
564 | =item BLOCK_SELECTOR - list of block names, filter for
565 |
566 | For example:
567 |
568 | =begin table :nested
569 |
570 | Selector Description
571 | _______________________________________ ___________________________________________________
572 | head1, head2, item1 all head1, head2 and item1 blocks from document
573 |
574 | file:article.pod6 | head1, head2 all head1 and head2 blocks from article.pod6 file
575 |
576 | file:./includes/*.pod6 | head1, head2 all head1 and head2 blocks from pod6 files placed
577 | in includes directory
578 |
579 | doc:Data::Dumper | code all code blocks from a module documentation
580 |
581 | file:/docs/**/*.md | head1 search headers with first level for all ".md" files
582 | within the "docs" directory and its subdirectories.
583 |
584 | =end table
585 |
586 | Please note that while the Selector blocks provide a way to query and filter specific elements
587 | within Markdown files, Markdown itself doesn't have formal named blocks like the Podlite syntax.
588 | Instead, Markdown uses a lightweight markup to structure content. The above table provides a mapping
589 | between Podlite block names and their corresponding Markdown elements.
590 |
591 | =begin table :nested :caption("A table of correspondences for some Podlite blocks and markdown blocks")
592 |
593 | Podlite Markdown Describtion
594 | _______________________________________ ______________ _____________________________________
595 | C<=head1>, C<=head2>, ... #, ##, ... Heading level 1,2...
596 |
597 | C<=nested> ">" blockquote
598 |
599 | C<=para> block of text paragraph
600 |
601 | C> [^1]: footnote. footnote
602 |
603 | C<=Html> text HTML block
604 |
605 | C> ~~text~~ Strikethrough, "O for Overstrike"
606 |
607 | C> ^text^ Superscript, "H for High text"
608 |
609 | C> ~text~ Subscript, "J for Junior text"
610 |
611 | C>, C<=formula> $,$$, ```math Mathematical formulas
612 |
613 | =end table
614 |
615 | The most common use of Selectors is to create L and
616 | in L.
617 |
618 | =head2 Block types
619 |
620 | Podlite offers notations for specifying a wide range of standard block types...
621 |
622 |
623 | =head3 Headings
624 |
625 | Podlite provides an unlimited number of levels of heading, specified by the
626 | C<=head>R block marker. For example:
627 |
628 | =begin code
629 | =head1 A Top Level Heading
630 |
631 | =head2 A Second Level Heading
632 |
633 | =head3 A third level heading
634 |
635 | =head86 A "Missed it by I much!" heading
636 | =end code
637 |
638 | While Podlite parsers are required to recognize and distinguish all levels
639 | of heading, Podlite renderers are only required to provide distinct
640 | I of the first four levels of heading (though they may, of
641 | course, provide more than that). Headings at levels without distinct
642 | renderings would typically be rendered like the lowest distinctly
643 | rendered level.
644 |
645 |
646 | =head4 Numbered headings
647 |
648 | You can specify that a heading is numbered using the C<:numbered> option. For
649 | example:
650 |
651 | =begin code
652 | =for head1 :numbered
653 | The Problem
654 |
655 | =for head1 :numbered
656 | The Solution
657 |
658 | =for head2 :numbered
659 | Analysis
660 |
661 | =for head3
662 | Overview
663 |
664 | =for head3
665 | Details
666 |
667 | =for head2 :numbered
668 | Design
669 |
670 | =for head1 :numbered
671 | The Implementation
672 | =end code
673 |
674 | which would produce:
675 |
676 | =begin nested
677 | 1. The Problem
678 |
679 | 2. The Solution
680 |
681 | =begin nested
682 | 2.1. Analysis
683 |
684 | =begin nested
685 | Overview
686 |
687 | Details
688 | =end nested
689 |
690 | 2.2: Design
691 | =end nested
692 |
693 | 3. The Implementation
694 | =end nested
695 |
696 | It is usually better to preset a numbering scheme for each heading
697 | level, in a series of L:
698 |
699 | =begin code :allow
700 | B<=config head1 :numbered
701 | Z<>=config head2 :numbered
702 | Z<>=config head3 :!numbered>
703 |
704 | =head1 The Problem
705 | =head1 The Solution
706 | =head2 Analysis
707 | =head3 Overview
708 | =head3 Details
709 | =head2 Design
710 | =head1 The Implementation
711 | =end code
712 |
713 | Alternatively, as a short-hand, if the first whitespace-delimited word
714 | in a heading consists of a single literal C<#> character, the C<#> is
715 | removed and the heading is treated as if it had a C<:numbered> option:
716 |
717 | =begin code
718 | =head1 # The Problem
719 | =head1 # The Solution
720 | =head2 # Analysis
721 | =head3 Overview
722 | =head3 Details
723 | =head2 # Design
724 | =head1 # The Implementation
725 | =end code
726 |
727 | Note that, even though renderers are not required to distinctly render
728 | more than the first four levels of heading, they I required to
729 | correctly honour arbitrarily nested numberings. That is:
730 |
731 | =begin code
732 | =head6 # The Rescue of the Kobayashi Maru
733 | =end code
734 |
735 | should produce something like:
736 |
737 | =nested
738 | B<2.3.8.6.1.9. The Rescue of the Kobayashi Maru>
739 |
740 |
741 | =head3 Ordinary paragraph blocks
742 |
743 | Ordinary paragraph blocks consist of text that is to be formatted into
744 | a document at the current level of nesting, with whitespace
745 | squeezed, lines filled, and any special L
746 | applied.
747 |
748 | Ordinary paragraphs consist of one or more consecutive lines of text,
749 | each of which starts with a non-whitespace character at (virtual) column
750 | 1. The paragraph is terminated by the first blank line or block
751 | directive. For example:
752 |
753 | =begin code
754 | =head1 This is a heading block
755 |
756 | This is an ordinary paragraph.
757 | Its text will be squeezed and
758 | short lines filled. It is terminated by
759 | the first blank line.
760 |
761 | This is another ordinary paragraph.
762 | Its text will also be squeezed and
763 | short lines filled. It is terminated by
764 | the trailing directive on the next line.
765 | =head2 This is another heading block
766 |
767 | This is yet another ordinary paragraph,
768 | at the first virtual column set by the
769 | previous directive
770 | =end code
771 |
772 | Within a C<=pod>, C<=item>, C<=defn>, C<=nested>, or
773 | L block, ordinary paragraphs do not require
774 | an explicit marker or delimiters, but there is also an explicit C
775 | marker (which may be used anywhere):
776 |
777 | =begin code :allow
778 | B<=para>
779 | This is an ordinary paragraph.
780 | Its text will be squeezed and
781 | short lines filled.
782 | =end code
783 |
784 | and likewise the longer C<=for> and C<=begin>/C<=end> forms. For example:
785 |
786 | =begin code :allow
787 | B<=begin para>
788 | This is an ordinary paragraph.
789 | Its text will be squeezed and
790 | short lines filled.
791 |
792 | This is I part of the same paragraph,
793 | which continues until an...
794 | B<=end para>
795 | =end code
796 |
797 | As the previous example implies, when any form of explicit C<=para> block
798 | is used, any whitespace at the start of each line is removed during rendering.
799 | In addition, within a delimited C<=begin para>/C<=end para> block, any
800 | blank lines are preserved.
801 |
802 |
803 | =head3 Code blocks
804 |
805 | Code blocks are used to specify pre-formatted text (typically source
806 | code), which should be rendered without rejustification, without
807 | whitespace-squeezing, and without recognizing any inline markup
808 | codes. Code blocks also have an implicit L
809 | associated with them. Typically these blocks are used to show examples
810 | of code, mark-up, or other textual specifications, and are rendered
811 | using a fixed-width font.
812 |
813 | A code block may be implicitly specified as one or more lines of text,
814 | each of which starts with a whitespace character at the block's virtual
815 | left margin. The implicit code block is then terminated by a blank line.
816 | For example:
817 |
818 | =begin code
819 | This ordinary paragraph introduces a code block:
820 |
821 | $this = 1 * code('block');
822 | $which.is_specified(:by);
823 | =end code
824 |
825 | Implicit code blocks may only be used within C<=pod>, C<=item>, C<=defn>,
826 | C<=nested>, or L blocks.
827 |
828 | There is also an explicit C<=code> block (which can be specified within
829 | I other block type, not just C<=pod>, C<=item>, etc.):
830 |
831 | =begin code :allow
832 | The C subroutine adds feedback:
833 |
834 | B<=begin code>
835 |
836 | sub loud_update ($who, $status) {
837 | say "$who -> $status";
838 |
839 | silent_update($who, $status);
840 | }
841 |
842 | B<=end code>
843 | =end code
844 |
845 | As the previous example demonstrates, within an explicit C<=code> block
846 | the code can start at the (virtual) left margin. Furthermore, lines that
847 | start with whitespace characters after that margin have subsequent
848 | whitespace preserved exactly (in addition to the implicit nesting of the
849 | code). Explicit C<=code> blocks may also contain empty lines.
850 |
851 |
852 | =head4 Formatting within code blocks
853 |
854 | Although C<=code> blocks automatically disregard all L, occasionally you may still need to specify
856 | some formatting within a code block. For example, you may wish
857 | to emphasize a particular keyword in an example (using a C> code). Or
858 | you may want to indicate that part of the example is metasyntactic
859 | (using the C> code). Or you might need to insert a non-ASCII
860 | character (using the C> code).
861 |
862 | You can specify a list of markup codes that should still be
863 | recognized within a code block using the C<:allow> option. The value of
864 | the C<:allow> option must be a list of the (single-letter) names of one
865 | or more markup codes. Those codes will then remain active inside the
866 | code block. For example:
867 |
868 | =begin code
869 | =begin code :allow
870 | sub demo {
871 | B 'Hello R';
872 | }
873 | =end code
874 | =end code
875 |
876 | would be rendered:
877 |
878 | =begin code :allow
879 | sub demo {
880 | B 'Hello R';
881 | }
882 | =end code
883 |
884 | Note that the use of the C<:allow> option also makes it possible
885 | for verbatim L (such as C>
886 | and C>) to L.
887 |
888 | =head4 Assign programming language to code blocks
889 |
890 | The C<:lang> attribute will be used to provide information about the
891 | programming language used in a particular block of code. This helps
892 | in ensuring that the code is correctly rendered and interpreted by the
893 | renderers or syntax highlighting tools.
894 |
895 | For example:
896 |
897 | =begin code :allow
898 | =begin code B<:lang>
899 | sub demo {
900 | say 'Hello R';
901 | }
902 | =end code
903 | =end code
904 |
905 |
906 | =head3 I/O blocks
907 |
908 | Podlite also provides blocks for specifying the input and output of programs.
909 |
910 | The C<=input> block is used to specify pre-formatted keyboard input,
911 | which should be rendered without rejustification or squeezing of whitespace.
912 |
913 | The C<=output> block is used to specify pre-formatted terminal or file
914 | output which should also be rendered without rejustification or
915 | whitespace-squeezing.
916 |
917 | Note that, like C<=code> blocks, both C<=input> and C<=output> blocks have an
918 | implicit level of nesting. They are also like C<=code> blocks in that they
919 | are typically rendered in a fixed-width font, though ideally all three blocks
920 | would be rendered in distinct font/weight combinations (for example: regular
921 | serifed for code, bold sans-serif for input, and regular sans-serif for
922 | output).
923 |
924 | Unlike C<=code> blocks, both C<=input> and C<=output> blocks honour any
925 | nested markup codes. This is particularly useful since a sample of
926 | input will often include prompts (which are, of course, output).
927 | Likewise a sample of output may contain the occasional interactive
928 | component. Podlite provides L
929 | (C> and C>) to indicate embedded input or output, so you can use
930 | the block type that indicates the overall purpose of the sample (i.e. is
931 | it demonstrating an input operation or an output sequence?) and then use
932 | the "contrasting" markup code within the block.
933 |
934 | For example, to include a small amount of input in a sample of output
935 | you could use the C> markup code:
936 |
937 | =begin code :allow
938 | =begin output
939 | Name: Baracus, B.A.
940 | Rank: Sgt
941 | Serial: 1PTDF007
942 |
943 | Do you want additional personnel details? B>
944 |
945 | Height: 180cm/5'11"
946 | Weight: 104kg/230lb
947 | Age: 49
948 |
949 | Print? B>
950 | =end output
951 | =end code
952 |
953 |
954 | =head3 Lists
955 |
956 | Lists in Podlite are specified as a series of contiguous C<=item> blocks. No
957 | special "container" directives or other delimiters are required to
958 | enclose the entire list. For example:
959 |
960 | =begin code
961 | The seven suspects are:
962 |
963 | =item Happy
964 | =item Dopey
965 | =item Sleepy
966 | =item Bashful
967 | =item Sneezy
968 | =item Grumpy
969 | =item Keyser Soze
970 | =end code
971 |
972 | List items have one implicit level of nesting:
973 |
974 | =begin nested
975 | The seven suspects are:
976 |
977 | =item Happy
978 | =item Dopey
979 | =item Sleepy
980 | =item Bashful
981 | =item Sneezy
982 | =item Grumpy
983 | =item Keyser Soze
984 | =end nested
985 |
986 | Lists may be multi-level, with items at each level specified using the
987 | C<=item1>, C<=item2>, C<=item3>, etc. blocks. Note that C<=item> is just
988 | an abbreviation for C<=item1>. For example:
989 |
990 | =begin code
991 | =item1 Animal
992 | =item2 Vertebrate
993 | =item2 Invertebrate
994 |
995 | =item1 Phase
996 | =item2 Solid
997 | =item2 Liquid
998 | =item2 Gas
999 | =item2 Chocolate
1000 | =end code
1001 |
1002 | which would be rendered something like:
1003 |
1004 | =for para :nested
1005 | E Animal
1006 | =for para :nested(2)
1007 | E Vertebrate
1008 | =for para :nested(2)
1009 | E Invertebrate
1010 |
1011 | =for para :nested
1012 | E Phase
1013 | =for para :nested(2)
1014 | E Solid
1015 | =for para :nested(2)
1016 | E Liquid
1017 | =for para :nested(2)
1018 | E Gas
1019 | =for para :nested(2)
1020 | E Chocolate
1021 |
1022 | Podlite parsers must issue a warning if a "level-R" C<=item> block
1023 | (e.g. an C<=item2>, C<=item3>, etc.) appears anywhere except where there
1024 | is a preceding "level-R" C<=item> in the same surrounding block. That
1025 | is, an C<=item3> should only be specified if an C<=item2> appears
1026 | somewhere before it, and that C<=item2> should itself only appear if
1027 | there is a preceding C<=item1>.
1028 |
1029 | Note that item blocks within the same list are not physically nested.
1030 | That is, lower-level items should I be specified inside
1031 | higher-level items:
1032 |
1033 | =begin code
1034 | =comment WRONG...
1035 | =begin item1 --------------
1036 | The choices are: |
1037 | =item2 Liberty ==< Level 2 |==< Level 1
1038 | =item2 Death ==< Level 2 |
1039 | =item2 Beer ==< Level 2 |
1040 | =end item1 --------------
1041 | =end code
1042 |
1043 | =begin code
1044 | =comment CORRECT...
1045 | =begin item1 ---------------
1046 | The choices are: |==< Level 1
1047 | =end item1 ---------------
1048 | =item2 Liberty ==================< Level 2
1049 | =item2 Death ==================< Level 2
1050 | =item2 Beer ==================< Level 2
1051 | =end code
1052 |
1053 |
1054 | =head4 Ordered lists
1055 |
1056 | An item is part of an ordered list if the item has a C<:numbered>
1057 | configuration option:
1058 |
1059 | =begin code
1060 | =for item1 :numbered
1061 | Visito
1062 |
1063 | =for item2 :numbered
1064 | Veni
1065 |
1066 | =for item2 :numbered
1067 | Vidi
1068 |
1069 | =for item2 :numbered
1070 | Vici
1071 | =end code
1072 |
1073 | This would produce something like:
1074 |
1075 | =begin nested
1076 | 1. Visito
1077 |
1078 | =begin nested
1079 | 1.1. Veni
1080 |
1081 | 1.2. Vidi
1082 |
1083 | 1.3. Vici
1084 | =end nested
1085 | =end nested
1086 |
1087 | although the numbering scheme is entirely at the discretion of the
1088 | renderer, so it might equally well be rendered:
1089 |
1090 | =begin nested
1091 | 1. Visito
1092 |
1093 | =begin nested
1094 | 1a. Veni
1095 |
1096 | 1b. Vidi
1097 |
1098 | 1c. Vici
1099 | =end nested
1100 | =end nested
1101 |
1102 | or even:
1103 |
1104 | =begin nested
1105 | A: Visito
1106 |
1107 | =begin nested
1108 | E(i) Veni
1109 |
1110 | E(ii) Vidi
1111 |
1112 | (iii) Vici
1113 | =end nested
1114 | =end nested
1115 |
1116 | Alternatively, if the first word of the item consists of a single C<#>
1117 | character, the item is treated as having a C<:numbered> option:
1118 |
1119 | =begin code
1120 | =item1 # Visito
1121 | =item2 # Veni
1122 | =item2 # Vidi
1123 | =item2 # Vici
1124 | =end code
1125 |
1126 | To specify an I list item that starts with a literal C<#>, either
1127 | make the octothorpe verbatim:
1128 |
1129 | =begin code :allow
1130 | =item B> introduces a comment
1131 | =end code
1132 |
1133 | or explicitly mark the item itself as being unnumbered:
1134 |
1135 | =begin code :allow
1136 | =for item B<:!numbered>
1137 | # introduces a comment
1138 | =end code
1139 |
1140 | The numbering of successive C<=item1> list items increments
1141 | automatically, but is reset to 1 whenever any other kind of non-ambient
1142 | Podlite block appears between two C<=item1> blocks. For example:
1143 |
1144 | =begin code
1145 | The options are:
1146 |
1147 | =item1 # Liberty
1148 | =item1 # Death
1149 | =item1 # Beer
1150 |
1151 | The tools are:
1152 |
1153 | =item1 # Revolution
1154 | =item1 # Deep-fried peanut butter sandwich
1155 | =item1 # Keg
1156 | =end code
1157 |
1158 | would produce:
1159 |
1160 | =begin nested
1161 | The options are:
1162 |
1163 | =begin nested
1164 | =para 1. Liberty
1165 | =para 2. Death
1166 | =para 3. Beer
1167 | =end nested
1168 |
1169 | The tools are:
1170 |
1171 | =begin nested
1172 | =para 1. Revolution
1173 | =para 2. Deep-fried peanut butter sandwich
1174 | =para 3. Keg
1175 | =end nested
1176 | =end nested
1177 |
1178 | The numbering of nested items (C<=item2>, C<=item3>, etc.) only resets
1179 | (to 1) when the higher-level item's numbering either resets or increments.
1180 |
1181 | To prevent a numbered C<=item1> from resetting after a non-item block,
1182 | you can specify the C<:continued> option:
1183 |
1184 | =begin code :allow
1185 | =for item1
1186 | # Retreat to remote Himalayan monastery
1187 |
1188 | =for item1
1189 | # Learn the hidden mysteries of space and time
1190 |
1191 | I
1192 |
1193 | =for item1 B<:continued>
1194 | # Prophet!
1195 | =end code
1196 |
1197 | which produces:
1198 |
1199 | =begin nested
1200 | =para 1. Retreat to remote Himalayan monastery
1201 | =para 2. Learn the hidden mysteries of space and time
1202 | =para I
1203 | =para 3. Prophet!
1204 | =end nested
1205 |
1206 | =head4 Task lists
1207 |
1208 | In addition to the ordered list Podlite also supports
1209 | task lists, which are commonly known as checklists or to-do lists.
1210 |
1211 | To create a task list item just apply a C<:checked>
1212 | attribute to C<=item> block.
1213 |
1214 | =begin code :allow
1215 | =for item B<:checked>
1216 | Buy groceries
1217 | =for item B<:!checked>
1218 | Clean the garage
1219 | =end code
1220 |
1221 | The rendered output looks like this:
1222 |
1223 | [X] Buy groceries
1224 | [ ] Clean the garage
1225 |
1226 | Alternatively, if item content starts with brackets with space (C<[ ]>)
1227 | the item is treated as having a C<:!checked> attribute.
1228 | To select a checkbox, add an C in between the brackets (C<[x]>). it eqvivalent
1229 | of C<:checked> attribute.
1230 |
1231 | For example:
1232 | =begin code :allow
1233 | =item B<[x]> Buy groceries
1234 | =itme B<[ ]> Clean the garage
1235 | =end code
1236 |
1237 | It possiible to create multilevel to-do lists, which permits the
1238 | inclusion of various task levels or sub-tasks.
1239 | Here's an example:
1240 |
1241 | =begin code :allow
1242 | B<=item1> [ ] Work
1243 | B<=item2> [ ] Prepare the presentation
1244 | =item2 [x] Send emails
1245 | =item1 [ ] Home
1246 | =item2 [ ] Vacuum the living room
1247 | =item2 [ ] Water the plants
1248 | =end code
1249 |
1250 | =head4 Unordered lists
1251 |
1252 | List items that are not C<:numbered> or C<:checked> are treated as defining unordered
1253 | lists. Typically, such lists are rendered with bullets. For example:
1254 |
1255 | =begin code
1256 | =item1 Reading
1257 | =item2 Writing
1258 | =item3 'Rithmetic
1259 | =end code
1260 |
1261 | might be rendered:
1262 |
1263 | =for para :nested(1)
1264 | EReading
1265 | =for para :nested(2)
1266 | EWriting
1267 | =for para :nested(3)
1268 | E'Rithmetic
1269 |
1270 | As with numbering styles, the bulletting strategy used for different levels
1271 | within a nested list is entirely up to the renderer.
1272 |
1273 |
1274 | =head4 Multi-paragraph list items
1275 |
1276 | Use the delimited form of the C<=item> block to specify items that
1277 | contain multiple paragraphs. For example:
1278 |
1279 | =begin code
1280 | Let's consider two common proverbs:
1281 |
1282 | =begin item :numbered
1283 | I
1284 |
1285 | This is a common myth and an unconscionable slur on the Spanish
1286 | people, the majority of whom are extremely attractive.
1287 | =end item
1288 |
1289 | =begin item :numbered
1290 | I
1291 |
1292 | In deciding whether to become an early riser, it is worth
1293 | considering whether you would actually enjoy annelids
1294 | for breakfast.
1295 | =end item
1296 |
1297 | As you can see, folk wisdom is often of dubious value.
1298 | =end code
1299 |
1300 | which produces:
1301 |
1302 | =begin nested
1303 | =config item :numbered
1304 | Let's consider two common proverbs:
1305 |
1306 | =begin item
1307 | I
1308 |
1309 | This is a common myth and an unconscionable slur on the Spanish
1310 | people, the majority of whom are extremely attractive.
1311 | =end item
1312 |
1313 | =begin item
1314 | I
1315 |
1316 | In deciding whether to become an early riser, it is worth
1317 | considering whether you would actually enjoy annelids
1318 | for breakfast.
1319 | =end item
1320 |
1321 | As you can see, folk wisdom is often of dubious value.
1322 | =end nested
1323 |
1324 |
1325 | =head4 Definition lists
1326 |
1327 | To create term/definition lists, use a C<=defn> block. This is
1328 | similar in effect to an C<=item> block, in that a series of C<=defn>
1329 | blocks implicitly defines a list (but which might then be rendered into
1330 | HTML using C«...
» tags, rather than C«...
» tags)
1331 |
1332 | The first non-blank line of content is treated as a term being defined,
1333 | and the remaining content is treated as the definition for the term.
1334 | For example:
1335 |
1336 | =begin code
1337 | =defn MAD
1338 | Affected with a high degree of intellectual independence.
1339 |
1340 | =defn MEEKNESS
1341 | Uncommon patience in planning a revenge that is worth while.
1342 |
1343 | =defn
1344 | MORAL
1345 | Conforming to a local and mutable standard of right.
1346 | Having the quality of general expediency.
1347 | =end code
1348 |
1349 | Like other kinds of list items, definitions can be numbered, using either an
1350 | option or a leading C<#>:
1351 |
1352 | =begin code :allow
1353 | =for defn B<:numbered>
1354 | SELFISH
1355 | Devoid of consideration for the selfishness of others.
1356 |
1357 | =defn B<#> SUCCESS
1358 | The one unpardonable sin against one's fellows.
1359 | =end code
1360 |
1361 |
1362 | =head3 Nesting blocks
1363 |
1364 | Any block can be nested by specifying a C<:nested> option on it:
1365 |
1366 | =begin code :allow
1367 | =begin para B<:nested>
1368 | We are all of us in the gutter,E
1369 | but some of us are looking at the stars!
1370 | =end para
1371 | =end code
1372 |
1373 | However, qualifying each nested paragraph individually quickly becomes
1374 | tedious if there are many in a sequence, or if multiple levels of
1375 | nesting are required:
1376 |
1377 | =begin code :allow
1378 | =begin para B<:nested>
1379 | We are all of us in the gutter,E
1380 | but some of us are looking at the stars!
1381 | =end para
1382 | =begin para B<:nested(2)>
1383 | -- Oscar Wilde
1384 | =end para
1385 | =end code
1386 |
1387 | So Podlite provides a C<=nested> block that marks all its contents as being
1388 | nested:
1389 |
1390 | =begin code :allow
1391 | B<=begin nested>
1392 | We are all of us in the gutter,E
1393 | but some of us are looking at the stars!
1394 | B<=begin nested>
1395 | -- Oscar Wilde
1396 | B<=end nested>
1397 | B<=end nested>
1398 | =end code
1399 |
1400 | Nesting blocks can contain any other kind of block, including implicit
1401 | paragraph and code blocks. Note that the relative physical indentation
1402 | of the blocks plays no role in determining their ultimate nesting.
1403 | The preceding example could equally have been specified:
1404 |
1405 | =begin code :allow
1406 | B<=begin nested>
1407 | We are all of us in the gutter,E
1408 | but some of us are looking at the stars!
1409 | B<=begin nested>
1410 | -- Oscar Wilde
1411 | B<=end nested>
1412 | B<=end nested>
1413 | =end code
1414 |
1415 |
1416 | =head3 Tables
1417 |
1418 | Simple tables can be specified in Podlite using a C<=table> block.
1419 | The table may be given an associated description or title using the
1420 | C<:caption> option.
1421 |
1422 | Columns are separated by two or more consecutive whitespace characters
1423 | (double-space),
1424 | or by a vertical line (C<|>) or a border intersection (C<+>), either of
1425 | which must be separated from any content by at least one whitespace
1426 | character. Note that only one column separator type is allowed in a single line,
1427 | but different lines are allowed to use different visible column separator types
1428 | (that style is not recommended). Using a mixture of visible and non-visible
1429 | column separator types in a table is an error.
1430 |
1431 | Rows can be specified in one of two ways: either one row per line, with
1432 | no separators; or multiple lines per row with explicit horizontal
1433 | separators (whitespace, intersections (C<+>), or horizontal lines: C<->,
1434 | C<=>, C<_>) between I row. Either style can also have an
1435 | explicitly separated header row at the top. If rows are using the
1436 | two-whitespace-character separator, the row cells should be carefully
1437 | aligned to ensure the table is interpreted as the user intended.
1438 |
1439 | Each individual table cell is separately formatted, as if it were a
1440 | nested C<=para>. Note that table rows are expected to have the same number
1441 | of cells.
1442 |
1443 | This means you can create tables compactly, line-by-line:
1444 |
1445 | =begin code
1446 | =table
1447 | The Shoveller Eddie Stevens King Arthur's singing shovel
1448 | Blue Raja Geoffrey Smith Master of cutlery
1449 | Mr Furious Roy Orson Ticking time bomb of fury
1450 | The Bowler Carol Pinnsler Haunted bowling ball
1451 | =end code
1452 |
1453 | With header:
1454 |
1455 | =begin code
1456 | =begin table
1457 |
1458 | Directive Specifies
1459 | _________ ____________________________________________________
1460 | C<=begin> Start of an explicitly terminated block
1461 | C<=config> Lexical modifications to a block or markup code
1462 |
1463 | =end table
1464 | =end code
1465 |
1466 | Or:
1467 |
1468 | =begin code
1469 | =begin table
1470 |
1471 | Energy Source Benefit
1472 |
1473 | Solar power Reduces electricity bills
1474 | Wind energy Clean power source
1475 | Hydroelectric power Highly efficient
1476 | Geothermal energy Low emissions
1477 | Biomass Reduces waste
1478 |
1479 | =end table
1480 | =end code
1481 |
1482 | or line-by-line with multi-line headers:
1483 |
1484 | =begin code
1485 | =table
1486 | Superhero | Secret |
1487 | | Identity | Superpower
1488 | ==============|=================|================================
1489 | The Shoveller | Eddie Stevens | King Arthur's singing shovel
1490 | Blue Raja | Geoffrey Smith | Master of cutlery
1491 | Mr Furious | Roy Orson | Ticking time bomb of fury
1492 | The Bowler | Carol Pinnsler | Haunted bowling ball
1493 | =end code
1494 |
1495 | or with multi-line headers I multi-line data:
1496 |
1497 | =begin code
1498 | =begin table :caption('The Other Guys')
1499 |
1500 | Secret
1501 | Superhero Identity Superpower
1502 | ============= =============== ===================
1503 | The Shoveller Eddie Stevens King Arthur's
1504 | singing shovel
1505 |
1506 | Blue Raja Geoffrey Smith Master of cutlery
1507 |
1508 | Mr Furious Roy Orson Ticking time bomb
1509 | of fury
1510 |
1511 | The Bowler Carol Pinnsler Haunted bowling ball
1512 |
1513 | =end table
1514 | =end code
1515 |
1516 | =head4 Advanced Table Format
1517 |
1518 | Tables may construct using C<=row> and C<=cell> blocks.
1519 | The C<=row> blocks represent individual rows within the table.
1520 |
1521 | The C<=cell> blocks exist within rows and contain the actual content of the table.
1522 | These cells can contain text, data, or other blocks.
1523 |
1524 | =begin code
1525 | =begin table
1526 |
1527 | =begin row
1528 | =cell Fruits
1529 | =cell Bananas
1530 | =cell Yellow and ripe
1531 | =end row
1532 |
1533 | =begin row
1534 | =cell Vegetables
1535 | =cell Carrots
1536 | =begin cell
1537 | =para Crunchy and orange
1538 | =end cell
1539 | =end row
1540 |
1541 | =end table
1542 | =end code
1543 |
1544 | Each C<=row> block may have an optional C<:header> attribute, designating
1545 | it as a header row. Header rows typically contain labels or titles
1546 | for columns and are visually distinct.
1547 |
1548 |
1549 | =begin code :allow
1550 | =begin table
1551 |
1552 | =begin row B<:header>
1553 | =cell Category
1554 | =cell Product
1555 | =cell Description
1556 | =end row
1557 |
1558 | =begin row
1559 | =cell Fruits
1560 | =cell Bananas
1561 | =cell Yellow and ripe
1562 | =end row
1563 |
1564 | =begin row
1565 | =cell Vegetables
1566 | =cell Carrots
1567 | =cell Crunchy and orange
1568 | =end row
1569 |
1570 | =end table
1571 | =end code
1572 |
1573 | The C<=cell> blocks can also have two important attributes:
1574 |
1575 | =begin defn
1576 | C<:colspan>
1577 |
1578 | This attribute specifies the number of columns a cell should span horizontally.
1579 | It allows cells to merge and occupy multiple adjacent columns, creating a visually
1580 | unified cell.
1581 | =end defn
1582 |
1583 | =begin defn
1584 | C<:rowspan>
1585 |
1586 | This attribute determines how many rows a cell should span vertically.
1587 | Cells with C<:rowspan> can cover multiple rows in a table, creating a vertical merge effect.
1588 | =end defn
1589 |
1590 | These example demonstrate how C<:colspan> and C<:rowspan> attributes can be used
1591 | to create tables with merged cells, which is especially useful for complex
1592 | data structures.
1593 |
1594 | =begin code
1595 | =begin table
1596 |
1597 | =begin row :header
1598 | =for cell :colspan(2)
1599 | Item and Quantity
1600 | =cell Description
1601 | =end row
1602 |
1603 | =begin row
1604 | =cell Apples
1605 | =cell 5
1606 | =for cell :rowspan(2)
1607 | Fruit for snacking
1608 | =end row
1609 |
1610 | =begin row
1611 | =cell Bananas
1612 | =cell 3
1613 | =end row
1614 |
1615 | =end table
1616 | =end code
1617 |
1618 |
1619 | It draw somethink like this:
1620 |
1621 | ---------------------------------------------------------------
1622 | | Item and Quantity | Description |
1623 | |----------------------------------|--------------------------|
1624 | | Apples | 5 | |
1625 | |--------------|-------------------| Fruit for snacking |
1626 | | Bananas | 3 | |
1627 | ---------------------------------------------------------------
1628 |
1629 | Each C<=row> block may only contain C<=cell> blocks or blank lines as delimiters.
1630 | All other types of blocks within the C<=row> are implicitly wrapped
1631 | by C<=cell> blocks.
1632 |
1633 | For example:
1634 |
1635 | =begin code
1636 |
1637 | =begin table
1638 |
1639 | =begin row :header
1640 | =cell Diagram or Picture
1641 | =cell Description
1642 | =end row
1643 |
1644 | =begin row
1645 | =picture spacecraft_in_orbit.jpg
1646 | =para
1647 | A vehicle designed for space travel
1648 | =end row
1649 |
1650 | =begin row
1651 | =Mermaid
1652 | graph TD;
1653 | A[Space Station] --> B[Mars Base]
1654 |
1655 | A space station connected to a Mars base
1656 | =end row
1657 |
1658 | =end table
1659 |
1660 | =end code
1661 |
1662 | =head4 Table from CSV files or data blocks
1663 |
1664 | It is possible to create tables from files or data blocks.
1665 | To do this, use the C or C schema in the first non-blank line
1666 | to specify the source of the table data.
1667 | For example:
1668 |
1669 | =begin code :allow
1670 | =table B
1671 |
1672 | =for table :caption('Basic cake recipe ingredients')
1673 | B
1674 |
1675 | =begin data B<:key> :mime-type
1676 | ingredient,quantity,unit
1677 | flour,2,cups
1678 | sugar,1,cups
1679 | eggs,2,items
1680 | butter,0.5,cups
1681 | baking powder,2,teaspoons
1682 | =end data
1683 | =end code
1684 |
1685 |
1686 | =for head3 :id
1687 | Named or modular custom blocks
1688 |
1689 | D whose names contain at least one uppercase and one lowercase
1690 | letter are assumed to be destined for specialized renderers or parser
1691 | plug-ins. For example:
1692 |
1693 | =begin code
1694 | =begin Xhtml
1695 |