Add section on running ad-hoc Perl programs to the nixpkgs manual

Co-authored-by: Timo Kaufmann <timokau@zoho.com>

doc/languages-frameworks/perl.xml

@@ -3,6 +3,39 @@
          xml:id="sec-language-perl">
  <title>Perl</title>
 
+ <section xml:id="ssec-perl-running">
+  <title>Running perl programs on the shell</title>
+
+  <para>
+   When executing a Perl script, it is possible you get an error such as <literal>./myscript.pl: bad interpreter: /usr/bin/perl: no such file or directory</literal>. This happens when the script expects Perl to be installed at <filename>/usr/bin/perl</filename>, which is not the case when using Perl from nixpkgs. You can fix the script by changing the first line to:
+  <programlisting>
+  #!/usr/bin/env perl
+  </programlisting>
+  to take the Perl installation from the <literal>PATH<literal> environment variable, or invoke Perl directly with:
+  <screen>
+  <prompt>$ </prompt>perl ./myscript.pl
+  </screen>
+  </para>
+
+  <para>
+   When the script is using a Perl library that is not installed globally, you might get an error such as <literal>Can't locate DB_File.pm in @INC (you may need to install the DB_File module)</literal>. In that case, you can use <command>nix-shell</command> to start an ad-hoc shell with that library installed, for instance:
+  <screen>
+  <prompt>$ </prompt>nix-shell -p perl perlPackages.DBFile --run ./myscript.pl
+  </screen>
+  </para>
+
+  <para>
+  If you are always using the script in places where <command>nix-shell</command> is available, you can embed the <command>nix-shell</command> invocation in the shebang like this:
+  <programlisting>
+  #!/usr/bin/env nix-shell
+  #! nix-shell -i perl -p perl perlPackages.DBFile
+  </programlisting>
+  </para>
+ </section>
+
+ <section xml:id="ssec-perl-packaging">
+  <title>Packaging Perl programs</title>
+
   <para>
    Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic package builder function for any Perl package that has a standard <varname>Makefile.PL</varname>. It’s implemented in <link
  xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.
@@ -159,3 +192,4 @@ ImageExifTool = buildPerlPackage {
    </para>
   </section>
  </section>
+</section>