Improving and restructuring documentation for dynamic variables.

This closes #2510 and also refs #2483.

Author: JJ

doc/Language/variables.pod6

@@ -882,7 +882,7 @@ successful exit means the block returned a defined value or a list.
 
 In the above case, if the C<Bool.pick> returns true, the answer will
 stay as 84 because the block returns a defined value (C<say> returns
-true). Otherwise the C<die> statement will cause the block to exit
+C<True>). Otherwise the C<die> statement will cause the block to exit
 unsuccessfully, resetting the answer to 42.
 
 X<|constant (Prefix)>
@@ -896,7 +896,9 @@ constant $pi2 = pi * 2;
 $pi2 = 6; # OUTPUT: «(exit code 1) Cannot assign to an immutable value␤
 =end code
 
-The value is assigned at compile time. Please check L<the section on constants in the Terms page|/language/terms#Constants> for additional information.
+The value is assigned at compile time. Please check
+L<the section on constants in the Terms page|/language/terms#Constants> for
+additional information.
 
 =head1 Type constraints and initialization
 
@@ -911,7 +913,8 @@ L<of|/type/Variable#trait_of> to set a type constraint.
     # OUTPUT: «X::TypeCheck::Assignment: Type check failed in assignment to $x; expected Int but got Str ("a string")␤»
 
 If a scalar variable has a type constraint but no initial value, it's
-initialized with the type object of the default value of the container it's bound to.
+initialized with the type object of the default value of the container it's
+bound to.
 
     my Int $x;
     say $x.^name;       # OUTPUT: «Int␤»
@@ -1201,7 +1204,11 @@ in uppercase.
 X<|$*ARGFILES>X<|@*ARGS>
 =head3 Argument related variables
 
-=item C<$*ARGFILES> An L<IO::ArgFiles> (an empty subclass of L<IO::CatHandle>)
+These variables are related to the arguments passed to a script.
+
+=head4 C<$*ARGFILES>
+
+An L<IO::ArgFiles> (an empty subclass of L<IO::CatHandle>)
 that uses C<@*ARGS> as source files, if it contains any files, or C<$*IN>
 otherwise. When C<$*IN> is used, its C<:nl-in>, C<:chomp>, C<:encoding>, and
 C<:bin> will be set on the L<IO::ArgFiles> object.
@@ -1210,8 +1217,9 @@ As of 6.d language, C<$*ARGFILES> I<inside>
 L<C«sub MAIN»|/language/functions#sub_MAIN> is always set to C<$*IN>, even
 when C<@*ARGS> is not empty.
 
-=item C<@*ARGS>
-Arguments from the command line.
+=head4 C<@*ARGS>
+
+C<@*ARGS> contains the arguments from the command line.
 
 X<|$*IN>X<|$*OUT>X<|$*ERR>
 =head3 Special filehandles: C<STDIN>, C<STDOUT> and C<STDERR>
@@ -1220,7 +1228,6 @@ For more information about special filehandles please see also the L<Input and
 Output|/language/io> page and the L<IO::Special> class. L<IO::Handle> contains
 several examples of using C<$*IN> for reading standard input.
 
-
 =item C<$*IN>
 Standard input filehandle, AKA I<STDIN>.
 
@@ -1231,153 +1238,229 @@ Standard output filehandle, AKA I<STDOUT>.
 Standard error filehandle, AKA I<STDERR>.
 
 =head3 Runtime environment
+
+These dynamic variables contain information related to the environment the
+script or program is running in.
+
 X<|%*ENV>
-=item  C<%*ENV>
-Environment variables. Numeric values are provided
+=head4  C<%*ENV>
+
+Operating system environment variables. Numeric values are provided
 as L<allomorphs|/language/glossary#index-entry-Allomorph>
 
 X<|$*REPO>
-=item C<$*REPO>
-a variable holding information about modules installed/loaded;
+=head4 C<$*REPO>
+
+This variable holds information about modules installed/loaded.
 
 X<|$*INIT-INSTANT>
-=item C<$*INIT-INSTANT>
-an Instant object representing program startup time.
+=head4 C<$*INIT-INSTANT>
+
+C<$*INIT-INSTANT> is an L<Instant> object representing program startup time.
 In particular, this is when the core code starts up,
 so the value of C<$*INIT-INSTANT> may be a few milliseconds
 earlier than C<INIT now> or even C<BEGIN now> executed
-in your program;
+in your program.
 
 X<|$*TZ>
-=item C<$*TZ>
-the system's local timezone offset, as the number of B<seconds> from GMT;
+=head4 C<$*TZ>
+
+C<$*TZ> contains the system's local timezone offset, as the number of B<seconds>
+from GMT.
 
 X<|$*CWD>
-=item C<$*CWD>
-the Current Working Directory;
+=head4 C<$*CWD>
+
+It contains the Current Working Directory.
 
 X<|$*KERNEL>
-=item C<$*KERNEL>
-the current running Kernel.
+=head4 C<$*KERNEL>
+
+C<$*KERNEL> contains an object that is stringified to the current running
+kernel.
+
+    say $*KERNEL; # OUTPUT: «linux (4.4.92.31.default)␤»
 
 X<|$*DISTRO>
-=item C<$*DISTRO>
+=head4 C<$*DISTRO>
+
 This object (of type C<Distro>) contains information about the current operating
-system distribution (e.g. C<say "Some sort of Windows" if $*DISTRO.is-win>); in
-the current Rakudo implementation, C<$*DISTRO.name> takes the following values
-(which should be self-explanatory): C<mswin32>, C<macosx>, C<freebsd>, C<linux>,
-C<netbsd>, C<raspbian> and C<dragonfly>. Since these names are implementation
-defined and not in the specification, they could vary and change at any moment.
-C<$*DISTRO> can be stringfied by printing it, for instance, C<say $*DISTRO>, it
-will show additional information on the operating system and version it's using,
-like C<OUTPUT: «debian (9.stretch)␤»>.
+system distribution. For instance:
+
+    say "Some sort of Windows" if $*DISTRO.is-win;
+
+C<$*DISTRO.name> takes a set of values that depend on the operating system.
+These names will vary with version and implementation, so you should
+double-check and test before using them in your programs; since these names are
+implementation defined and not in the specification, they could vary and change
+at any moment.
+
+C<$*DISTRO> can be stringfied by printing it
+
+    say $*DISTRO; # OUTPUT: «debian (9.stretch)␤»
+
+This shows additional information on the operating system and version it's
+using, but as a matter of fact, this variable contains information which is
+useful to create portable programs, such as the path separator:
+
+    say $*DISTRO.perl;
+    # OUTPUT: «Distro.new(release => "42.3", is-win => Bool::False,
+    #          path-sep => ":", name => "opensuse",
+    #          auth => "https://www.opensuse.org/", version => v42.3,
+    #          signature => Blob, desc => "2018-12-13T08:50:59.213619+01:00")␤»
 
 
 X<|$*VM>
-=item C<$*VM>
-contains the current virtual machine running the code;
+=head4 C<$*VM>
+
+This variable contains the current virtual machine running the code, as well as
+additional information on the inner workings of aforementioned VM.
+
+    say $*VM.precomp-ext, " ", $*VM.precomp-target; # OUTPUT: «moarvm mbc␤»
+
+These two variables, for instance, will show the extension used in the
+precompiled bytecode scripts and the target used. This is what is found in the
+Moar Virtual Machine, but it could also vary with version and implementation.
+Other VM, such as Java, will show different values for them. C<$*VM.config>
+includes all configuration values used to create the virtual machine, e.g.
+
+    say $*VM.config<versionmajor>, ".", $*VM.config<versionminor>;
+    # OUTPUT: «2018.11␤»
+
+which are the version of the virtual machine, generally the same one as the one
+used in the interpreter and the overall Perl 6 environment.
 
 X<|$*PERL>
-=item C<$*PERL>
-the current implementation of the Perl language;
+=head4 C<$*PERL>
+
+This object contains information on the current implementation of the Perl
+language:
+
+    say $*PERL.compiler.version; # OUTPUT: «v2018.11.52.g.06156.a.7.ca␤»
+
+but it simply stringifies to the major version of the compiler:
+
+    say $*PERL;# OUTPUT: «Perl 6 (6.d)␤»
 
 X<|$*PID>
-=item C<$*PID>
-the current Process IDentifier (operating system dependent);
+=head4 C<$*PID>
+
+Object containing an integer describing the current Process IDentifier
+(operating system dependent).
 
 X<|$*PROGRAM-NAME>
-=item C<$*PROGRAM-NAME>
-path to the current executable as it was entered on the
-command line, or C<-e> if perl was invoked with the -e flag;
+=head4 C<$*PROGRAM-NAME>
+
+This contains the path to the current executable as it was entered on the
+command line, or C<-e> if perl was invoked with the -e flag.
 
 X<|$*PROGRAM>
-=item C<$*PROGRAM>
-location (in the form of an C<IO::Path> object) of the Perl program being executed;
+=head4 C<$*PROGRAM>
+
+Contains the location (in the form of an C<IO::Path> object) of the Perl 6
+program being executed.
 
 X<|&*EXIT>
-=item C<&*EXIT> code that will be executed when doing an exit().  Intended to
-be used in situations where Perl 6 is embedded in another language runtime
-(such as Inline::Perl6 in Perl 5);
+=head4 C<&*EXIT>
+
+This is a L<Callable> that contains the code that will be executed when doing an
+C<exit()> call.  Intended to be used in situations where Perl 6 is embedded in
+another language runtime (such as Inline::Perl6 in Perl 5).
 
 X<|$*EXECUTABLE>
-=item C<$*EXECUTABLE>
-absolute path of the perl executable that is currently running;
+=head4 C<$*EXECUTABLE>
+
+Contains an C<IO::Path> absolute path of the perl executable that is currently
+running.
 
 X<|$*EXECUTABLE-NAME>
-=item C<$*EXECUTABLE-NAME>
-the name of the perl executable that is currently running.
-(e.g. perl6-p, perl6-m, Niecza.exe)
-Favor $*EXECUTABLE because it's not guaranteed that the perl
-executable is in C<PATH>;
+=head4 C<$*EXECUTABLE-NAME>
+
+This the name of the perl executable that is currently running. (e.g. perl6-p,
+perl6-m). Favor C<$*EXECUTABLE> over this one, since it's not guaranteed that
+the perl executable is in C<PATH>.
 
 X<|$*USAGE>
-=item C<$*USAGE>
-the default usage message generated from the
+=head4 C<$*USAGE>
+
+This is the default usage message generated from the
 signatures of C<MAIN> subs available from inside
-C<sub MAIN> and C<sub USAGE>. The variable is I<read-only>;
+C<sub MAIN> and C<sub USAGE>. The variable is I<read-only>.
 
 X<|$*USER>
-=item C<$*USER>
-the user that is running the program. It's an object
-that evaluates to C<username (uid)>.  It will evaluate
-to the username only if treated as a string and the
-numeric user id if treated as a number;
+=head4 C<$*USER>
+
+An C<Allomorph> with information about the user that is running the program.
+It's an object that evaluates to C<username (uid)>.  It will evaluate to the
+username only if treated as a string and the numeric user id if treated as a
+number.
 
 X<|$*GROUP>
-=item C<$*GROUP>
-the primary group of the user who is running the program.
+=head4 C<$*GROUP>
+
+An C<Allomorph> with the primary group of the user who is running the program.
 It's an object that evaluates to C<groupname (gid)>.
 It will evaluate to the groupname only if treated as a
-string and the numeric group id if treated as a number;
+string and the numeric group id if treated as a number.
 
 X<|$*HOME>
-=item C<$*HOME>
-an L<IO::Path> object representing the "home directory"
+=head4 C<$*HOME>
+
+Contains an L<IO::Path> object representing the "home directory"
 of the user that is running the program. Uses
 C«%*ENV<HOME>» if set. On Windows, uses
 C«%*ENV<HOMEDRIVE> ~ %*ENV<HOMEPATH>». If the
-home directory cannot be determined, it will be L<Any>;
+home directory cannot be determined, it will be L<Any>.
 
 X<|$*SPEC>
-=item C<$*SPEC>
-the appropriate L<IO::Spec> sub-class for the platform that the program is running on;
+=head4 C<$*SPEC>
+
+Contains the appropriate L<IO::Spec> sub-class for the platform that the program
+is running on. This is a higher-level class for the operating system; it will
+return C<Unix>, for instance, in the case of Linux (in the form of the
+C<IO::Spec> class used for the current implementation).
 
 X<|$*TMPDIR>
-=item C<$*TMPDIR>
-an L<IO::Path> object representing the "system temporary directory" as determined by L«C<.tmpdir IO::Spec::* method>|/routine/tmpdir»;
+=head4 C<$*TMPDIR>
+
+This is an L<IO::Path> object representing the "system temporary directory" as
+determined by L«C<.tmpdir IO::Spec::* method>|/routine/tmpdir».
 
 X<|$*TOLERANCE>
-=item C<$*TOLERANCE>
-used by the C<=~=> operator, and any operations that depend on it, to
+=head4 C<$*TOLERANCE>
+
+Variable used by the C<=~=> operator, and any operations that depend on it, to
 decide if two values are approximately equal. Defaults to C<1e-15>;
 
 X<|$*THREAD>
-=item C<$*THREAD>
-a L<Thread> object representing the currently executing thread;
-
-X<|$*SCHEDULER>
-=item C<$*SCHEDULER>
-a L<ThreadPoolScheduler> object representing the current default scheduler (see note below);
+=head4 C<$*THREAD>
 
-X<|$*SAMPLER>
-=item C<$*SAMPLER>: the current L<Telemetry::Sampler> used for
-making snapshots of system state.  Only available if L<Telemetry> has been
-loaded.
+Contains a L<Thread> object representing the currently executing thread;
 
+X<|$*SCHEDULER>
+=head4 C<$*SCHEDULER>
 
-Note on usage of C<$*SCHEDULER>:
+This is a L<ThreadPoolScheduler> object representing the current default
+scheduler.
 
-For the current (2018.04) Rakudo, by default this imposes a maximum of 64
-threads on the methods C<.hyper>, C<.race> and other thread-pool classes that
-use that scheduler such as C<Promise>s or C<Supplie>s. To change the maximum
-number of threads, you can either set the environment variable
-C<RAKUDO_MAX_THREADS> before running perl6 or create a scoped copy with the
-default changed before using them:
+By default this imposes a maximum of 64 threads on the methods C<.hyper>,
+C<.race> and other thread-pool classes that use that scheduler such as
+C<Promise>s or C<Supply>s. This is, however, implementation, dependent and might
+be subject to change. To change the maximum number of threads, you can either
+set the environment variable C<RAKUDO_MAX_THREADS> before running perl6 or
+create a scoped copy with the default changed before using them:
 
     my $*SCHEDULER = ThreadPoolScheduler.new( max_threads => 128 );
 
 This behavior is not tested in the spec tests and is subject to change.
 
+X<|$*SAMPLER>
+=head4 C<$*SAMPLER>
+
+The current L<Telemetry::Sampler> used for
+making snapshots of system state.  Only available if L<Telemetry> has been
+loaded.
+
 =head1 Naming conventions
 
 It is helpful to know our naming conventions in order to understand what codes