Enhance atest/README.rst, especially related to jar distro.

Also document --jar-name option in `invoke jar` and add `.jar`
extension if needed.

BUILD.rst

@@ -207,6 +207,11 @@ Creating distributions
        java -jar dist/robotframework-$VERSION.jar --version
        java -jar dist/robotframework-$VERSION.jar atest/testdata/misc/pass_and_fail.robot
 
+    - To create a JAR with a custom name for testing::
+
+       invoke jar --jar-name=example
+       java -jar dist/example.jar --version
+
 8. Upload JAR to Sonatype
 
    - Sonatype offers a service where users can upload JARs and they will be synced

atest/README.rst

@@ -53,23 +53,37 @@ executed with Python 3.6 or newer. Run it with ``--help`` or see
 documentation in its `source code <run.py>`__ for more information.
 
 To run all the acceptance tests, execute the ``atest/robot`` folder
-entirely using the selected interpreter::
+entirely using the selected interpreter. If the interpreter itself needs
+arguments, the interpreter and its arguments need to be quoted.
+
+Examples::
 
     atest/run.py python atest/robot
     atest/run.py jython atest/robot
+    atest/run.py "py -3" atest/robot
+
+When running tests with the standalone jar distribution, the jar needs to
+be first created with command ``invoke jar`` (see `<../BUILD.rst>`__ for
+details):
+
+    invoke jar --jar-name=atest
+    atest/run.py dist/atest.jar atest/robot
 
 The commands above will execute all tests, but you typically want to skip
 `Telnet tests`_ and tests requiring manual interaction. These tests are marked
 with the ``no-ci`` tag and can be easily excluded::
 
     atest/run.py python --exclude no-ci atest/robot
 
+On modern machines running all acceptance tests ought to take less than ten
+minutes with Python, but with Jython and IronPython the execution time can be
+several hours.
+
 A sub test suite can be executed simply by running the folder or file
-containing it. On modern machines running all acceptance tests ought to
-take less than ten minutes with Python, but with Jython the execution time
-is considerably longer. This is due to Jython being somewhat slower than
-Python in general, but the main reason is that the JVM is started by
-acceptance tests dozens of times and that always takes a few seconds.
+containing it::
+
+    atest/run.py python atest/robot/libdoc
+    atest/run.py python atest/robot/libdoc/resource_file.robot
 
 Before a release tests should be executed separately using Python, Jython,
 IronPython and PyPy to verify interoperability with all supported interpreters.
@@ -146,10 +160,6 @@ Examples:
     # than running all tests on Jython.
     atest/run.py jython --include require-jython atest/robot
 
-    # Recreate the standalone jar distribution and use it as an interpreter.
-    invoke jar
-    atest/run.py dist/robotframework-3.2b3.dev1.jar --exclude no-ci atest/robot
-
 Preconditions
 -------------
 

tasks.py

@@ -182,6 +182,9 @@ def jar(ctx, jython_version='2.7.2', pyyaml_version='5.1',
             `jython-standalone-<version>.jar` found from Maven central.
         pyyaml_version: Version of PyYAML that will be included in the
             standalone jar. The version must be available from PyPI.
+        jar_name: Name of the jar file. If not given, name is constructed
+            based on the version. The `.jar` extension is added automatically
+            if needed and the jar is always created under the `dist` directory.
         remove_dist:  Control is 'dist' directory initially removed or not.
     """
     clean(ctx, remove_dist, create_dirs=True)
@@ -276,6 +279,8 @@ def create_robot_jar(ctx, version, name=None, source='build'):
     write_manifest(version, source)
     if not name:
         name = f'robotframework-{version}.jar'
+    elif not name.endswith('.jar'):
+        name += '.jar'
     target = Path(f'dist/{name}')
     ctx.run(f'jar cvfM {target} -C {source} .')
     print(f"Created '{target}'.")