clarified logging options in Compose, fixed glaring note formats (#3272)

* clarified logging options in Compose, fixed glaring note formats

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* added link directly to JSON driver in supported drivers docs

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* took off code tags to make link stand out

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* fixed alignment of note text in markdown

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* x-ref to how to set environment variables in containers

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* copyedit in note

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

compose/compose-file/compose-file-v1.md

@@ -43,12 +43,16 @@ context.
 
     build: ./dir
 
-> **Note**: In the [version 1 file format](compose-versioning.md#version-1), `build` is different in
+> **Notes**
-> two ways:
 >
-> 1.   Only the string form (`build: .`) is allowed - not the object form that is allowed in Version 2 and up.
+> In [version 1 file format](compose-versioning.md#version-1),
-> 2.   Using `build` together with [`image`](#image) is not allowed. Attempting to do so
+`build` is  different in two ways:
->     results in an error.
+>
+>*  Only the string form (`build: .`) is allowed - not the object
+>   form that is allowed in Version 2 and up.
+> * Using `build` together with [`image`](#image) is not allowed.
+Attempting to do so results in an error.
+{: .note-vanilla}
 
 #### dockerfile
 
@@ -60,12 +64,13 @@ specified.
       build: .
       dockerfile: Dockerfile-alternate
 
-> **Note**: In the [version 1 file format](compose-versioning.md#version-1), `dockerfile` is
+> **Note**
-> different from newer versions in two ways:
 >
->  1.  It appears alongside `build`, not as a sub-option:
+> In the [version 1 file format](compose-versioning.md#version-1), `dockerfile` is different from newer versions in two ways:
 >
->  2.  Using `dockerfile` together with [`image`](#image) is not allowed. Attempting to do so results in an error.
+>* It appears alongside `build`, not as a sub-option:
+>
+>*  Using `dockerfile` together with [`image`](#image) is not allowed. Attempting to do so results in an error.
 
 ### cap_add, cap_drop
 

compose/compose-file/compose-file-v2.md

@@ -894,14 +894,19 @@ then read-write will be used.
      - container:container_name
      - container:container_name:rw
 
-> **Note**: The `container:...` formats are only supported in the
+> **Notes**
-> [version 2 file format](compose-versioning.md#version-2). In [version 1](compose-versioning.md#version-1), you can use
+>
+>* The `container:...` formats are only supported in the
+> [version 2 file format](compose-versioning.md#version-2).
+>
+>* In [version 1](compose-versioning.md#version-1), you can use
 > container names without marking them as such:
 >
->     - service_name
+>     - `service_name`
->     - service_name:ro
+>     - `service_name:ro`
->     - container_name
+>     - `container_name`
->     - container_name:rw
+>     - `container_name:rw`
+{: .note-vanilla}
 
 ### restart
 

compose/compose-file/index.md

@@ -49,7 +49,8 @@ The Compose file is a [YAML](http://yaml.org/) file defining
 [volumes](#volume-configuration-reference).
 The default path for a Compose file is `./docker-compose.yml`.
 
->**Tip**: You can use either a `.yml` or `.yaml` extension for this file. They both work.
+>**Tip**: You can use either a `.yml` or `.yaml` extension for this file.
+They both work.
 
 A service definition contains configuration which will be applied to each
 container started for that service, much like passing command-line parameters to
@@ -456,7 +457,7 @@ Simple example:
       db:
         image: postgres
 
-> **Note**: There are several things to be aware of when using `depends_on`:
+> There are several things to be aware of when using `depends_on`:
 >
 > - `depends_on` will not wait for `db` and `redis` to be "ready" before
 >   starting `web` - only until they have been started. If you need to wait
@@ -468,6 +469,7 @@ Simple example:
 > - The `depends_on` option is ignored when
 >   [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
 >   with a version 3 Compose file.
+{: .note-vanilla}
 
 
 ### dns
@@ -611,13 +613,14 @@ specifying both the container name and the link alias (`CONTAINER:ALIAS`).
 
 > **Notes:**
 >
->* If you're using the [version 2 or above file format](compose-versioning.md#version-2), the
+> If you're using the [version 2 or above file format](compose-versioning.md#version-2), the externally-created  containers
-> externally-created containers must be connected to at least one of the same
+must be connected to at least one of the same networks as the service which is
-> networks as the service which is linking to them. Starting with Version 2, [links](compose-file-v2#links) are a legacy option. We recommend using [networks](#networks) instead.
+linking to them. Starting with Version 2, [links](compose-file-v2#links) are a
+legacy option. We recommend using [networks](#networks) instead.
 >
->* This option is ignored when
+> This option is ignored when [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
-> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
+with a (version 3) Compose file.
-> with a (version 3) Compose file.
+{: .note-vanilla}
 
 ### extra_hosts
 
@@ -723,7 +726,7 @@ the alias, or the service name if no alias was specified.
 Links also express dependency between services in the same way as
 [depends_on](#dependson), so they determine the order of service startup.
 
-> **Notes:**
+> **Notes**
 >
 > * If you define both links and [networks](#networks), services with
 > links between them must share at least one network in common in order to
@@ -732,6 +735,7 @@ Links also express dependency between services in the same way as
 > *  This option is ignored when
 > [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
 > with a (version 3) Compose file.
+{: .note-vanilla}
 
 ### logging
 
@@ -752,9 +756,9 @@ The default value is json-file.
     driver: "syslog"
     driver: "none"
 
-> **Note**: Only the `json-file` and `journald` drivers make the logs available directly from
+> **Note**: Only the `json-file` and `journald` drivers make the logs
-> `docker-compose up` and `docker-compose logs`. Using any other driver will not
+available directly from `docker-compose up` and `docker-compose logs`.
-> print any logs.
+Using any other driver will not print any logs.
 
 Specify logging options for the logging driver with the ``options`` key, as with the ``--log-opt`` option for `docker run`.
 
@@ -764,17 +768,18 @@ Logging options are key-value pairs. An example of `syslog` options:
     options:
       syslog-address: "tcp://192.168.0.42:123"
 
-To limit the amount of logs stored there are two options key-value pairs:
+The default driver [json-file](/engine/admin/logging/overview.md#json-file), has options to limit the amount of logs stored. To do this, use a key-value pair for maximum storage size and maximum number of files:
 
     options:
       max-size: "200k"
       max-file: "10"
 
-This example would store log files until the reach a `max-size` of 200kB, and then rotate them.
+The example shown above would store log files until they reach a `max-size` of
-The amount of individual log files stored is specified by the `max-file` value. As logs grow
+200kB, and then rotate them. The amount of individual log files stored is
-beyond the max limits, older log files are removed to allow storage of new logs.
+specified by the `max-file` value. As logs grow beyond the max limits, older log
+files are removed to allow storage of new logs.
 
-An example `docker-compose.yml` file that limits logging storage
+Here is an example `docker-compose.yml` file that limits logging storage:
 
     services:
       some-service:
@@ -785,6 +790,15 @@ An example `docker-compose.yml` file that limits logging storage
             max-size: "200k"
             max-file: "10"
 
+> Logging options available depend on which logging driver you use
+>
+> The above example for controlling log files and sizes uses options
+specific to the [json-file driver](/engine/admin/logging/overview.md#json-file).
+These particular options are not available on other logging drivers.
+For a full list of supported logging drivers and their options, see
+[logging drivers](/engine/admin/logging/overview.md).
+{: .note-vanilla}
+
 ### network_mode
 
 Network mode. Use the same values as the docker client `--net` parameter, plus
@@ -796,11 +810,15 @@ the special form `service:[service name]`.
     network_mode: "service:[service name]"
     network_mode: "container:[container name/id]"
 
-> **Note**: This option is ignored when
+> **Notes**
-> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
+>
-> with a (version 3) Compose file.
+>* This option is ignored when
-
+[deploying a stack in swarm
-> **Note**: `network_mode: "host"` cannot be mixed with [links](#links).
+ mode](/engine/reference/commandline/stack_deploy.md) with a (version 3) Compose
+ file.
+>
+>* `network_mode: "host"` cannot be mixed with [links](#links).
+{: .note-vanilla}
 
 ### networks
 
@@ -988,13 +1006,14 @@ container access to the secret and mounts it at `/run/secrets/<secret_name>`
 within the container. The source name and destination mountpoint are both set
 to the secret name.
 
-> **Warning**:
+> Limitations of short syntax in Docker 1.13.1
+>
 > Due to a bug in Docker 1.13.1, using the short syntax currently
 > mounts the secret with permissions `000`, which means secrets defined using
 > the short syntax are unreadable within the container if the command does not
 > run as the `root` user. The workaround is to use the long syntax instead if
 > you use Docker 1.13.1 and the secret must be read by a non-`root` user.
-{:.warning}
+{: .warning-vanilla}
 
 The following example uses the short syntax to grant the `redis` service
 access to the `my_secret` and `my_other_secret` secrets. The value of

compose/env-file.md

@@ -35,9 +35,19 @@ variables](reference/envvars.md):
 - `DOCKER_HOST`
 - `DOCKER_TLS_VERIFY`
 
-> **Note**: Values present in the environment at runtime will always override
+> **Notes**
-> those defined inside the `.env` file. Similarly, values passed via
+>
-> command-line arguments take precedence as well.
+> * Values present in the environment at runtime will always override
+those defined inside the `.env` file. Similarly, values passed via command-line
+arguments take precedence as well.
+>
+> * Environment variables defined in the `.env` file are not
+automatically visible inside containers. To set container-applicable
+environment variables, follow the guidelines in the topic [Environment variables
+in Compose](/compose/environment-variables.md), which describes how to pass
+shell environment variables through to containers, define environment variables
+in Compose files, and more.
+{: .note-vanilla}
 
 ## More Compose documentation
 

test.md

@@ -368,7 +368,7 @@ Current styles for admonitions in
 support two broad categories of admonitions: those with prefixed text (**Note:**,
 **Important:**, **Warning**) and those with prefixed icons.
 
-The new styles (with icons) are defined in a way that will not impact admonitions 
+The new styles (with icons) are defined in a way that will not impact admonitions
 formatted with the original styles (prefixed text), so notes in your
 published documents won't be adversely affected.
 
@@ -444,6 +444,17 @@ Admonitions with prefixed text use the following class tags, as shown in the exa
  super complex.
 {: .warning-vanilla}
 
+### Examples with both prefixed word and icon
+
+The current CSS also supports this kind of of admonition.
+
+> **Notes**
+>
+> * This is a note about a thing.
+>
+> *  This is another note about the same thing.
+{: .note-vanilla}
+
 ## Code blocks
 
 Rouge provides lots of different code block "hints". If you leave off the hint,