Improve "fully executable jars" documentation

Closes gh-5505

spring-boot-docs/src/main/asciidoc/deployment.adoc

@@ -394,6 +394,9 @@ With Gradle, the equivalent configuration would be:
 	}
 ----
 
+You can then run your application by typing `./my-application.jar` (where
+`my-application` is the name of your artifact).
+
 NOTE: Fully executable jars work by embedding an extra script at the front of the file.
 Not all tools currently accept this format so you may not always be able to use this
 technique.
@@ -415,9 +418,13 @@ or `systemd`.
 
 [[deployment-initd-service]]
 ==== Installation as an init.d service (System V)
-The default executable script that can be embedded into Spring Boot jars will act as an
-`init.d` script when it is symlinked to `/etc/init.d`. The standard `start`, `stop`,
-`restart` and `status` commands can be used. The script supports the following features:
+If you've configured Spring Boot's Maven or Gradle plugin to generate a
+<<deployment-install,fully executable jar>>, and you're not using a custom
+`embeddedLaunchScript`, then your application can be used as an `init.d` service. Simply
+symlink the jar to `init.d` to support the standard `start`, `stop`, `restart` and
+`status` commands.
+
+The script supports the following features:
 
 * Starts the services as the user that owns the jar file
 * Tracks application's PID using `/var/run/<appname>/<appname>.pid`
@@ -431,15 +438,26 @@ Spring Boot application as an `init.d` service simply create a symlink:
 	$ sudo ln -s /var/myapp/myapp.jar /etc/init.d/myapp
 ----
 
-Once installed, you can start and stop the service in the usual way. You can also flag the
-application to start automatically using your standard operating system tools. For example,
-if you use Debian:
+Once installed, you can start and stop the service in the usual way. For example:
+
+[indent=0,subs="verbatim,quotes,attributes"]
+----
+	$ /etc/init.d/myapp start
+----
+
+TIP: If you're application fails to start, check the log file written to
+`/var/log/<appname>.log` for errors.
+
+You can also flag the application to start automatically using your standard operating
+system tools. For example, if you use Debian:
 
 [indent=0,subs="verbatim,quotes,attributes"]
 ----
 	$ update-rc.d myapp defaults <priority>
 ----
 
+
+
 [[deployment-initd-service-securing]]
 ===== Securing an init.d service
 
@@ -548,8 +566,67 @@ Refer to `man systemctl` for more details.
 
 [[deployment-script-customization]]
 ==== Customizing the startup script
-The script accepts the following parameters as environment variables, so you can change
-the default behavior in a script or on the command line:
+The default embedded startup script written by the Maven or Gradle plugin can be
+customized in a number of ways. For most people, using the default script along with
+a few customizations is usually enough. If you find you can't customize something that
+you need to, you can always use the `embeddedLaunchScript` option to write your own
+file entirely.
+
+
+
+[[deployment-script-customization-when-it-written]]
+===== Customizing script when it's written
+It often makes sense to customize elements of the start script as it's written into the
+jar file. For example, init.d scripts can provide a "`description`" and, since you know
+this up front (and it won't change), you may as well provide it when the jar is generated.
+
+To customize written elements, use the `embeddedLaunchScriptProperties` option of the
+Spring Boot Maven or Gradle plugins.
+
+The following property substitutions are supported with the default script:
+
+[cols="1,6"]
+|===
+|Name |Description
+
+|`mode`
+|The script mode. Defaults to `auto`.
+
+|`initInfoProvides`
+|The `Provides` section of "`INIT INFO`". Defaults to `spring-boot-application` for Gradle
+ and to `${project.artifactId}` for Maven.
+
+|`initInfoShortDescription`
+|The `Short-Description` section of "`INIT INFO`". Defaults to `Spring Boot Application`
+for Gradle and to `${project.name}` for Maven.
+
+|`initInfoDescription`
+|The `Description` section of "`INIT INFO`". Defaults to `Spring Boot Application` for
+ Gradle and to `${project.description}` (falling back to `${project.name}`) for Maven.
+
+|`initInfoChkconfig`
+|The `chkconfig` section of "`INIT INFO`". Defaults to `2345 99 01`.
+
+|`logFolder`
+|The default value for `LOG_FOLDER`. Only valid for an `init.d` service.
+
+|`pidFolder`
+|The default value for `PID_FOLDER`. Only valid for an `init.d` service.
+
+|`useStartStopDaemon`
+|If the `start-stop-daemon` command, when it's available, should be used to control the
+ process. Defaults to `true`.
+|===
+
+
+[[deployment-script-customization-when-it-runs]]
+[[deployment-script-customization-conf-file]]
+===== Customizing script when it runs
+For items of the script that need to be customized _after_ the jar has been written you
+can use environment variables or a
+<<deployment-script-customization-conf-file, config file>>.
+
+The following environment properties are supported with the default script:
 
 [cols="1,6"]
 |===
@@ -608,66 +685,26 @@ script. Check the
 http://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit
 configuration man page] for more details.
 
-In addition, the following properties can be changed when the script is written by using
-the `embeddedLaunchScriptProperties` option of the Spring Boot Maven or Gradle plugins.
-
-[cols="1,6"]
-|===
-|Name |Description
-
-|`mode`
-|The script mode. Defaults to `auto`.
-
-|`initInfoProvides`
-|The `Provides` section of "`INIT INFO`". Defaults to `spring-boot-application` for Gradle
- and to `${project.artifactId}` for Maven.
-
-|`initInfoShortDescription`
-|The `Short-Description` section of "`INIT INFO`". Defaults to `Spring Boot Application`
-for Gradle and to `${project.name}` for Maven.
-
-|`initInfoDescription`
-|The `Description` section of "`INIT INFO`". Defaults to `Spring Boot Application` for
- Gradle and to `${project.description}` (falling back to `${project.name}`) for Maven.
-
-|`initInfoChkconfig`
-|The `chkconfig` section of "`INIT INFO`". Defaults to `2345 99 01`.
-
-|`logFolder`
-|The default value for `LOG_FOLDER`. Only valid for an `init.d` service.
-
-|`pidFolder`
-|The default value for `PID_FOLDER`. Only valid for an `init.d` service.
-
-|`useStartStopDaemon`
-|If the `start-stop-daemon` command, when it's available, should be used to control the
- process. Defaults to `true`.
-|===
-
-
-
 [[deployment-script-customization-conf-file]]
-==== Customizing the startup script with a conf file
-
 With the exception of `JARFILE` and `APP_NAME`, the above settings can be configured using
-a `.conf` file,
+a `.conf` file. The file is expected next to the jar file and have the same name but
+suffixed with `.conf` rather than `.jar`. For example, a jar named `/var/myapp/myapp.jar`
+will use the configuration file named `/var/myapp/myapp.conf`.
 
+.myapp.conf
 [indent=0,subs="verbatim,quotes,attributes"]
 ----
 	JAVA_OPTS=-Xmx1024M
 	LOG_FOLDER=/custom/log/folder
 ----
 
-The file is expected next to the jar file and have the same name but suffixed with
-`.conf` rather than `.jar`. For example, a jar named `/var/myapp/myapp.jar` will use the
-configuration file named `/var/myapp/myapp.conf` if it exists. You can also use the
-`CONF_FOLDER` property to customize the location of that file.
+TIP: You can use a `CONF_FOLDER` environment variable to customize the location of the
+config file if you don't like it living next to the jar.
 
 To learn about securing this file appropriately, please refer to
 <<deployment-initd-service-securing,the guidelines for securing an init.d service>>.
 
 
-
 [[deployment-windows]]
 == Microsoft Windows services
 Spring Boot application can be started as Windows service using