Clarify documentation about startup script requirements. Markdown improvements in README.

Fixes #261

2 files changed, 73 insertions, 68 deletions

diff --git a/README.md b/README.md
index 93b444e..a893d0b 100644
--- a/README.md
+++ b/README.md
@@ -33,29 +33,29 @@ Bourne shell, provided of course that the compression programs are available.
 As of version 2.1, Makeself has been rewritten and tested on the following
 platforms :
 
-  * Linux (all distributions)
-  * Sun Solaris (8 and above)
-  * HP-UX (tested on 11.0 and 11i on HPPA RISC)
-  * SCO OpenUnix and OpenServer
-  * IBM AIX 5.1L
-  * macOS (Darwin)
-  * SGI IRIX 6.5
-  * FreeBSD
-  * UnicOS / Cray
-  * Cygwin (Windows)
+* Linux (all distributions)
+* Sun Solaris (8 and above)
+* HP-UX (tested on 11.0 and 11i on HPPA RISC)
+* SCO OpenUnix and OpenServer
+* IBM AIX 5.1L
+* macOS (Darwin)
+* SGI IRIX 6.5
+* FreeBSD
+* UnicOS / Cray
+* Cygwin (Windows)
 
 If you successfully run Makeself and/or archives created with it on another
 system, then please [let me know][2]!
 
 Examples of publicly available archives made using makeself are :
 
-  * Game patches and installers for [Id Software][3] games like Quake 3 for Linux or Return To Castle Wolfenstein ;
-  * All game patches released by [Loki Software][4] for the Linux version of popular games ;
-  * The [nVidia drivers][5] for Linux
-  * The installer for the Linux version of [Google Earth][6]
-  * The [VirtualBox][7] installers for Linux
-  * The [Makeself][1] distribution itself ;-)
-  * and countless others...
+* Game patches and installers for [Id Software][3] games like Quake 3 for Linux or Return To Castle Wolfenstein ;
+* All game patches released by [Loki Software][4] for the Linux version of popular games ;
+* The [nVidia drivers][5] for Linux
+* The installer for the Linux version of [Google Earth][6]
+* The [VirtualBox][7] installers for Linux
+* The [Makeself][1] distribution itself ;-)
+* and countless others...
 
 **Important note for Apache users:** By default, most Web servers will think that Makeself archives are regular text files and thus they may show up as text in a Web browser. The correct way to prevent this is to add a MIME type for this file format, like so (in httpd.conf) :
 
@@ -69,7 +69,7 @@ Examples of publicly available archives made using makeself are :
 
 The syntax of makeself is the following:
 
-```
+```sh
 makeself.sh [args] archive_dir file_name label startup_script [script_args]
 ```
 
@@ -117,34 +117,36 @@ makeself.sh [args] archive_dir file_name label startup_script [script_args]
   * `file_name` is the name of the archive to be created
   * `label` is an arbitrary text string describing the package. It will be displayed while extracting the files.
   * `startup_script` is the command to be executed _from within_ the directory of extracted files. Thus, if you wish to execute a program contained in this directory, you must prefix your command with `./`. For example, `./program` will be fine. The `script_args` are additional arguments for this command.
+  Note that `startup_script` and its arguments are not strictly required for archives that don't extract in a temporary directory (i.e. when using `--notemp`).
 
 Here is an example, assuming the user has a package image stored in a **/home/joe/mysoft**, and he wants to generate a self-extracting package named
 **mysoft.sh**, which will launch the "setup" script initially stored in /home/joe/mysoft :
 
-`makeself.sh /home/joe/mysoft mysoft.sh "Joe's Nice Software Package" ./setup
-`
+```sh
+makeself.sh /home/joe/mysoft mysoft.sh "Joe's Nice Software Package" ./setup
+```
 
 Here is also how I created the [makeself.run][9] archive which contains the Makeself distribution :
 
-`makeself.sh --notemp makeself makeself.run "Makeself by Stephane Peter" echo "Makeself has extracted itself" `
+`makeself.sh --notemp makeself makeself.run "Makeself by Stephane Peter" echo "Makeself has extracted itself"`
 
 Archives generated with Makeself can be passed the following arguments:
 
-  * **`--keep`** : Prevent the files to be extracted in a temporary directory that will be removed after the embedded script's execution. The files will then be extracted in the current working directory and will stay here until you remove them.
-  * **`--verbose`** : Will prompt the user before executing the embedded command
-  * **`--target dir`** : Allows to extract the archive in an arbitrary place.
-  * **`--nox11`** : Do not spawn a X11 terminal.
-  * **`--confirm`** : Prompt the user for confirmation before running the embedded command.
-  * **`--info`** : Print out general information about the archive (does not extract).
-  * **`--lsm`** : Print out the LSM entry, if it is present.
-  * **`--list`** : List the files in the archive.
-  * **`--check`** : Check the archive for integrity using the embedded checksums. Does not extract the archive.
-  * **`--nochown`** : By default, a `chown -R` command is run on the target directory after extraction, so that all files belong to the current user. This is mostly needed if you are running as root, as tar will then try to recreate the initial user ownerships. You may disable this behavior with this flag.
-  * **`--tar`** : Run the tar command on the contents of the archive, using the following arguments as parameter for the command.
-  * **`--noexec`** : Do not run the embedded script after extraction.
-  * **`--noexec-cleanup`** : Do not run the embedded cleanup script.
-  * **`--nodiskspace`** : Do not check for available disk space before attempting to extract.
-  * **`--cleanup-args`** : Specify arguments to be passed to the cleanup script. Wrap value in quotes to specify multiple arguments.
+* **`--keep`** : Prevent the files to be extracted in a temporary directory that will be removed after the embedded script's execution. The files will then be extracted in the current working directory and will stay here until you remove them.
+* **`--verbose`** : Will prompt the user before executing the embedded command
+* **`--target dir`** : Allows to extract the archive in an arbitrary place.
+* **`--nox11`** : Do not spawn a X11 terminal.
+* **`--confirm`** : Prompt the user for confirmation before running the embedded command.
+* **`--info`** : Print out general information about the archive (does not extract).
+* **`--lsm`** : Print out the LSM entry, if it is present.
+* **`--list`** : List the files in the archive.
+* **`--check`** : Check the archive for integrity using the embedded checksums. Does not extract the archive.
+* **`--nochown`** : By default, a `chown -R` command is run on the target directory after extraction, so that all files belong to the current user. This is mostly needed if you are running as root, as tar will then try to recreate the initial user ownerships. You may disable this behavior with this flag.
+* **`--tar`** : Run the tar command on the contents of the archive, using the following arguments as parameter for the command.
+* **`--noexec`** : Do not run the embedded script after extraction.
+* **`--noexec-cleanup`** : Do not run the embedded cleanup script.
+* **`--nodiskspace`** : Do not check for available disk space before attempting to extract.
+* **`--cleanup-args`** : Specify arguments to be passed to the cleanup script. Wrap value in quotes to specify multiple arguments.
 
 Any subsequent arguments to the archive will be passed as additional arguments to the embedded command. You must explicitly use the `--` special command-line construct before any such options to make sure that Makeself will not try to interpret them.
 
@@ -154,7 +156,9 @@ The startup script must be a regular Shell script.
 
 Within the startup script, you can use the `$USER_PWD` variable to get the path of the folder from which the self-extracting script is executed. This is especially useful to access files that are located in the same folder as the script, as shown in the example below. 
 
-`my-self-extracting-script.sh --fooBarFileParameter foo.bar`
+```sh
+my-self-extracting-script.sh --fooBarFileParameter foo.bar
+```
 
 ## Building and Testing
 
@@ -175,8 +179,8 @@ Makeself itself is covered by the [GNU General Public License][8] (GPL) version
 
 I will gladly consider merging your pull requests on the [GitHub][10] repository. However, please keep the following in mind:
 
-  * One of the main purposes of Makeself is portability. Do not submit patches that will break supported platforms. The more platform-agnostic, the better.
-  * Please explain clearly what the purpose of the patch is, and how you achieved it.
+* One of the main purposes of Makeself is portability. Do not submit patches that will break supported platforms. The more platform-agnostic, the better.
+* Please explain clearly what the purpose of the patch is, and how you achieved it.
 
 ## Download
 
@@ -186,34 +190,34 @@ The latest development version can be grabbed from [GitHub][10]. Feel free to su
 
 ## Version history
 
-  * **v1.0:** Initial public release
-  * **v1.1:** The archive can be passed parameters that will be passed on to the embedded script, thanks to John C. Quillan
-  * **v1.2:** Cosmetic updates, support for bzip2 compression and non-temporary archives. Many ideas thanks to Francois Petitjean.
-  * **v1.3:** More patches from Bjarni R. Einarsson and Francois Petitjean: Support for no compression (`--nocomp`), script is no longer mandatory, automatic launch in an xterm, optional verbose output, and -target archive option to indicate where to extract the files.
-  * **v1.4:** Many patches from Francois Petitjean: improved UNIX compatibility, automatic integrity checking, support of LSM files to get info on the package at run time..
-  * **v1.5.x:** A lot of bugfixes, and many other patches, including automatic verification through the usage of checksums. Version 1.5.5 was the stable release for a long time, even though the Web page didn't get updated ;-). Makeself was also officially made a part of the [Loki Setup installer][11], and its source is being maintained as part of this package.
-  * **v2.0:** Complete internal rewrite of Makeself. The command-line parsing was vastly improved, the overall maintenance of the package was greatly improved by separating the stub from makeself.sh. Also Makeself was ported and tested to a variety of Unix platforms.
-  * **v2.0.1:** First public release of the new 2.0 branch. Prior versions are officially obsoleted. This release introduced the `--copy` argument that was introduced in response to a need for the [UT2K3][12] Linux installer.
-  * **v2.1.0:** Big change : Makeself can now support multiple embedded tarballs, each stored separately with their own checksums. An existing archive can be updated with the `--append` flag. Checksums are also better managed, and the `--nochown` option for archives appeared.
-  * **v2.1.1:** Fixes related to the Unix compression (compress command). Some Linux distributions made the insane choice to make it unavailable, even though gzip is capable of uncompressing these files, plus some more bugfixes in the extraction and checksum code.
-  * **v2.1.2:** Some bug fixes. Use head -n to avoid problems with POSIX conformance.
-  * **v2.1.3:** Bug fixes with the command line when spawning terminals. Added `--tar`, `--noexec` for archives. Added `--nomd5` and `--nocrc` to avoid creating checksums in archives. The embedded script is now run through "eval". The `--info` output now includes the command used to create the archive. A man page was contributed by Bartosz Fenski.
-  * **v2.1.4:** Fixed `--info` output. Generate random directory name when extracting files to . to avoid problems. Better handling of errors with wrong permissions for the directory containing the files. Avoid some race conditions, Unset the $CDPATH variable to avoid problems if it is set. Better handling of dot files in the archive directory.
-  * **v2.1.5:** Made the md5sum detection consistent with the header code. Check for the presence of the archive directory. Added `--encrypt` for symmetric encryption through gpg (Eric Windisch). Added support for the digest command on Solaris 10 for MD5 checksums. Check for available disk space before extracting to the target directory (Andreas Schweitzer). Allow extraction to run asynchronously (patch by Peter Hatch). Use file descriptors internally to avoid error messages (patch by Kay Tiong Khoo).
-  * **v2.1.6:** Replaced one dot per file progress with a realtime progress percentage and a spinning cursor. Added `--noprogress` to prevent showing the progress during the decompression. Added `--target` dir to allow extracting directly to a target directory. (Guy Baconniere)
-  * **v2.2.0:** First major new release in years! Includes many bugfixes and user contributions. Please look at the [project page on Github][10] for all the details.
-  * **v2.3.0:** Support for archive encryption via GPG or OpenSSL. Added LZO and LZ4 compression support. Options to set the packaging date and stop the umask from being overriden. Optionally ignore check for available disk space when extracting. New option to check for root permissions before extracting.
-  * **v2.3.1:** Various compatibility updates. Added unit tests for Travis CI in the GitHub repo. New `--tar-extra`, `--untar-extra`, `--gpg-extra`, `--gpg-asymmetric-encrypt-sign` options.
-  * **v2.4.0:** Added optional support for SHA256 archive integrity checksums.
-  * **v2.4.2:** New --cleanup and --cleanup-args arguments for cleanup scripts. Added threading support for supported compressors. Now supports zstd compression.
-  * **v2.4.3:** Make explicit POSIX tar archives for increased compatibility.
-  * **v2.4.4:** Fixed various compatibility issues (no longer use POSIX tar archives), Github Actions to check on Solaris and FreeBSD.
-  * **v2.4.5:** Added `--tar-format` option to set the tar archive format (default is ustar)
+* **v1.0:** Initial public release
+* **v1.1:** The archive can be passed parameters that will be passed on to the embedded script, thanks to John C. Quillan
+* **v1.2:** Cosmetic updates, support for bzip2 compression and non-temporary archives. Many ideas thanks to Francois Petitjean.
+* **v1.3:** More patches from Bjarni R. Einarsson and Francois Petitjean: Support for no compression (`--nocomp`), script is no longer mandatory, automatic launch in an xterm, optional verbose output, and -target archive option to indicate where to extract the files.
+* **v1.4:** Many patches from Francois Petitjean: improved UNIX compatibility, automatic integrity checking, support of LSM files to get info on the package at run time..
+* **v1.5.x:** A lot of bugfixes, and many other patches, including automatic verification through the usage of checksums. Version 1.5.5 was the stable release for a long time, even though the Web page didn't get updated ;-). Makeself was also officially made a part of the [Loki Setup installer][11], and its source is being maintained as part of this package.
+* **v2.0:** Complete internal rewrite of Makeself. The command-line parsing was vastly improved, the overall maintenance of the package was greatly improved by separating the stub from makeself.sh. Also Makeself was ported and tested to a variety of Unix platforms.
+* **v2.0.1:** First public release of the new 2.0 branch. Prior versions are officially obsoleted. This release introduced the `--copy` argument that was introduced in response to a need for the [UT2K3][12] Linux installer.
+* **v2.1.0:** Big change : Makeself can now support multiple embedded tarballs, each stored separately with their own checksums. An existing archive can be updated with the `--append` flag. Checksums are also better managed, and the `--nochown` option for archives appeared.
+* **v2.1.1:** Fixes related to the Unix compression (compress command). Some Linux distributions made the insane choice to make it unavailable, even though gzip is capable of uncompressing these files, plus some more bugfixes in the extraction and checksum code.
+* **v2.1.2:** Some bug fixes. Use head -n to avoid problems with POSIX conformance.
+* **v2.1.3:** Bug fixes with the command line when spawning terminals. Added `--tar`, `--noexec` for archives. Added `--nomd5` and `--nocrc` to avoid creating checksums in archives. The embedded script is now run through "eval". The `--info` output now includes the command used to create the archive. A man page was contributed by Bartosz Fenski.
+* **v2.1.4:** Fixed `--info` output. Generate random directory name when extracting files to . to avoid problems. Better handling of errors with wrong permissions for the directory containing the files. Avoid some race conditions, Unset the $CDPATH variable to avoid problems if it is set. Better handling of dot files in the archive directory.
+* **v2.1.5:** Made the md5sum detection consistent with the header code. Check for the presence of the archive directory. Added `--encrypt` for symmetric encryption through gpg (Eric Windisch). Added support for the digest command on Solaris 10 for MD5 checksums. Check for available disk space before extracting to the target directory (Andreas Schweitzer). Allow extraction to run asynchronously (patch by Peter Hatch). Use file descriptors internally to avoid error messages (patch by Kay Tiong Khoo).
+* **v2.1.6:** Replaced one dot per file progress with a realtime progress percentage and a spinning cursor. Added `--noprogress` to prevent showing the progress during the decompression. Added `--target` dir to allow extracting directly to a target directory. (Guy Baconniere)
+* **v2.2.0:** First major new release in years! Includes many bugfixes and user contributions. Please look at the [project page on Github][10] for all the details.
+* **v2.3.0:** Support for archive encryption via GPG or OpenSSL. Added LZO and LZ4 compression support. Options to set the packaging date and stop the umask from being overriden. Optionally ignore check for available disk space when extracting. New option to check for root permissions before extracting.
+* **v2.3.1:** Various compatibility updates. Added unit tests for Travis CI in the GitHub repo. New `--tar-extra`, `--untar-extra`, `--gpg-extra`, `--gpg-asymmetric-encrypt-sign` options.
+* **v2.4.0:** Added optional support for SHA256 archive integrity checksums.
+* **v2.4.2:** New --cleanup and --cleanup-args arguments for cleanup scripts. Added threading support for supported compressors. Now supports zstd compression.
+* **v2.4.3:** Make explicit POSIX tar archives for increased compatibility.
+* **v2.4.4:** Fixed various compatibility issues (no longer use POSIX tar archives), Github Actions to check on Solaris and FreeBSD.
+* **v2.4.5:** Added `--tar-format` option to set the tar archive format (default is ustar)
 
 ## Links
 
-  * Check out the ["Loki Setup"][11] installer, used to install many Linux games and other applications, and of which I am the co-author. Since the demise of Loki, I am now the official maintainer of the project, and it is now being hosted here on GitHub.
-  * Bjarni R. Einarsson also wrote the **setup.sh** installer script, inspired by Makeself. [Check it out !][14]
+* Check out the ["Loki Setup"][11] installer, used to install many Linux games and other applications, and of which I am the co-author. Since the demise of Loki, I am now the official maintainer of the project, and it is now being hosted here on GitHub.
+* Bjarni R. Einarsson also wrote the **setup.sh** installer script, inspired by Makeself. [Check it out !][14]
 
 ## Contact
 
diff --git a/makeself.sh b/makeself.sh
index f8f7da6..df55a8d 100755
--- a/makeself.sh
+++ b/makeself.sh
@@ -135,8 +135,9 @@ MS_Usage()
     echo "    --nochown          : Do not give the target folder to the current user (default)"
     echo "    --chown            : Give the target folder to the current user recursively"
     echo "    --nocomp           : Do not compress the data"
-    echo "    --notemp           : The archive will create archive_dir in the"
-    echo "                         current directory and uncompress in ./archive_dir"
+    echo "    --notemp           : The archive will create archive_dir in the current directory"
+    echo "                         and uncompress in ./archive_dir"
+    echo "                         Note: persistent archives do not strictly require a startup_script"
     echo "    --needroot         : Check that the root user is extracting the archive before proceeding"
     echo "    --copy             : Upon extraction, the archive will first copy itself to"
     echo "                         a temporary directory"
@@ -144,9 +145,9 @@ MS_Usage()
     echo "                         The label and startup scripts will then be ignored"
     echo "    --target dir       : Extract directly to a target directory"
     echo "                         directory path can be either absolute or relative"
-    echo "    --nooverwrite      : Do not extract the archive if the specified target directory exists"
     echo "    --current          : Files will be extracted to the current directory"
-    echo "                         Both --current and --target imply --notemp"
+    echo "                         Both --current and --target imply --notemp, and do not require a startup_script"
+    echo "    --nooverwrite      : Do not extract the archive if the specified target directory exists"
     echo "    --tar-format opt   : Specify a tar archive format (default is ustar)"
     echo "    --tar-extra opt    : Append more options to the tar command line"
     echo "    --untar-extra opt  : Append more options to the during the extraction of the tar archive"