Overhaul README (#231)

- Switch to asciidoc, since it supports an auto-generated table of contents
- Re-organize into sections
- Document private recipes
- Document windows dependencies
- Document doc comments

.gitignore

@@ -1,2 +1,3 @@
 /target
 /.vagrant
+/README.html

README.asc

@@ -1,11 +1,11 @@
-just
+= `just`
-====
+:toc:
+:toc-title:
 
-
+image:https://img.shields.io/crates/v/just.svg[crates.io version,link=https://crates.io/crates/just]
-[![crates.io version](https://img.shields.io/crates/v/just.svg)](https://crates.io/crates/just)
+image:https://travis-ci.org/casey/just.svg?branch=master[build status,link=https://travis-ci.org/casey/just]
-[![Build Status](https://travis-ci.org/casey/just.svg?branch=master)](https://travis-ci.org/casey/just)
+image:https://badges.gitter.im/just-because/Lobby.svg[chat on gitter,link= https://gitter.im/just-because/Lobby]
-[![Chat](https://badges.gitter.im/just-because/Lobby.svg)](https://gitter.im/just-because/Lobby)
+image:https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg[say thanks,link=https://saythanks.io/to/casey]
-[![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/casey)
 
 `just` is a handy way to save and run commands.
 
@@ -24,38 +24,36 @@ test TEST: build
     ./test --test {{TEST}}
 ```
 
-`just` produces detailed error messages and avoids `make`'s idiosyncrasies, so debugging a justfile is easier and less surprising than debugging a makefile.
+`just` produces detailed error messages and avoids `make`’s idiosyncrasies, so debugging a justfile is easier and less surprising than debugging a makefile.
 
 If you need help with `just` please feel free to open an issue. Feature requests and bug reports are also always welcome!
 
-
+== Installation
-installation
-------------
 
 `just` should run on any system with a reasonable `sh`. 
 
-### prebuilts
+On Windows, the `sh` provided by https://git-scm.com[git] and https://desktop.github.com[GitHub Desktop] should both work.
 
-Prebuilt binaries for Linux and macOS can be found on [the releases page](https://github.com/casey/just/releases).
+=== Pre-built Binaries
 
-### cargo
+Pre-built binaries for Linux, macOS, and Windows can be found on https://github.com/casey/just/releases[the releases page].
 
-Alternately, `just` can be installed with `cargo`, the [rust language](https://www.rust-lang.org) package manager:
+=== Cargo
 
-1. Install rust and cargo by following the instructions at [rustup.rs](https://www.rustup.rs)
+`just` can also be installed with `cargo`, the https://www.rust-lang.org[rust language package manager]:
+
+1. Install rust and cargo by following the instructions https://www.rustup.rs[here]
 2. Run `cargo install just`
-3. Add `~/.cargo/bin` to your PATH
+3. Add `~/.cargo/bin` to your shell's $PATH.
 
-### alias
+`rustup` may have done #3 for you. If this doesn't work, put `export PATH="$HOME/.cargo/bin:$PATH"` in your shell's configuration file
 
-You can put `alias j=just` in your shell's config file for lightning fast command running.
+== Quick Start
 
-How do I just?
---------------
 
-Once `just` is working, create a file called `justfile` in the root of your project and start adding recipes to it.
+See xref:Installation[] for how to install `just` on your computer. Try running `just --version` to make sure that it's installed correctly.
 
-Recipes look like this:
+Once `just` is installed and working, create a file named `justfile` in the root of your project with the following contents:
 
 ```make
 recipe-name:
@@ -63,9 +61,11 @@ recipe-name:
 
 # this is a comment
 another-recipe:
-    @echo 'Another recipe.'
+    @echo 'This is another recipe.'
 ```
 
+When you invoke `just` it looks for a `justfile` in the current directory and upwards, so you can invoke it from any subdirectory of your project.
+
 Running `just` with no arguments runs the first recipe in the `justfile`:
 
 ```sh
@@ -74,34 +74,14 @@ echo 'This is a recipe!'
 This is a recipe!
 ```
 
-When you invoke `just` it looks for a `justfile` in the current directory and upwards, so you can invoke `just` from any subdirectory of your project.
+One or more arguments specify the recipe(s) to run:
-
-One or more arguments specify the recipes to run:
 
 ```sh
 $ just another-recipe
 Another recipe.
 ```
 
-`just` prints each command to standard error before running it, which is why `echo 'This is a recipe!'` was printed. Lines starting with `@` will not be printed which is why `echo 'Another recipe.'` was not printed.
+`just` prints each command to standard error before running it, which is why `echo 'This is a recipe!'` was printed. This is suppressed for lines starting with `@`, which is why `echo 'Another recipe.'` was not printed.
-
-A recipe name may be prefixed with '@' to invert the meaning of '@' before each line:
-
-```make
-@quiet:
-  echo hello
-  echo goodbye
-  @# all done!
-```
-
-Now only the lines starting with '@' will be echoed:
-
-```sh
-$ j quiet
-hello
-goodbye
-# all done!
-```
 
 Recipes stop running if a command fails. Here `cargo publish` will only run if `cargo test` succeeds:
 
@@ -149,23 +129,52 @@ cc main.c foo.c bar.c -o main
 testing... all tests passed!
 ```
 
-If the first argument passed to `just` contains a `/`, then the following occurs:
+== Features
 
-1. The argument is split at the last `/`.
+=== Listing Available Recipes
-2. The part before the last `/` is treated as a directory. Just will start its search for the justfile there, instead of in the current directory.
-3. The part after the last slash is treated as a normal argument, or ignored if it is empty.
 
-This may seem a little strange, but it's useful if you wish to run a command in a justfile that is in a subdirectory.
+Recipes can be listed with `just --list` :
-
-For example, if you are in a directory which contains a subdirectory named `foo`, which contains justfile with the recipe `build`, which is also the default recipe, the following are all equivalent:
 
 ```sh
-$ (cd foo && just build)
+$ just --list
-$ just foo/build
+Available recipes:
-$ just foo/
+  build
+  test
+  deploy
+  lint
 ```
 
-Assignment, strings, concatenation, and substitution with `{{...}}` are supported:
+`just --summary` is more concise:
+
+```sh
+$ just --summary
+build test deploy lint
+```
+
+=== Documentation Comments
+
+Comments immediately preceding a recipe will appear in `just --list`:
+
+```make
+# build stuff
+build:
+  ./bin/build
+
+# test stuff
+test:
+  ./bin/test
+```
+
+```sh
+$ just --list
+Available recipes:
+    build # build stuff
+    test # test stuff
+```
+
+=== Variables and Substitution
+
+Variables, strings, concatenation, and substitution using `{{...}}` are supported:
 
 ```make
 version = "0.2.7"
@@ -181,27 +190,7 @@ publish:
     rm -rf {{tarball}} {{tardir}}
 ```
 
-`{{...}}` substitutions may need to be quoted if they contains spaces. For example, if you have the following recipe:
+=== Strings
-
-```make
-search QUERY:
-    lynx https://www.google.com/?q={{QUERY}}
-```
-
-And you type:
-
-```sh
-$ just search "cat toupee"
-```
-
-Just will run the command `lynx https://www.google.com/?q=cat toupee`, which will get parsed by `sh` as `lynx`, `https://www.google.com/?q=cat`, and `toupee`, and not the intended `lynx` and `https://www.google.com/?q=cat toupee`.
-
-You can fix this by adding quotes:
-
-```make
-search QUERY:
-    lynx 'https://www.google.com/?q={{QUERY}}'
-```
 
 Double-quoted strings support escape sequences:
 
@@ -250,6 +239,67 @@ string!
 "
 ```
 
+=== Command Evaluation using Backticks
+
+Backticks can be used to store the result of commands:
+
+```make
+localhost = `dumpinterfaces | cut -d: -f2 | sed 's/\/.*//' | sed 's/ //g'`
+
+serve:
+    ./serve {{localhost}} 8080
+```
+
+=== Setting Variables from the Command Line
+
+Variables can be overridden from the command line.
+
+```make
+os = "linux"
+
+test: build
+    ./test --test {{os}}
+
+build:
+    ./build {{os}}
+```
+
+```sh
+$ just
+./build linux
+./test --test linux
+```
+
+Any number of arguments of the form `NAME=VALUE` can be passed before recipes:
+
+```sh
+$ just os=plan9
+./build plan9
+./test --test plan9
+```
+
+Or you can use the `--set` flag:
+
+```sh
+$ just --set os bsd
+./build bsd
+./test --test bsd
+```
+
+=== Environment Variables
+
+Assignments prefixed with the `export` keyword will be exported to recipes as environment variables:
+
+```make
+export RUST_BACKTRACE = "1"
+
+test:
+    # will print a stack trace if it crashes
+    cargo test
+```
+
+=== Recipe Parameters
+
 Recipes may have parameters. Here recipe `build` has a parameter called `target`:
 
 ```make
@@ -292,7 +342,7 @@ Testing server:unit...
 ./test --tests unit server
 ```
 
-The last parameter to a recipe may be variadic, indicated with a `+` before the argument name:
+The last parameter of a recipe may be variadic, indicated with a `+` before the argument name:
 
 ```make
 backup +FILES:
@@ -308,59 +358,29 @@ FAQ.md                  100% 1831     1.8KB/s   00:00
 GRAMMAR.md              100% 1666     1.6KB/s   00:00
 ```
 
-Variables can be exported to recipes as environment variables:
+`{{...}}` substitutions may need to be quoted if they contains spaces. For example, if you have the following recipe:
 
 ```make
-export RUST_BACKTRACE = "1"
+search QUERY:
-
+    lynx https://www.google.com/?q={{QUERY}}
-test:
-    # will print a stack trace if it crashes
-    cargo test
 ```
 
-Variables can also be overridden from the command line:
+And you type:
+
+```sh
+$ just search "cat toupee"
+```
+
+Just will run the command `lynx https://www.google.com/?q=cat toupee`, which will get parsed by `sh` as `lynx`, `https://www.google.com/?q=cat`, and `toupee`, and not the intended `lynx` and `https://www.google.com/?q=cat toupee`.
+
+You can fix this by adding quotes:
 
 ```make
-os = "linux"
+search QUERY:
-
+    lynx 'https://www.google.com/?q={{QUERY}}'
-test: build
-    ./test --test {{os}}
-
-build:
-    ./build {{os}}
-```
-
-```sh
-$ just
-./build linux
-./test --test linux
-```
-
-You can pass any number of arguments of the form `NAME=VALUE` before recipes:
-
-```sh
-$ just os=plan9
-./build plan9
-./test --test plan9
-```
-
-Or you can use the `--set` flag:
-
-```sh
-$ just --set os bsd
-./build bsd
-./test --test bsd
-```
-
-Backticks can be used to store the result of commands:
-
-```make
-localhost = `dumpinterfaces | cut -d: -f2 | sed 's/\/.*//' | sed 's/ //g'`
-
-serve:
-    ./serve {{localhost}} 8080
 ```
 
+=== Write Recipes in other Languages
 
 Recipes that start with a `#!` are executed as scripts, so you can write recipes in other languages:
 
@@ -398,7 +418,9 @@ Yo from a shell script!
 Hello from ruby!
 ```
 
-`just` also supports a number of useful command line options for listing, dumping, and debugging recipes and variable:
+=== Command Line Options
+
+`just` supports a number of useful command line options for listing, dumping, and debugging recipes and variable:
 
 ```sh
 $ just --list
@@ -418,11 +440,78 @@ polyglot: python js perl sh ruby
 
 Run `just --help` to see all the options.
 
+=== Private Recipes
 
-miscellanea
+Recipes whose name starts with a `_` are omitted from `just --list`:
------------
 
-### syntax highlighting
+```make
+test: _test-helper
+  ./bin/test
+
+_test-helper:
+  ./bin/super-secret-test-helper-stuff
+```
+
+```sh
+$ just --list
+Available recipes:
+  test
+```
+
+And from `just --summary`:
+
+```sh
+$ just --summary
+test
+```
+
+This is useful for helper recipes which are only meant to be used as dependencies of other recipes.
+
+=== Quiet Recipes
+
+A recipe name may be prefixed with '@' to invert the meaning of '@' before each line:
+
+```make
+@quiet:
+  echo hello
+  echo goodbye
+  @# all done!
+```
+
+Now only the lines starting with '@' will be echoed:
+
+```sh
+$ j quiet
+hello
+goodbye
+# all done!
+```
+
+=== Invoking Justfiles in Other Directories
+
+If the first argument passed to `just` contains a `/`, then the following occurs:
+
+1. The argument is split at the last `/`.
+2. The part before the last `/` is treated as a directory. Just will start its search for the justfile there, instead of in the current directory.
+3. The part after the last slash is treated as a normal argument, or ignored if it is empty.
+
+This may seem a little strange, but it's useful if you wish to run a command in a justfile that is in a subdirectory.
+
+For example, if you are in a directory which contains a subdirectory named `foo`, which contains justfile with the recipe `build`, which is also the default recipe, the following are all equivalent:
+
+```sh
+$ (cd foo && just build)
+$ just foo/build
+$ just foo/
+```
+
+== Miscellanea
+
+=== Shell Alias
+
+For lightning-fast command running, put `alias j=just` in your shell's configuration file.
+
+=== Syntax Highlighting
 
 `justfile` syntax is close enough to `make` that you may want to tell your editor to use make syntax highlighting for just.
 
@@ -449,15 +538,15 @@ Include the following in a `justfile` to enable syntax highlighting in vim and e
 
 Feel free to send me the commands necessary to get syntax highlighting working in your editor of choice so that I may include them here.
 
-### justfile grammar
+=== Grammar
 
-A description of the grammar of justfiles can be found in [GRAMMAR.md](GRAMMAR.md).
+A non-normative grammar of justfiles can be found in link:GRAMMAR.md[].
 
-### just.sh
+=== just.sh
 
-Before `just` was a bloated rust program it was a tiny shell script that called `make`. If you can't or would rather not install rust you can find the old version in [extras/just.sh](extras/just.sh).
+Before `just` was a fancy rust program it was a tiny shell script that called `make`. You can find the old version in link:extras/just.sh[].
 
-### non-project specific justfile
+=== Non-Project Specific Justfile
 
 If you want some commands to be available everwhere, put them in `~/.justfile` and add the following to your shell's initialization file:
 
@@ -471,9 +560,11 @@ Or, if you'd rather they run in the current directory:
 alias .j='just --justfile ~/.justfile --working-directory .'
 ```
 
+I'm pretty sure that nobody actually uses this feature, but it's there.
 
-further ramblings
+¯\\_(ツ)_/¯
------------------
+
+== Further Ramblings
 
 I personally find it very useful to write a `justfile` for almost every project, big or small.
 
@@ -495,7 +586,7 @@ Some ideas for recipes:
 
 Even for small, personal projects it's nice to be able to remember commands by name instead of ^Reverse searching your shell history, and it's a huge boon to be able to go into an old project written in a random language with a mysterious build system and know that all the commands you need to do whatever you need to do are in the `justfile`, and that if you type `just` something useful (or at least interesting!) will probably happen.
 
-For ideas for recipes, check out [this project's `justfile`](justfile), or some of the `justfile`s [out in the wild](https://github.com/search?utf8=%E2%9C%93&q=filename%3Ajustfile).
+For ideas for recipes, check out link:justfile[this project's `justfile`], or some of the `justfile`s https://github.com/search?utf8=%E2%9C%93&q=filename%3Ajustfile[out in the wild].
 
 Anyways, I think that's about it for this incredibly long-winded README.
 

justfile

@@ -100,6 +100,16 @@ quine-text = '
 	}
 '
 
+render-readme:
+	#!/usr/bin/env ruby
+	require 'github/markup'
+	$rendered = GitHub::Markup.render("README.asc", File.read("README.asc"))
+	File.write('tmp/README.html', $rendered)
+
+watch-readme:
+	just render-readme
+	fswatch -ro README.asc | xargs -n1 -I{} just render-readme
+
 # run all polyglot recipes
 polyglot: python js perl sh ruby
 

src/unit.rs

@@ -1092,7 +1092,7 @@ fn readme_test() {
   let mut justfiles = vec![];
   let mut current = None;
 
-  for line in brev::slurp("README.md").lines() {
+  for line in brev::slurp("README.asc").lines() {
     if let Some(mut justfile) = current {
       if line == "```" {
         justfiles.push(justfile);

tmp/.gitignore

@@ -1 +1,2 @@
 *
+!.gitignore