WIP Polishes docs

SUMMARY.md

@@ -5,7 +5,6 @@
 * [Languages](languages.md)
 * [Alternatives](alternatives.md)
 * [Join the Community](join-the-community.md)
-* [Babelfish Improvement Proposals](babelfish-improvement-proposals.md)
 
 ## Using Babelfish
 
@@ -15,7 +14,7 @@
 * [UAST Querying](using-babelfish/uast-querying.md)
 * [Babelfish Protocol](using-babelfish/babelfish-protocol.md)
 * [gRPC usage example](using-babelfish/grpc-usage-example.md)
-* [Babelfish web client](http://play.bblf.sh)
+* [Babelfish playground](http://play.bblf.sh)
 
 ## UAST
 
@@ -42,4 +41,3 @@
 * [BIP3: Agglutinative Roles language](bip-index/bip3-agglutinative-roles-language.md)
 * [BIP4: Schema-less internal representation for AST](bip-index/bip4-schema-less-internal-representation-for-ast.md)
 * [BIP5: Shape-based AST transformations](bip-index/bip5-shape-based-ast-transformations.md)
-

alternatives.md

@@ -114,8 +114,7 @@ Babelfish provides access to the native language AST though [client libraries](h
 From the [project documentation](http://tree-sitter.github.io/tree-sitter/):
 > Tree-sitter is a parser generator tool and an incremental parsing library. It can build a concrete syntax tree for a source file and efficiently update the syntax tree as the source file is edited. This makes it suitable for use in text-editing programs.
 
-Although tree-sitter, being a parser generator, produces a Concrete Syntax Tree, the shape of the tree is designed to closely mirror the structure of the AST and thus can be used directly for code analysis. Other differences include: tree-sitter's syntax nodes currently just contain an ordered list of children, the syntax nodes don't have a name for each child such as a predicate, a body, etc.
-
+Although tree-sitter, being a parser generator, produces a Concrete Syntax Tree, the shape of the tree is designed to closely mirror the structure of the AST and thus can be used directly for code analysis.
 That project also focuses on performance and incremental parsing since both are essential
 for text editors.
 

join-the-community.md

@@ -27,4 +27,4 @@ Bugs should be reported through GitHub Issues. When you find a bug, report it to
 
 If you want to request a new feature, feel free to open it as an issue at the relevant GitHub repository.
 
-For design changes we use the [Babelfish Improvement Proposals](bip-index/babelfish-improvement-proposals.md). If the feature you want to request is quite complex and could benefit from some deeper discussion, consider initiating a BIP procedure, as described in [BIP1](bip-index/bip1-purpose-and-guidelines.md).
+For design changes we currently use [design documents](https://doc.bblf.sh/bip-index/babelfish-improvement-proposals.html#design-documents). Before we used [BIPs](https://doc.bblf.sh/bip-index/babelfish-improvement-proposals.html). If the feature you want to request is quite complex and could benefit from some deeper discussion, consider initiating a design document using [this template](https://docs.google.com/document/d/1UBK9G9Bbe0aGl_OG9aMtV2dsBlVNG5LAKRQB6Fcz0cM/edit#heading=h.qhzm4nnshexd).

using-babelfish/clients.md

@@ -12,7 +12,7 @@ There are clients for the following languages:
 | :--- | :--- | :--- | :--- |
 | Python |  Beta | ✓ | [bblfsh/python-client](https://github.com/bblfsh/python-client) |
 | Go | Beta | ✓ | [bblfsh/go-client](https://github.com/bblfsh/go-client) |
-| Scala |  | [WIP](https://github.com/bblfsh/scala-client/issues/83)  | [bblfsh/client-scala](https://github.com/bblfsh/scala-client) |
+| Scala | Beta | ✓ | [bblfsh/scala-client](https://github.com/bblfsh/scala-client) |
 
 ## Examples
 
@@ -93,12 +93,6 @@ func main() {
 
 ### Python example
 
-As a command:
-
-```bash
-python3 -m bblfsh -q [XPath query] -f [file.ext]
-```
-
 As a library:
 
 ```python
@@ -115,12 +109,6 @@ if __name__ == "__main__":
 
 ### Scala example
 
-As a command:
-
-```bash
-java -jar bblfsh-client-assembly-1.0.1.jar -q [XPath query] -f file.py
-```
-
 As a library:
 
 ```scala
@@ -170,4 +158,3 @@ root = client.parse("/path/to/myfile.py")
 for node in bblfsh.iterator(root, bblfsh.TreeOrder.PRE_ORDER):
     #... do stuff with the node
 ```
-

using-babelfish/getting-started.md

@@ -10,38 +10,50 @@ After playing with the web client, you will probably want to get Babelfish runni
 
 ### Prerequisites
 
-* Linux: [Docker](https://docs.docker.com/install/) \(optional\)
+* Linux: [Docker](https://docs.docker.com/install/)
 * macOS: [Docker for Mac](https://docs.docker.com/docker-for-mac/install/)
 * Windows: [Docker for Windows](https://docs.docker.com/docker-for-windows/install/)
 
 ### Running with Docker \(recommended\)
 
-The easiest way to run the _bblfshd_ daemon is using Docker. You can run it in one of those modes:
-- _Embedded drivers mode_, meaning that recommended drivers will be included in the Docker image. Installing more drivers is similar to stateless mode.
-- _Stateless mode_, meaning that all installed drivers will be wiped out once you remove the container.
-- _Stateful mode_, using a Docker volume to store part of the container internal filesystem and thus add persistence.
+The easiest way to run the _bblfshd_ daemon is using Docker. With respect to privileges of `bblfshd` daemon, there are two ways of executing it:
+- As `rootless` container. You will need to get the file [`bblfshd-seccomp.json`](https://raw.githubusercontent.com/bblfsh/bblfshd/master/bblfshd-seccomp.json). Further requirements to run in rootless mode are available at [bblfshd#rootless.md](https://github.com/bblfsh/bblfshd/blob/master/rootless.md). Examples below use this mode.
+- In privileged mode (we advise against it). Check out instructions [here](https://github.com/bblfsh/bblfshd/blob/master/README.md#privileged-mode).
+
+With respect to storage, you can run it in one of these modes:
+- _Embedded drivers mode_, meaning that recommended drivers will be included in the Docker image. Installing more drivers is similar to stateless mode. The Docker image will weight more of course, and there may be language drivers included in it you will not use.
+- _Stateless mode_, meaning `bblfshd` is fethed without any driver included, and the drivers you install in it will be wiped out once you remove the container.
+- _Stateful mode_, using a Docker volume to store part of the container internal filesystem and thus add persistence. `bblfhsd` is fetched without drivers, as in _stateless mode_, but all drivers you install will persist in the volume you use, and could be plugged in another `bblfshd` instance or even the same if you stop `bblfshd` and start it again.
 
 #### Embedded drivers
 
 For embedded drivers mode, run the following command:
 
 ```bash
-$ docker run -d --name bblfshd --privileged -p 9432:9432 bblfsh/bblfshd:latest-drivers
+$ docker run -d --name bblfshd \
+  -p 9432:9432 \
+  -v /proc:/newproc \
+  --security-opt seccomp=./bblfshd-seccomp.json \
+  bblfsh/bblfshd:latest-drivers
 ```
 
 #### Stateless mode
 
 For stateless mode, run the following command:
 
 ```bash
-$ docker run -d --name bblfshd --privileged -p 9432:9432 bblfsh/bblfshd:latest
+$ docker run -d --name bblfshd \
+  -p 9432:9432 \
+  -v /proc:/newproc \
+  --security-opt seccomp=./bblfshd-seccomp.json \
+  bblfsh/bblfshd:latest
 ```
 
-#### Using a volume
+#### Stateful mode
 
 This is an alternative to stateless mode. Depending on your operating system, you can use a Docker volume or a normal local filesystem directory.
 
-**Docker volume \(Linux and macOS\)**
+##### Docker volume \(Linux and macOS\)
 
 First, create a volume with the command:
 
@@ -52,28 +64,45 @@ $ docker volume create bblfshd-cache
 Then you can run the daemon with this command:
 
 ```bash
-$ docker run -d --name bblfshd --privileged -p 9432:9432 -v bblfshd-cache:/var/lib/bblfshd bblfsh/bblfshd:latest
+$ docker run -d --name bblfshd \
+  -p 9432:9432 \
+  -v /proc:/newproc \
+  -v bblfshd-cache:/var/lib/bblfshd \
+  --security-opt seccomp=./bblfshd-seccomp.json \
+  bblfsh/bblfshd:latest
 ```
 
-#### Volume mapped to a local directory \(Linux only\)
+##### Volume mapped to a local directory \(Linux only\)
 
 In this case, just specify the local directory in the `-v` parameter when running the daemon:
 
 ```bash
-$ docker run -d --name bblfshd --privileged -p 9432:9432 -v /var/lib/bblfshd:/var/lib/bblfshd bblfsh/bblfshd:latest
+$ docker run -d --name bblfshd \
+  -p 9432:9432 \
+  -v /proc:/newproc \
+  -v /var/lib/bblfshd:/var/lib/bblfshd bblfsh/bblfshd:latest \
+  --security-opt seccomp=./bblfshd-seccomp.json \
+  bblfsh/bblfshd:latest
 ```
 
 ### Notes on command line parameters to "docker run"
 
-The only mandatory flag is [`--privileged`](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). _bblfshd_ uses containers itself to run language drivers, which currently requires it to run in privileged mode.
-
-Exposing the port \(`9432`\) with `-p 9432:9432` makes it easier to connect to the gRPC server from outside the container.
+- The flag `-d` makes the container run as a daemon. You can omit it and you will see the log outputs.
+- `--name bblfshd` gives a name to the container as `bblfshd`.
+- Exposing the port \(`9432`\) with `-p 9432:9432` makes it easier to connect to the gRPC server from outside the container.
+- `-v /proc:/newproc` is mandatory to run in rootless mode, due to a [bug in `libcontainer`](https://github.com/opencontainers/runc/issues/1658), the container technology used in bblfshd.
+- `--security-opt seccomp=./bblfshd-seccomp.json` allows the default syscalls Docker permits plus `mount`, `unshare`, `pivot_root`, `keyctl`, `umount2` and `sethostname`, needed to spawn containers inside `bblfshd`. More on that matter can be consulted in [Docker docs](https://docs.docker.com/engine/security/seccomp/).
 
 If you are behind an HTTP or HTTPS proxy server, for example in corporate settings, you will need to add the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables in the docker run command to configure HTTP or HTTPS proxy behavior.
 
 ```bash
-$ docker run -d --name bblfshd --privileged -p 9432:9432 -e
-HTTP_PROXY="http://proxy.example.com:80/" -v bblfshd-cache:/var/lib/bblfshd bblfsh/bblfshd
+$ docker run -d --name bblfshd \
+  -p 9432:9432 \
+  -v /proc:/newproc \
+  -v bblfshd-cache:/var/lib/bblfshd \
+  --security-opt seccomp=./bblfshd-seccomp.json \
+  -e HTTP_PROXY="http://proxy.example.com:80/" \
+  bblfsh/bblfshd:latest
 ```
 
 If your system uses SELinux \(like Fedora, Red Hat or CentOS among other Linux distributions\) you'll need to install a policy module. You can find instructions about it in the [bblfshd README](https://github.com/bblfsh/bblfshd#selinux).
@@ -89,7 +118,7 @@ If everything worked, `docker logs bblfshd` should output something like this:
 [2019-05-01T17:58:29Z]  INFO control server listening in /var/run/bblfshctl.sock (unix)
 ```
 
-#### Installing the drivers
+#### Driver management
 
 Now we need to install the driver images into the daemon. You can install the official images with the following command:
 
@@ -118,7 +147,19 @@ $ docker exec -it bblfshd bblfshctl driver list
 +------------+------------------------------------------+---------+--------+----------+--------+-------------+----------------------+
 ```
 
-#### Testing the drivers
+You can remove a driver (e.g. `python` one) with:
+
+```bash
+$ docker exec -it bblfshd bblfshctl driver remove python
+```
+
+or all drivers with:
+
+```bash
+$ docker exec -it bblfshd bblfshctl driver remove --all
+```
+
+##### Testing the drivers
 
 To test the driver you can execute a parse request to the server with the `bblfshctl parse` command, and an example contained in the Docker image:
 
@@ -158,6 +199,12 @@ Available commands:
   status     List all the pools of driver instances running
 ```
 
+Note that the `--help` command works at any sublevel:
+
+```bash
+docker exec -it bblfshd bblfshctl driver --help
+```
+
 ### Driver management
 
 The _bblfshd's_ drivers can be installed, updated and removed with the `driver` command and its subcommands. Remember to prefix all these commands with `docker exec -it bblfshd` if you are running bblfshd from a Docker image.
@@ -188,4 +235,3 @@ $ bblfshctl driver list
 | java       | docker://bblfsh/java-driver:latest       | v2.2.0  | beta   | 8 months | alpine | 1.10-alpine | openjdk:8-jre-alpine |
 +------------+------------------------------------------+---------+--------+----------+--------+-------------+----------------------+
 ```
-

using-babelfish/uast-querying.md

@@ -39,8 +39,7 @@ The query language also allows some more complex queries:
 * All the simple identifiers: `//*[@role='Identifier' and not(@role='Qualified')]` or, if you're getting the semantic UAST (which is the default): `//Identifier[not(@role='Qualified')]`.
 * All the simple identifiers that don't have any positioning: `//*[@role='Identifier' and not(@role='Qualified') and not(@startOffset) and not(@endOffset)]`
 * All the arguments in function calls: `//*[@role='Call' and @role='Argument']`
-* The parent node of a call argument: `//*@[role='Call' and @role='Argument']/parent::*` (you can also specify the type of the parent node instead of an `*` or use `ancestor::type` to get the first ancestor of a specified type).
+* The parent node of a call argument: `//*[@role='Call' and @role='Argument']/parent::*` (you can also specify the type of the parent node instead of an `*` or use `ancestor::type` to get the first ancestor of a specified type).
 * All the numeric literals in binary arithmetic operators: `//*[@role='Binary' and @role='Operator' and @role='Arithmetic']//*[@role='Number' and @role='Literal']`
 
 [XPath 1.0 functions](https://developer.mozilla.org/en-US/docs/Web/XPath/Functions) can also be used in the queries, but if the query returns a type different than the default node list you must use one of the specific typed functions: `filter_bool` \(or `filterBool` in some clients\), `filter_number` or `filter_string`. If you use the wrong type the error will tell you what is the type returned by the expression.
-