Add table of contents in readme

[simov]

• Add table of contents in readme
• Add back to top links at the end of each section
• Add horizontal line divider after each section
• Add visual cues in options list

Closes #1340
Also related to #1331

Basically I refactored the readme according to what @nylen outlined in #1340 (comment) as collaborative effort to improve the readme.

Easier to review the this PR would be to just check out the rendered markdown file https://github.com/simov/request/tree/refactor-readme

Table of contents and back to top links at the end of each section are pretty self explanatory. The horizontal line divider between the sections is mostly for easier maintenance of the file (if you have good markdown syntax highlighting you'll now what I mean) Also I'm putting 2 blank lines before and after each horizontal rule, and two blank lines before each header (not an actual rule, just fyi)

The last thing was to use simple horizontal lines again, this time for the list of options.

Now if you take a look at it, you'll notice that it's a bit easier to fix your sight on certain things. So the presentation remains linear (no additional headers or text) yet just enough to scan through it faster.

I also wanted to split the sections into separate files and put them under docs folder. But I couldn't figure out a good way to introduce the building process to the user while having the combined readme all the time too.

/cc @rockbot @nylen @FredKSchott and anyone else

[FredKSchott]

+1 I like it

[nylen]

This is awesome.

I'm merging so it doesn't go stale. A few points of feedback, though:

Horizontal lines

I'm not super excited about all the <hr>s. I think these should just be headings instead, since GitHub already provides separation:

The splits in the all-options section should be named headers too, but at a lower level, like ####:

Linking to individual options

There are lots of places in the docs where we cross-reference options, and making them clickable links would be a nice enhancement. Last time I checked (Jan 2015) the following markup works on GitHub:

<a href="#user-content-something" id="something">some text</a>
<a href="#user-content-something" name="something">some text</a>

Examples:

• https://github.com/nylen/playground/blob/patch-1/anchors.md#user-content-dsazf
• https://github.com/nylen/playground/blob/patch-1/anchors.md#user-content-sdaf

Huge images

Images in this post are huge because retina display,

[nylen]

Forgot to say - I think using headers & spacing addresses the maintainability concerns too, since good Markdown syntax highlighting applies to headers.

[simov]

I intentionally didn't wanted to add additional headers to the options list, but yeah if someone show me a good example of using them, I can change my mind eventually. Btw H6 is a grayed out header according to the GitHub's css:

Wow I'm a header too

As for the horizontal lines separating the sections - I can live without them, if that's such an issue.

Huge images - nice! It's like me wearing glasses

[nylen]

Not a big deal, it's still a huge improvement. Just my $0.02: it's graphically cleaner to use only headers rather than both headers and lines, and semantically clearer to use named sections rather than lines. Named sections also makes the best place for new options more clear.

[nickmccurdy]

@nylen 👍