ggreer/the_silver_searcher — pull request #145 by pooriaazimi (2013-02-02 23:14:36+00:00)
Title: Generate a more standard (and fish-friendly!) man page

This is what `man ack` looks like on my machine ( *I strongly recommend you to enable colors for man pages, like I did. Instructions for [bash](http://blog.0x1fff.com/2009/11/linux-tip-color-enabled-pager-less.html) and [fish](https://github.com/pooriaazimi/dotfiles/blob/master/fish/config.fish#L50-L58)* ):

![ack](https://f.cloud.github.com/assets/814637/121340/adf44140-6d8a-11e2-8407-cc499c280ee8.png)

This is `man ag`:

![ag-before](https://f.cloud.github.com/assets/814637/121341/c345ccf8-6d8a-11e2-9ddf-b49a78a2c946.png)

A couple things are wrong with `ag`'s man page:

1. Option lines start with a stupid, useless `o` (probably because they're list items in original markdown file)

2. Description lines are NOT in the line after option names (you know, like literally all other unix man pages!)

Why on earth would anyone care? Because I use the excellent [fish](http://ridiculousfish.com/shell/) shell. It has a handy little feature that quickly shows you all available options and their "meaning" when you press tab. For example, if you type `ag --a` and press tab, it will print the following in the terminal:
```
--ackmate: (Output results in a format parseable by ... [See Man Page])
--after (Print lines before match)
--all-text: (Search all text files)
--all-types: (Search all files)
```
or, when you type `ag -q`, the cursor will turn red (as there's no `-q` option!). These cases can bee seen in the following screenshot:

![ag-correct-and-wrong-options](https://f.cloud.github.com/assets/814637/121352/0ec36270-6d8c-11e2-81ea-70d5046082e4.png)

Even more useful, if you type `ag -` and press tab, it lists ALL options:

![fish-completions](https://f.cloud.github.com/assets/814637/121354/2748720e-6d8c-11e2-80b8-6bd92d0c289d.png)

The wonderful thing is that there's no `fish-completions` like there is for `bash` (`bash-completions`). `fish` literally generates this autocompletion list by parsing man pages.

So, this is why I care about "standard" man page.

Right now, `ag`'s man page is NOT standard and none of the above completions happen.

I changed the script that builds man pages (`doc/generate_man.sh` file) and added a fairly simple AWK script that tries to tidy up the markdown version of man page (`ag.1.md`). It writes the tidied version to a temp file (`ag.1.man.tmp`) that gets deleted at the end of the script. `ronn` now uses this temporary file to generate the actual man page.

The script is extremely straightforward. I've included a few comments that explain what (and why) I'm doing stuff (they might not be of best quality though, as it's 2:30 AM here!).

This is how `ag`'s man page looks like. As a bonus, I've even handled "multiline" options (two options that share the same description), as it's apparent in the second screenshot below!

![ag-after](https://f.cloud.github.com/assets/814637/121361/545e4ede-6d8d-11e2-8781-41dc0ca9b013.png)

![ag-after-multiline](https://f.cloud.github.com/assets/814637/121362/5c8bf3d6-6d8d-11e2-85ad-b4280c99b2e9.png)

Signed-off-by: Pooria Azimi