Generate a more standard (and fish-friendly!) man page #145

Merged
merged 1 commit into from Feb 3, 2013

Conversation

Projects
None yet
2 participants
Contributor

pooriaazimi commented Feb 2, 2013

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 and fish ):

ack

This is man ag:

ag-before

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 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

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

fish-completions

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. Currently, ag's man page displays it all wrong and messed up.

ag-after

ag-after-multiline

Signed-off-by: Pooria Azimi pooriaazimi@me.com

@pooriaazimi pooriaazimi more standard (and fish-friendly!) man page with a simple awk script
Signed-off-by: Pooria Azimi <pooriaazimi@me.com>
ddee41c
Owner

ggreer commented Feb 3, 2013

First of all, nice job on this pull request. You explained the problem, your solution, and included screenshots. This is pretty much my favorite thing to see.

One bit of feedback: If you're dealing with generated code, it's best to split the PR into (at least) two commits. In this case, you could have had one commit adding the awk stuff and another for the regenerated manpage. I don't care that much, but others can be sticklers about that sort of thing.

I just have one question: Instead of using awk to change the markdown file, why didn't you change the markdown file manually?

Owner

ggreer commented Feb 3, 2013

Ohhh yeah.

@ggreer ggreer added a commit that referenced this pull request Feb 3, 2013

@ggreer ggreer Merge pull request #145 from pooriaazimi/master
Generate a more standard (and fish-friendly!) man page
f671937

@ggreer ggreer merged commit f671937 into ggreer:master Feb 3, 2013

Contributor

pooriaazimi commented Feb 3, 2013

Thanks :)

And you're right about splitting up the PR. I should've done that. I was hesitant whether to include .1 file or not (on one hand, it was a generated file and those things make a repo dirty, on the other hand I wanted the PR to be more complete) - your solution is the best. I'll keep that in mind, thanks :)

As to why I just didn't change the .md file:

  1. I thought it might be frowned upon!
  2. It would require future developers to remember a few "rules" about Markdown (namely, to end lines with to insert a literal<br>, or use&nbsp; to indent instead of regular `)
  3. It would make .md file a bit unreadable and Un-markdown-y.
`-v --invert-match`  
`-w --word-regexp`:  
&nbsp;&nbsp;&nbsp;&nbsp;  Only match whole words.

is not as nice-looking as

  * `-v --invert-match`
  * `-w --word-regexp`:
       Only match whole words.`
  1. You have to keep practicing old tools or you'll forget them very soon :) I've been programming in Ruby lately and it took me like 10 minutes to realize why my ifs weren't working (you have to enclose the condition in ( and the body in {s)!

😄

Owner

ggreer commented Feb 3, 2013

Good points. My curiosity is satisfied.

About ag.1: Like you, I don't like to put generated code in source control. On the other hand, I didn't want to force people to install ronn just to install ag.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment