How do I generate numbered lists with pod?

Question

Looking at https://docs.raku.org/language/pod#Lists. I don't see a way to create a numbered list:

1. one
2. three
3. four

Is there an undocumented way to do it?

Answer 1

There is not currently (as of January 2022) an implemented way to use ordered list in Pod6.

The historical design documents contain Pod6 syntax for ordered lists and, as far as I know, this remains something that we'd like to add. Once that syntax is implemented, you'll be able to write something like:

=item1 # Animal 
=item2    # Vertebrate 
=item2    # Invertebrate 
 
=item1 # Phase 
=item2    # Solid 
=item2    # Liquid 
=item2    # Gas

This would produce output along the lines of:

1. Animal 
   1.1     Vertebrate 
   1.2     Invertebrate 
 
2. Phase 
   2.1     Solid 
   2.2     Liquid 
   2.3     Gas

(Though the exact syntax for rendering the list would be up to the implementation of the Pod renderer.)

But until that's implemented, there isn't any way to use Pod6 syntax to create an ordered list.

Edit:

I just checked the actual parsed Pod6, and it looks like (to my surprise) the ordered list syntax I showed above actually is parsed internally. For example, running say $=pod[5].raku with the Pod6 shows the following (based on the =item2 # Liquid line):

Pod::Item.new(level => 2, config => {:numbered(1)}, contents => [Pod::Block::Para.new(config => {}, contents => ["Liquid"])])

So the parsing work is in place; it's just the Pod::To::_ renderer that need to add support. (And there could even be some out there that have that support. I do know that neither Rakudo's Pod::To::Text nor Raku's Pod::To::HTML (v0.8.1) currently render ordered lists, however.)

Workarounds

Depending on the output formats you're targeting, you could of course write the ordered list yourself (pretty easy if you're rendering to plain text, more annoying to do if you're printing to HTML). This does, of course, sacrifice Pod6's multi-output-format support, which is one of its key features.

For a workaround that doesn't sacrifice Pod's multi-output nature, you'd probably want to look into manipulating/reformatting the Pod text programmatically. If you do so, the docs to start with are the Pod6 section on accessing Pod and the (unfortunately very short) section on the DOC phaser.

Answer 2

Just use a list and a loop?

    my @list = [ (1, 2, 3), (1, 2, ),
               [<a b c>, <d e f>],
               [[1]]];

    for @list -> @element {
        say "{@element} → {@element.^name}";
        for @element -> $sub-element {
            say $sub-element;
        }
    }
    
    # OUTPUT: 
    #1 2 3 → List 
    #1 
    #2 
    #3 
    #1 2 → List 
    #1 
    #2 
    #a b c d e f → Array 
    #(a b c) 
    #(d e f) 
    #1 → Array 
    #1