=begin rakudoc :type<plugin>

Overview

When a group of Rakudoc files are rendered using a RakuDoc::Processor object (RPO), the data from the processing can be collected before the final output is stored.

If this processed file meta data is injected back into the RPO before a RakuDoc source with a =ListFiles block, then the block will output the files in the meta data cache according to selector criteria.

Selectors

At the start of a RakuDoc source is a =begin rakudoc instruction. It can be given metadata options, which describe the file.

For example, the documentation files for the RakuAST::RakuDoc::Render distribution all contain the option :type, eg.

    =begin rakudoc :type<plugin>

In the distribution, the type option is given the values: plugin, renderer, fundamental, and minor.

Using the ListFiles block, an index source can be written so that the files are sorted according to the type values, eg.

The documentation can be split as follows:
=for ListFiles :select<type=fundamental> :caption<Fundamental>
Sources containing key concepts and information

=for ListFiles :select<type=renderer> :caption<Renderers in distribution>
Descriptions of the Renderer classes

...

=for ListFiles :select<type=!> :caption<Files without type options>
File from other sources or automatically generated

By default, matching files are listed alphabetically by title. To control the order, add :sort-by<field> to the ListFiles block. Any metadata field can be used for ordering, eg.

    =begin rakudoc :type<plugin> :nav-order<20>
    =TITLE Grouping files in an index
    =SUBTITLE The plugin takes data collected from other files
    ...
    =end rakudoc

    =for ListFiles :select<type=plugin> :sort-by<nav-order>

If the chosen sort field contains integers, the entries are sorted numerically. When the field is missing or empty, that entry falls back to sorting by title. The values title, subtitle, and route can also be used with :sort-by, as can custom metadata such as nav-order.

The last example shows how to capture files that do not have a type option. A file not matching any of the select criteria are not listed, so having a catchall syntax ensures all the RakuDoc source files in a collection are listed.

When more meta options are available, for example the Raku documentation suite, with about 700 source files, has three metadata options for each file.

=place semantic:AUTHOR :caption<Credits> =place semantic:VERSION :!toc =end rakudoc