=begin rakudoc

Overview

In general, RakuDoc sources are held in git repositories.

However, if the sources^[1] already contains all the sources, and no sources are kept in repositories, then the gather-sources utility need not be used.

The following steps are then followed for each build sequence: =numitem The gather-sources utility is used to:

• clone the RakuDoc sources in the website build are under the repository-store directory using gather-sources.

• Each repository is specified in the 04.repositories config file.

• A repository may contain files for multiple languages.

• create entries in repo-info hash to the desired .rakudoc files.

• Files may be selected on a global basis by setting the with-only.

• Files may be filtered out at the language/repo using ignore, files not listed in ignore have entries created.

• Files may be selected at the language/repo using select, no other files are let through.

• ignore is applied after select, so files in both select and ignore will be ignored.

• generate from repo-info a file called repository-info-file, which is stored in misc.

=numitem The elucid8-build utility is then called to:

• update the file-data-name file.

• If the repository-info-file file exists, it is the basis for file-data-name.

• If the repository-info-file file does not exist, file-data-name is built from the files in the sources directory.

• render the files in the sources directory into the publication directory

• Existing rendered files are updated if

• the rendered date is older than the last modification date of the source

• the force -f flag is set

• if a :with-only list is present in the config file, or elucid8-build is called with a --with-only argument on the CLI, then only those sources are rendered

The build process may be controlled using the following options with elucid8-build:

• --regenerate-from-scratch = delete the publication directory and the file-data-name file.

• --with-only               = only operate on these files (others in publication directory will be untouched).

• --f                       = ignore the modified attribute.

• -v                        = get the versions of the Elucid8-build and Rakuast-RakuDoc-Render distributions.

Relation between repository-info-file and file-data-name

The repository-info-file is generated by gather-sources and contains information that can be obtained from the repositories and the config.

file-data-name file can be generated from the files in sources or from repository-info-file.

Either there are files in sources, and repository-info-file is absent, or vice versa.

However, file-data-name contains information about the rendered files as well.

When gather-sources is run, it updates the local repositories, and stores the modified attribute for each file. So, elucid8-build needs to update file-data-name.

=place semantic:LICENSE :caption<License> =place semantic:AUTHORS :caption<Credits> =end rakudoc