Merge pull request #3065 from perl6/document-resources

Document resources

Author: JJ

doc/Language/modules.pod6

@@ -561,7 +561,6 @@ Vortex-TotalPerspective/
 ├── README.md
 └── t
     └── basic.t
-
 =end code
 
 If your project contains other modules that help the main module do

doc/Language/variables.pod6

@@ -1192,7 +1192,58 @@ C<$?FILE> and C<$?LINE> are also available from L<CallFrame|/type/CallFrame> as
 the L<C<file>|/type/CallFrame#method_file> and
 L<C<line>|/type/CallFrame#method_line> methods, respectively.
 
-=head3 Other compile-time variables:
+=head3 X<%?RESOURCES>
+
+A compile-time variable available within code of a X<Distribution>.
+
+It contains a hash that provides compile and runtime access to files
+associated with the Distribution of the current compilation unit.  It
+is used to access a special storage for Distribution-wide static files
+(for example, examples of configuration files, templates etc).
+
+To add a file to a distribution, it is placed under C<resources> directory:
+
+=begin code :lang<text>
+Module-Foo/
+├── lib
+│   └── Module
+│       └── Foo.pm6
+├── META6.json
+├── README.md
+└── resources
+    └── images
+        └── foo.jpg
+=end code
+
+Then a relative path (starting from root directory of a distribution)
+to a file is specified under C<"resources"> field in META6.json file:
+
+=begin code :lang<js>
+"resources": [
+    "images/foo.jpg"
+]
+=end code
+
+Every resource file is added to an installed Distribution and is
+accessible using a Hash-like access to C<%?RESOURCES>:
+
+=begin code :skip<resources-example>
+my $foo-IO = %?RESOURCE<images/foo.jpg>;          # gets an object you can slurp
+my $foo-IO = %?RESOURCE<images/foo.jpg>.absolute; # gets an absolute path to a file
+my $foo-IO = %?RESOURCE<images/foo.jpg>.open;     # gets an opened IO::Handle to work with
+=end code
+
+Note that paths and names of resource files can be mangled in an
+installed distribution, so do not rely on their values in any other
+case besides using them as keys for C<%?RESOURCES> variable.
+
+C<%?RESOURCES> variable is not implemented as a plain Hash, but an
+instance of C<Distribution::Resources> type, so do not expect to see
+all available resource files in a distribution by printing or other
+ways to inspect its value. Instead, use the API described above to
+access particular files.
+
+=head3 Introspection compile-time variables
 
 X<|$?PACKAGE>X<|$?MODULE>X<|$?CLASS>X<|$?ROLE>
 X<|$?TABSTOP>X<|$?NL>X<|$?DISTRIBUTION>
@@ -1211,6 +1262,8 @@ The following compile time variables allow for a deeper introspection:
 With particular regard to the C<$?NL>, see the L<newline
 pragma|/language/pragmas>.
 
+=head3 Rakudo-specific compile-time variables
+
 These variables are Rakudo specific, with all the corresponding caveats:
 =for table
 $?BITS           Number of data-path bits of the platform the program is being compiled upon.