Make location of bin/logstash more obvious and fix TOC org

Fixes #6784

docs/index.asciidoc

@@ -59,13 +59,16 @@ include::static/life-of-an-event.asciidoc[]
 include::static/setting-up-logstash.asciidoc[]
 
 
-include::static/docker.asciidoc[]
-
-
 include::static/settings-file.asciidoc[]
 
 
-include::static/command-line-flags.asciidoc[]
+include::static/running-logstash-command-line.asciidoc[]
+
+
+include::static/running-logstash.asciidoc[]
+
+
+include::static/docker.asciidoc[]
 
 
 include::static/logging.asciidoc[]

docs/static/getting-started-with-logstash.asciidoc

@@ -163,7 +163,8 @@ the data to a destination.
 
 image::static/images/basic_logstash_pipeline.png[]
 
-To test your Logstash installation, run the most basic Logstash pipeline:
+To test your Logstash installation, run the most basic Logstash pipeline. For
+example:
 
 ["source","sh",subs="attributes"]
 --------------------------------------------------
@@ -171,6 +172,9 @@ cd logstash-{logstash_version}
 bin/logstash -e 'input { stdin { } } output { stdout {} }'
 --------------------------------------------------
 
+NOTE: The location of the `bin` directory varies by platform. See <<dir-layout>>
+to find the location of `bin\logstash` on your system.
+
 The `-e` flag enables you to specify a configuration directly from the command line. Specifying configurations at the
 command line lets you quickly test configurations without having to edit a file between iterations.
 The pipeline in the example takes input from the standard input, `stdin`, and moves that input to the standard output,

docs/static/running-logstash-command-line.asciidoc

@@ -1,16 +1,41 @@
+[[running-logstash-command-line]]
+=== Running Logstash from the Command Line
+
+To run Logstash from the command line, use the following command:
+
+[source,shell]
+----
+bin/logstash [options]
+----
+
+Where `options` are <<command-line-flags,command-line>> flags that you can
+specify to control Logstash execution. The location of the `bin` directory
+varies by platform. See <<dir-layout>> to find the location of `bin\logstash` on
+your system.
+
+The following example runs Logstash and loads the Logstash config defined in
+the `mypipeline.conf` file:
+
+[source,shell]
+----
+bin/logstash -f mypipeline.conf
+----
+
+Specifying command line options is useful when you are testing Logstash.
+However, in a production environment, we recommend that you use the Logstash
+<<logstash-settings-file,settings file>> to control Logstash execution. Using
+the settings file makes it easier for you to specify multiple options, and it
+provides you with a single, versionable file that you can use to start up
+Logstash consistently for each run.
+
+Any flags that you set at the command line override the corresponding settings
+in the Logstash <<logstash-settings-file,settings file>>.
+
 [[command-line-flags]]
-=== Command-Line Flags
+==== Command-Line Flags
 
 Logstash has the following flags. You can use the `--help` flag to display this information.
 
-Instead of specifying options at the command line, we recommend that you control Logstash execution
-by specifying options in the Logstash <<logstash-settings-file,settings file>>. Using a settings file
-makes it easier for you to specify mutliple options, and it provides you with a single, versionable
-file that you can use to start up Logstash consistently for each run.
-
-Any flags that you set at the command line override the corresponding settings in the Logstash
-<<logstash-settings-file,settings file>>.
-
 *`--node.name NAME`*::
   Specify the name of this Logstash instance. If no value is given it will default to the current
   hostname.

docs/static/running-logstash.asciidoc

@@ -0,0 +1,53 @@
+[[running-logstash]]
+=== Running Logstash as a Service on Debian or RPM
+
+Logstash is not started automatically after installation. How to start and stop Logstash depends on whether your system
+uses systemd, upstart, or SysV.
+
+Here are some common operating systems and versions, and the corresponding
+startup styles they use.  This list is intended to be informative, not exhaustive.
+
+|=======================================================================
+| Distribution | Service System |
+| Ubuntu 16.04 and newer | <<running-logstash-systemd,systemd>> |
+| Ubuntu 12.04 through 15.10 | <<running-logstash-upstart,upstart>> |
+| Debian 8 "jessie" and newer | <<running-logstash-systemd,systemd>> |
+| Debian 7 "wheezy" and older | <<running-logstash-sysv,sysv>> |
+| CentOS (and RHEL) 7 and newer | <<running-logstash-systemd,systemd>> |
+| CentOS (and RHEL) 6 | <<running-logstash-upstart,upstart>> |
+|=======================================================================
+
+[[running-logstash-systemd]]
+==== Running Logstash by Using Systemd
+
+Distributions like Debian Jessie, Ubuntu 15.10+, and many of the SUSE derivatives use systemd and the
+`systemctl` command to start and stop services. Logstash places the systemd unit files in `/etc/systemd/system` for both deb and rpm. After installing the package, you can start up Logstash with:
+
+[source,sh]
+--------------------------------------------
+sudo systemctl start logstash.service
+-------------------------------------------
+
+[[running-logstash-upstart]]
+==== Running Logstash by Using Upstart
+
+For systems that use upstart, you can start Logstash with:
+
+[source,sh]
+--------------------------------------------
+sudo initctl start logstash
+-------------------------------------------
+
+The auto-generated configuration file for upstart systems is `/etc/init/logstash.conf`.
+
+[[running-logstash-sysv]]
+==== Running Logstash by Using SysV
+
+For systems that use SysV, you can start Logstash with:
+
+[source,sh]
+--------------------------------------------
+sudo /etc/init.d/logstash start
+-------------------------------------------
+
+The auto-generated configuration file for SysV systems is `/etc/init.d/logstash`.

docs/static/setting-up-logstash.asciidoc

@@ -7,10 +7,10 @@ This section includes additional information on how to set up and run Logstash,
 
 * <<dir-layout>>
 * <<config-setting-files>>
+* <<logstash-settings-file>>
+* <<running-logstash-command-line>>
 * <<running-logstash>>
 * <<docker>>
-* <<logstash-settings-file>>
-* <<command-line-flags>>
 * <<logging>>
 * <<persistent-queues>>
 * <<shutdown>>
@@ -177,59 +177,3 @@ The settings files are already defined in the Logstash installation. Logstash in
   the file and change the values for specific settings. Note that the `startup.options` file is not read at startup. If
   you want to change the Logstash startup script (for example, to change the Logstash user or read from a different
   configuration path), you must re-run the `system-install` script (as root) to pass in the new settings.
-
-[[running-logstash]]
-=== Running Logstash as a Service on Debian or RPM
-
-Logstash is not started automatically after installation. How to start and stop Logstash depends on whether your system
-uses systemd, upstart, or SysV.
-
-Here are some common operating systems and versions, and the corresponding
-startup styles they use.  This list is intended to be informative, not exhaustive.
-
-|=======================================================================
-| Distribution | Service System |
-| Ubuntu 16.04 and newer | <<running-logstash-systemd,systemd>> |
-| Ubuntu 12.04 through 15.10 | <<running-logstash-upstart,upstart>> |
-| Debian 8 "jessie" and newer | <<running-logstash-systemd,systemd>> |
-| Debian 7 "wheezy" and older | <<running-logstash-sysv,sysv>> |
-| CentOS (and RHEL) 7 and newer | <<running-logstash-systemd,systemd>> |
-| CentOS (and RHEL) 6 | <<running-logstash-upstart,upstart>> |
-|=======================================================================
-
-For info about shutting down Logstash safely, see <<shutdown>>.
-
-[[running-logstash-systemd]]
-==== Running Logstash by Using Systemd
-
-Distributions like Debian Jessie, Ubuntu 15.10+, and many of the SUSE derivatives use systemd and the
-`systemctl` command to start and stop services. Logstash places the systemd unit files in `/etc/systemd/system` for both deb and rpm. After installing the package, you can start up Logstash with:
-
-[source,sh]
---------------------------------------------
-sudo systemctl start logstash.service
--------------------------------------------
-
-[[running-logstash-upstart]]
-==== Running Logstash by Using Upstart
-
-For systems that use upstart, you can start Logstash with:
-
-[source,sh]
---------------------------------------------
-sudo initctl start logstash
--------------------------------------------
-
-The auto-generated configuration file for upstart systems is `/etc/init/logstash.conf`.
-
-[[running-logstash-sysv]]
-==== Running Logstash by Using SysV
-
-For systems that use SysV, you can start Logstash with:
-
-[source,sh]
---------------------------------------------
-sudo /etc/init.d/logstash start
--------------------------------------------
-
-The auto-generated configuration file for SysV systems is `/etc/init.d/logstash`.

docs/static/settings-file.asciidoc

@@ -7,9 +7,9 @@ Most of the settings in the `logstash.yml` file are also available as <<command-
 when you run Logstash. Any flags that you set at the command line override the corresponding settings in the
 `logstash.yml` file.
 
-The `logstash.yml` file, which is written in http://yaml.org/[YAML], is located in `LOGSTASH_HOME/config`. You can
+The `logstash.yml` file is written in http://yaml.org/[YAML]. Its location varies by platform (see
-specify settings in hierarchical form or use flat keys. For example, to use hierarchical form to set the pipeline batch
+<<dir-layout>>). You can specify settings in hierarchical form or use flat keys. For example, to use
-size and batch delay, you specify:
+hierarchical form to set the pipeline batch size and batch delay, you specify:
 
 [source,yaml]
 -------------------------------------------------------------------------------------