In many cases, it is desirable to write a content file that has an annotated overview of all or some of the files in the collection, showing the Title together with the Subtitle.

This list should be amenable to separate styling, so that long lists can be folded, or put into tabs.

Since Raku::Pod::Render captures all the meta (or configuration) information associated with the first Pod::Block named pod in a file, this information can be extracted and used to list these files in the Compilation stage.

USAGE

Place listfiles in the plugins-required<compilation> and plugins-required<render> configuration keys.

Place the =for ListFiles :select<...> in the Pod6 content file. See below for select.

In the content files that need to be listed, place meta data in the =begin pod line, eg.

    =begin pod :kind<Language> :category<tutorial>

The key names and the key values are arbitrary and depend only on the collection designer/writer.

ListFiles block

The basic usage is

    =for ListFiles :select<key-name-1=key-value-1, key-name-2=key-value-2, ...> :no-desc<Nothing found> :no-files<aint got nothing>
    Some text for the caption in a single paragraph

Another way
    =begin ListFiles :select< ... > :no-desc<No description found>
    Some text in several paragraphs

    more caption text
    =end ListFiles

While ListFiles is used here, Listfiles and listfiles are also possible.

The selectkey is mandatory

If a ListFiles block is used without a select key, then a <div> with an error message is output.

If the select key does not parse correctly, then an error div is also output.

It must have the form :select< ... > so that the contents are a string. (Pod6 allows other forms, which may be used so long as the argument is a string).

select contains one, or a comma-separated list of, key/value pair(s) with the form \S+\s*=\s*\S+.

The template will use the select information to gather the files that meet the meta data criteria, access the =TITLE and =SUBTITLE information in the Pod file, and list the files in alpahbetical order.

This plugin only allows for a simple select semantic, such that files are selected when each key/value pair is true. Other more complex select semantics could be considered in time.

If no =TITLE block is found in the content file, the content filename is used instead.

The no-desc key is optional

If no =SUBTITLE block is found, then the content of the no-desc key is used. This allows for multilingual use.

If none of the alternatives are given, then the words 'no description' is used.

The no-files key is optional

If there are no files that meet the select criteria, then the text in no-files is used.

If the option is not given, then the words 'No files meet the criteria' are used.