more documentation improvements

Changes

@@ -1,7 +1,7 @@
 Revision history for Perl module {{$dist->name}}
 
 {{$NEXT}}
-  - Documentation improvements (gh#30)
+  - Documentation improvements (gh#30, gh#31)
 
 1.16_01   2022-09-11 15:29:26 -0600
   - Add support for ALIEN_DOWNLOAD_RULE (gh#28, gh#29)

README.md

@@ -25,7 +25,7 @@ my $builder = Alien::Base::ModuleBuild->new(
                              # system version of the mylibrary
 
   alien_repository => {
-    protocol => 'http',
+    protocol => 'https',
     host     => 'myhost.org',
     location => '/path/to/tarballs',
     pattern  => qr{^mylibrary-([0-9\.]+)\.tar\.gz$},
@@ -144,11 +144,12 @@ this method.
 my %result = $amb->alien_do_system($cmd)
 ```
 
-Similar to [Module::Build::do\_system](https://metacpan.org/pod/Module::Build::do_system), also sets the path and several
-environment variables in accordance to the object configuration
-(i.e. `alien_bin_requires`) and performs the interpolation of the
-patterns described in ["COMMAND
-INTERPOLATION" in Alien::Base::ModuleBuild::API](https://metacpan.org/pod/Alien::Base::ModuleBuild::API#COMMAND-INTERPOLATION).
+Similar to
+[Module::Build's do\_system](https://metacpan.org/pod/Module::Build::API#do_system-cmd-args),
+also sets the path and several environment variables in accordance
+to the object configuration (i.e. `alien_bin_requires`) and
+performs the interpolation of the patterns described in
+["COMMAND INTERPOLATION" in Alien::Base::ModuleBuild::API](https://metacpan.org/pod/Alien::Base::ModuleBuild::API#COMMAND-INTERPOLATION).
 
 Returns a set of key value pairs including `stdout`, `stderr`,
 `success` and `command`.
@@ -227,6 +228,19 @@ The documentation for `Module::Build` is broken up into sections:
     This is a reference to the `Alien::Base::ModuleBuild` API beyond that contained
     in `Module::Build::API`.
 
+- Using the resulting [Alien](https://metacpan.org/pod/Alien) ([Alien::Build::Manual::AlienUser](https://metacpan.org/pod/Alien::Build::Manual::AlienUser))
+
+    Once you have an [Alien](https://metacpan.org/pod/Alien) you or your users can review this manual for how to use
+    it.  Generally speaking you should have some useful usage information in your
+    [Alien](https://metacpan.org/pod/Alien)'s POD, but some authors choose to direct their users to this manual
+    instead.
+
+- Using [Alien::Build](https://metacpan.org/pod/Alien::Build) instead ([Alien::Build::Manual](https://metacpan.org/pod/Alien::Build::Manual))
+
+    As mentioned at the top, you are encouraged to use the [Alien::Build](https://metacpan.org/pod/Alien::Build) and
+    [alienfile](https://metacpan.org/pod/alienfile) system instead.  This manual is a starting point for the other
+    [Alien::Build](https://metacpan.org/pod/Alien::Build) documentation.
+
 # ENVIRONMENT
 
 - **ALIEN\_ARCH**
@@ -275,7 +289,7 @@ The documentation for `Module::Build` is broken up into sections:
 
 - **ALIEN\_INSTALL\_TYPE**
 
-    Set to 'share' or 'system' to override the install type.  Set to 'default' or unset
+    Set to `share` or `system` to override the install type.  Set to `default` or unset
     to restore the default.
 
 - **ALIEN\_VERBOSE**

lib/Alien/Base/ModuleBuild.pm

@@ -1319,7 +1319,7 @@ In your Build.PL:
                               # system version of the mylibrary
  
    alien_repository => {
-     protocol => 'http',
+     protocol => 'https',
      host     => 'myhost.org',
      location => '/path/to/tarballs',
      pattern  => qr{^mylibrary-([0-9\.]+)\.tar\.gz$},
@@ -1432,11 +1432,12 @@ this method.
 
   my %result = $amb->alien_do_system($cmd)
 
-Similar to L<Module::Build::do_system>, also sets the path and several
-environment variables in accordance to the object configuration
-(i.e. C<alien_bin_requires>) and performs the interpolation of the
-patterns described in L<Alien::Base::ModuleBuild::API/COMMAND
-INTERPOLATION>.
+Similar to
+L<Module::Build's do_system|Module::Build::API/"do_system($cmd, @args)">,
+also sets the path and several environment variables in accordance
+to the object configuration (i.e. C<alien_bin_requires>) and
+performs the interpolation of the patterns described in
+L<Alien::Base::ModuleBuild::API/"COMMAND INTERPOLATION">.
 
 Returns a set of key value pairs including C<stdout>, C<stderr>,
 C<success> and C<command>.
@@ -1509,6 +1510,19 @@ L<Alien::Base> projects, it is located in the upper namespace.
 This is a reference to the C<Alien::Base::ModuleBuild> API beyond that contained
 in C<Module::Build::API>.
 
+=item Using the resulting L<Alien> (L<Alien::Build::Manual::AlienUser>)
+
+Once you have an L<Alien> you or your users can review this manual for how to use
+it.  Generally speaking you should have some useful usage information in your
+L<Alien>'s POD, but some authors choose to direct their users to this manual
+instead.
+
+=item Using L<Alien::Build> instead (L<Alien::Build::Manual>)
+
+As mentioned at the top, you are encouraged to use the L<Alien::Build> and
+L<alienfile> system instead.  This manual is a starting point for the other
+L<Alien::Build> documentation.
+
 =back
 
 =head1 ENVIRONMENT
@@ -1565,7 +1579,7 @@ Set to C<0> or another false value to turn off network installs.
 
 =item B<ALIEN_INSTALL_TYPE>
 
-Set to 'share' or 'system' to override the install type.  Set to 'default' or unset
+Set to C<share> or C<system> to override the install type.  Set to C<default> or unset
 to restore the default.
 
 =item B<ALIEN_VERBOSE>

lib/Alien/Base/ModuleBuild/API.pod

@@ -5,17 +5,17 @@
 =head1 DESCRIPTION
 
 B<NOTE>: Please consider for new development of L<Alien>s that you use
-L<Alien::Build> and L<alienfile> instead.  Like L<Alien::Base::ModuleBUild> they work
-with L<Alien::Base>.  Unlike L<Alien::Base::Module::Build> they are more easily customized
+L<Alien::Build> and L<alienfile> instead.  Like L<Alien::Base::ModuleBuild> they work
+with L<Alien::Base>.  Unlike L<Alien::Base::ModuleBuild> they are more easily customized
 and handle a number of corner cases better.  For a good place to start,
-please see L<Alien::Build::Manual::AlienAuthor>.  Although the 
+please see L<Alien::Build::Manual::AlienAuthor>.  Although the
 Alien-Base / Alien-Build team will continue to maintain this module,
 (we will continue to fix bugs where appropriate), we aren't adding any
 new features to this module.
 
-A list of extra properties and methods provided by 
+A list of extra properties and methods provided by
 L<Alien::Base::ModuleBuild> beyond those contained in L<Module::Build::API>.
-Note that all property and method names are prefixed with C<alien_> to prevent future 
+Note that all property and method names are prefixed with C<alien_> to prevent future
 collisions L<Module::Build> builtins.
 
 =head2 CONSTRUCTOR
@@ -78,14 +78,14 @@ to remove the variable.
  );
  ...
 
-Please keep in mind that frequently users have a good reason to have set 
-environment variables, and you should not override them without a good 
-reason.  An example of a good justification would be if a project has a 
-Makefile that interacts badly with common environment variables.  This 
+Please keep in mind that frequently users have a good reason to have set
+environment variables, and you should not override them without a good
+reason.  An example of a good justification would be if a project has a
+Makefile that interacts badly with common environment variables.  This
 can sometimes be a problem since Makefile variables can be overridden with
 environment variables.
 
-A useful pattern is to use a helper to only override an environment 
+A useful pattern is to use a helper to only override an environment
 variable if it is not already set.
 
  ...
@@ -101,7 +101,7 @@ variable if it is not already set.
  );
  ...
 
-A common pitfall with environment variables is that setting one to the 
+A common pitfall with environment variables is that setting one to the
 empty string (C<''>) is not portable.  On Unix it works fine as you would
 expect, but in Windows it actually unsets the environment variable, which
 may not be what you intend.
@@ -164,10 +164,10 @@ By default alien_name is used with any C<lib> prefix removed.  For example C<lib
 
 [version 0.020]
 
-Provide helpers to generate commands or arguments at build or install time.  This property is a hash 
-reference.  The keys are the helper names and the values are strings containing Perl code that will 
-be evaluated and interpolated into the command before execution.  Because helpers are only needed 
-when building a package from the source code, any dependency may be specified as an 
+Provide helpers to generate commands or arguments at build or install time.  This property is a hash
+reference.  The keys are the helper names and the values are strings containing Perl code that will
+be evaluated and interpolated into the command before execution.  Because helpers are only needed
+when building a package from the source code, any dependency may be specified as an
 C<alien_bin_requires>.  For example:
 
  ...
@@ -344,15 +344,15 @@ The name of the temporary folder which will house the library when it is downloa
 
 [version 0.001]
 
-An arrayref of commands used to test the library.  Each command is first 
+An arrayref of commands used to test the library.  Each command is first
 passed through the L<command interpolation engine|/"COMMAND INTERPOLATION">,
 so those variables may be used.  The default is to do no tests.  The most
 common command used by the GNU toolchain is C<[ 'make check' ]>, but beware
 that is not supported by all packages.
 
 [version 0.009]
 
-Each command may be either a string or an array reference.  If the array 
+Each command may be either a string or an array reference.  If the array
 reference form is used, then the multiple argument form of system is used.
 
 =item alien_version_check
@@ -367,7 +367,7 @@ A command to run to check the version of the library installed on the system. Th
 
 A few global variables are used to set gross behavior. For each pair of variables, if both are set, the environment variable takes precedence.
 
-=over 
+=over
 
 =item $ENV{ALIEN_ARCH}
 
@@ -379,7 +379,7 @@ integrators creating a single non-architecture specific RPM, .deb or similar pac
 
 =item $ENV{ALIEN_BLIB}
 
-Setting this to true indicates that you don't intend to actually install your Alien::Base subclass, but rather use it from the built F<blib> directory. This behavior is mostly to support automated testing from CPANtesters and should be automagically determined. If by chance you happen to trip the behavior accidentally, setting this environment variable to false (0) before building should prevent problems. 
+Setting this to true indicates that you don't intend to actually install your Alien::Base subclass, but rather use it from the built F<blib> directory. This behavior is mostly to support automated testing from CPANtesters and should be automagically determined. If by chance you happen to trip the behavior accidentally, setting this environment variable to false (0) before building should prevent problems.
 
 =item $Alien::Base::ModuleBuild::Force
 
@@ -395,7 +395,7 @@ Setting to C<share> will ignore a system-wide installation and build a local ver
 
 =item $ENV{ALIEN_VERBOSE}
 
-Setting the either to a true value will output a little more info from within the module itself. At this point L<Alien::Base> is going to be fairly verbose without this enabled. 
+Setting the either to a true value will output a little more info from within the module itself. At this point L<Alien::Base> is going to be fairly verbose without this enabled.
 
 =back
 
@@ -511,7 +511,7 @@ A literal C<%>.
 
 =over
 
-=item * 
+=item *
 
 L<Module::Build::API>
 

lib/Alien/Base/ModuleBuild/Authoring.pod

@@ -6,9 +6,9 @@
 
 B<NOTE>: Please consider for new development of L<Alien>s that you use
 L<Alien::Build> and L<alienfile> instead.  Like L<Alien::Base::ModuleBuild> they work
-with L<Alien::Base>.  Unlike L<Alien::Base::Module::Build> they are more easily customized
+with L<Alien::Base>.  Unlike L<Alien::Base::ModuleBuild> they are more easily customized
 and handle a number of corner cases better.  For a good place to start,
-please see L<Alien::Build::Manual::AlienAuthor>.  Although the 
+please see L<Alien::Build::Manual::AlienAuthor>.  Although the
 Alien-Base / Alien-Build team will continue to maintain this module,
 (we will continue to fix bugs where appropriate), we aren't adding any
 new features to this module.
@@ -17,8 +17,8 @@ Congratulations! You have made the decision to help the Perl community by provid
 
 =head1 STATUS
 
-L<Alien::Base> is under active development.  The API is relatively 
-stable, although breaking changes may be introduced if the rewards are 
+L<Alien::Base> is under active development.  The API is relatively
+stable, although breaking changes may be introduced if the rewards are
 deemed greater than the pains that they produce.
 
 =head1 ECOSYSTEM
@@ -51,7 +51,7 @@ C<Alien::MyLibrary> is called by C<Some::Library::MyLibrary>'s build script, eit
  # file: Some-Module-MyLibrary/Build.PL
  use Module::Build;
  use Alien::MyLibrary;
-
+ 
  my $alien = Alien::MyLibrary->new;
  my $builder = Module::Build->new(
    ...
@@ -68,22 +68,22 @@ C<Alien::MyLibrary> must be a subclass of L<Alien::Base>. This provides the C<im
 
  # file: Alien-MyLibrary/lib/Alien/MyLibrary.pm
  package Alien::MyLibrary;
-
+ 
  use parent 'Alien::Base';
-
+ 
  1;
 
 Finally, C<Alien::MyLibrary> must also be called by C<Some::Library::MyLibrary> before C<DynaLoader::bootstrap> or C<XSLoader::load>. The C<use> directive is recommended, however if you must use C<require> then be sure to call the C<import> method too. Without this C<import> call, the loader doesn't know where to find F<libmylibrary.so>.
 
  # file: Some-Module-MyLibrary/lib/Some/Module/MyLibrary.pm
  package Some::Module::MyLibrary;
-
+ 
  use Alien::MyLibrary;
  our $VERSION = '0.54';
-
+ 
  require XSLoader;
  XSLoader::load('Some::Module::MyLibrary', $VERSION);
-
+ 
  # your code
 
 =head1 EXAMPLES
@@ -126,7 +126,7 @@ L<Alien::gmake> -- Builds and installs GNU make.  Rather than being a library, t
 
 =over
 
-=item * 
+=item *
 
 L<Module::Build>