=begin rakudoc :type<plugin>
=TITLE Grouping files in an index
=SUBTITLE The plugin takes data collected from other
Rakudoc files, selects them according to criteria,
and outputs the filename and descriptions.
=for AUTHOR :hidden
Richard Hainsworth, aka finanalyst
=for VERSION :hidden
v0.1.0
=head Overview

When a group of Rakudoc files are rendered using a
C<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 C<=ListFiles> block, then the block will
output the files in the meta data cache according to
selector criteria.

=head Selectors

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

For example, the documentation files for the C<RakuAST::RakuDoc::Render>
distribution all contain the option C<:type>, eg.
=begin code :lang<RakuDoc>
    =begin rakudoc :type<plugin>
=end code
In the distribution, the I<type> option is given the values:
B<plugin>, B<renderer>, B<fundamental>, and B<minor>.

Using the C<ListFiles> block, an index source can be written
so that the files are sorted according to the type values, eg.
=begin code :lang<RakuDoc>
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
=end code

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

=begin code :lang<RakuDoc>
    =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>
=end code

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 C<title>,
C<subtitle>, and C<route> can also be used with C<:sort-by>,
as can custom metadata such as C<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