fleshed out Machine scp command description, fixed Compose file notes (#2265)

copyedit to fix typo

wrapped text properly

replaced original example with Nathan's

added a better sub-title

specifically mentioned not using relative paths

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

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

@@ -534,7 +534,7 @@ Links also express dependency between services in the same way as
 
 > **Note:** If you define both links and [networks](#networks), services with
 > links between them must share at least one network in common in order to
-> communicate. We recommend using networks instead. See [Version 2 file format](#version-2).
+> communicate. We recommend using networks instead.
 
 ### logging
 

compose/compose-file/index.md

@@ -505,21 +505,23 @@ accessible to linked services. Only the internal port can be specified.
 
 ### external_links
 
-Link to containers started outside this `docker-compose.yml` or even outside
-of Compose, especially for containers that provide shared or common services.
-`external_links` follow semantics similar to `links` when specifying both the
-container name and the link alias (`CONTAINER:ALIAS`).
+Link to containers started outside this `docker-compose.yml` or even outside of
+Compose, especially for containers that provide shared or common services.
+`external_links` follow semantics similar to the legacy option `links` when
+specifying both the container name and the link alias (`CONTAINER:ALIAS`).
 
     external_links:
      - redis_1
      - project_db_1:mysql
      - project_db_1:postgresql
 
-> **Note:** If you're using the [version 2 or above file format](compose-versioning.md#version-2), the
+> **Notes:**
+>
+>* If you're using the [version 2 or above file format](compose-versioning.md#version-2), the
 > externally-created containers must be connected to at least one of the same
-> networks as the service which is linking to them. Starting with Version 2, links are a legacy option. We recommend using networks instead. See [Version 2 file format](compose-versioning.md#version-2).
-
-> **Note:** This option is ignored when
+> 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.
+>
+>* This option is ignored when
 > [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
 > with a (version 3) Compose file.
 
@@ -652,11 +654,13 @@ 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.
 
-> **Note:** If you define both links and [networks](#networks), services with
+> **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
 > communicate.
-
-> **Note:** This option is ignored when
+>
+> *  This option is ignored when
 > [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
 > with a (version 3) Compose file.
 

machine/reference/scp.md

@@ -10,6 +10,8 @@ machine to your local host using `scp`.
 The notation is `machinename:/path/to/files` for the arguments; in the host
 machine's case, you don't have to specify the name, just the path.
 
+## Example
+
 Consider the following example:
 
 ```none
@@ -27,5 +29,43 @@ A file created remotely!
 Just like how `scp` has a `-r` flag for copying files recursively,
 `docker-machine` has a `-r` flag for this feature.
 
-In the case of transferring files from machine to machine, they go through the
-local host's filesystem first (using `scp`'s `-3` flag).
+In the case of transferring files from machine to machine,
+they go through the local host's filesystem first (using `scp`'s `-3` flag).
+
+## Specifying file paths for remote deployments
+
+When you copy files to a remote server with `docker-machine scp` for app
+deployment, make sure `docker-compose` and the Docker daemon know how to find
+them. You can specify absolute paths, e.g. `/home/myuser/workspace` in a
+[Compose file](/compose/compose-file/index.md), which will be mounted into the
+container at `/workspace`, from the absolute path on the remote host where the
+Docker daemon is running. Local client paths (e.g., on your laptop) will not
+work for daemons running on a remote machine, so avoid using relative paths.
+
+For example, imagine you want to transfer your local directory
+`/Users/londoncalling/webapp` to a remote machine and bind mount it into a
+container on the remote host. (We'll suppose the remote user is `ubuntu`.) You
+could do something like this:
+
+```none
+$ docker-machine scp -r /Users/londoncalling/webapp MACHINE-NAME:/home/ubuntu/webapp
+```
+
+Then write a docker-compose file that bind mounts it in:
+
+```none
+version: "3.1"
+services:
+  webapp:
+    image: alpine
+    command: cat /app/root.php
+    volumes:
+    - "/home/ubuntu/webapp:/app"
+```
+
+And we can try it out like so:
+
+```none
+$ eval $(docker-machine env MACHINE-NAME)
+$ docker-compose run webapp
+```