=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

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