i#1709 Add README.md files to facilitate GitHub browsing

Commit log for first patchset:
---------------
i#1709 Add README.md files to facilitate GitHub browsing

Adding a README.md file in every top-level directory, and every
sub-directory having a dedicated page in the API documentation.

Fixes #1709
---------------

[bruening, 2015-06-18 21:56:26]

I'm curious: why the footnote style instead of inlined links?  I would think
inlined would be easier to read and maintain w/o any separation of pieces.

LGTM w/ comments

https://codereview.appspot.com/242420043/diff/1/api/docs/README.md
File api/docs/README.md (right):

https://codereview.appspot.com/242420043/diff/1/api/docs/README.md#newcode4
api/docs/README.md:4: [1]: http://dynamorio.org/docs/index.html
IMHO the inlined syntax is more readable:

[dynamorio.org](http://dynamorio.org/docs/index.html)

https://codereview.appspot.com/242420043/diff/1/api/samples/README.md
File api/samples/README.md (right):

https://codereview.appspot.com/242420043/diff/1/api/samples/README.md#newcode3
api/samples/README.md:3: client can be found in the source code comments at the
top of each file.
Add a link to http://dynamorio.org/docs/API_samples.html

https://codereview.appspot.com/242420043/diff/1/clients/drcov/README.md
File clients/drcov/README.md (right):

https://codereview.appspot.com/242420043/diff/1/clients/drcov/README.md#newcode3
clients/drcov/README.md:3: [1]: http://dynamorio.org/docs/page_drcov.html
Again, why not inlined?  Why footnote?

https://codereview.appspot.com/242420043/diff/1/ext/drsyms/README.md
File ext/drsyms/README.md (right):

https://codereview.appspot.com/242420043/diff/1/ext/drsyms/README.md#newcode2
ext/drsyms/README.md:2: reading symbol information from Windows PDB files or
Linux ELF, Mac Mach-O, or Windows
suggest: s/or/or from/

https://codereview.appspot.com/242420043/diff/1/ext/drutil/README.md
File ext/drutil/README.md (right):

https://codereview.appspot.com/242420043/diff/1/ext/drutil/README.md#newcode1
ext/drutil/README.md:1: The [drutil][1] DynamoRIO Extension provides various
utilities for inserting instrumentation.
style: line too long

https://codereview.appspot.com/242420043/diff/1/libutil/README.md
File libutil/README.md (right):

https://codereview.appspot.com/242420043/diff/1/libutil/README.md#newcode2
libutil/README.md:2: documentation is provided because it is not intended for
standalone use.
Not entirely true: drconfiglib and drfrontendlib are implemented here.

[Byron, 2015-06-18 23:47:54]

Commit log for latest patchset:
---------------
i#1709 Add README.md files to facilitate GitHub browsing

Adding a README.md file in every top-level directory, and every
sub-directory having a dedicated page in the API documentation.

Fixes #1709

Review-URL: https://codereview.appspot.com/242420043
---------------

[Byron, 2015-06-18 23:48:17]

https://codereview.appspot.com/242420043/diff/1/api/docs/README.md
File api/docs/README.md (right):

https://codereview.appspot.com/242420043/diff/1/api/docs/README.md#newcode4
api/docs/README.md:4: [1]: http://dynamorio.org/docs/index.html
On 2015/06/18 21:56:25, bruening wrote:
> IMHO the inlined syntax is more readable:
> 
> [dynamorio.org](http://dynamorio.org/docs/index.html)


I can change to inline if you prefer. But here's my reasons for using the
subscript version:

1. It gets awkward with the line length. There will be some very short line
fragments, and it's difficult to edit the text. 

2. Most readers will only see it on GitHub where the link is transformed into an
<a> tag.
 
3. For readers browsing a checkout in bash, I was thinking the text should match
what you see on the doxy page, so they get the idea "ok, here's the rest of
it..." 

4. The subscript version is actually quite popular for plain text--many projects
use it even when they expect people to read the text version more often.

https://codereview.appspot.com/242420043/diff/1/api/samples/README.md
File api/samples/README.md (right):

https://codereview.appspot.com/242420043/diff/1/api/samples/README.md#newcode3
api/samples/README.md:3: client can be found in the source code comments at the
top of each file.
On 2015/06/18 21:56:25, bruening wrote:
> Add a link to http://dynamorio.org/docs/API_samples.html

Done.

https://codereview.appspot.com/242420043/diff/1/clients/drcov/README.md
File clients/drcov/README.md (right):

https://codereview.appspot.com/242420043/diff/1/clients/drcov/README.md#newcode3
clients/drcov/README.md:3: [1]: http://dynamorio.org/docs/page_drcov.html
On 2015/06/18 21:56:25, bruening wrote:
> Again, why not inlined?  Why footnote?

See previous comment on /api/docs/README.md.

https://codereview.appspot.com/242420043/diff/1/ext/drsyms/README.md
File ext/drsyms/README.md (right):

https://codereview.appspot.com/242420043/diff/1/ext/drsyms/README.md#newcode2
ext/drsyms/README.md:2: reading symbol information from Windows PDB files or
Linux ELF, Mac Mach-O, or Windows
On 2015/06/18 21:56:25, bruening wrote:
> suggest: s/or/or from/

Done. I stole all of the text from the DR doxygen, so should I make the same
change there?

https://codereview.appspot.com/242420043/diff/1/ext/drutil/README.md
File ext/drutil/README.md (right):

https://codereview.appspot.com/242420043/diff/1/ext/drutil/README.md#newcode1
ext/drutil/README.md:1: The [drutil][1] DynamoRIO Extension provides various
utilities for inserting instrumentation.
On 2015/06/18 21:56:26, bruening wrote:
> style: line too long

Done.

https://codereview.appspot.com/242420043/diff/1/libutil/README.md
File libutil/README.md (right):

https://codereview.appspot.com/242420043/diff/1/libutil/README.md#newcode2
libutil/README.md:2: documentation is provided because it is not intended for
standalone use.
On 2015/06/18 21:56:26, bruening wrote:
> Not entirely true: drconfiglib and drfrontendlib are implemented here.

Done.

[bruening, 2015-06-26 15:01:46]

https://codereview.appspot.com/242420043/diff/1/api/docs/README.md
File api/docs/README.md (right):

https://codereview.appspot.com/242420043/diff/1/api/docs/README.md#newcode4
api/docs/README.md:4: [1]: http://dynamorio.org/docs/index.html
On 2015/06/18 23:48:16, Byron wrote:
> On 2015/06/18 21:56:25, bruening wrote:
> > IMHO the inlined syntax is more readable:
> > 
> > [dynamorio.org](http://dynamorio.org/docs/index.html)
> 
> 
> I can change to inline if you prefer. But here's my reasons for using the
> subscript version:
> 
> 1. It gets awkward with the line length. There will be some very short line
> fragments, and it's difficult to edit the text. 
> 
> 2. Most readers will only see it on GitHub where the link is transformed into
an
> <a> tag.
>  
> 3. For readers browsing a checkout in bash, I was thinking the text should
match
> what you see on the doxy page, so they get the idea "ok, here's the rest of
> it..." 
> 
> 4. The subscript version is actually quite popular for plain text--many
projects
> use it even when they expect people to read the text version more often. 

I dunno, I would still vote for inline to have everything in one place.  If
there were 10 different links with 10 different footnotes, I wouldn't want to
have to look in 2 places for each one just to understand where they're linking
to, and to edit each sounds like a pain.

[Byron, 2015-06-26 15:49:47]

Commit log for latest patchset:
---------------
i#1709 Add README.md files: added README.md files

Added a README.md file in every top-level directory, and every
sub-directory having a dedicated page in the API documentation,
to facilitate browsing on github.

Fixes #1709

Review-URL: https://codereview.appspot.com/242420043
---------------

[bruening, 2015-06-26 20:06:43]

LGTM

[Byron, 2015-06-26 20:42:54]

Committed as
https://github.com/DynamoRIO/dynamorio/commit/a729fe43f9faa2c2018c07943ca0317...

Final commit log: 
---------------
i#1709 Add README.md files: added README.md files

Added a README.md file in every top-level directory, and every
sub-directory having a dedicated page in the API documentation,
to facilitate browsing on github.

Fixes #1709

Review-URL: https://codereview.appspot.com/242420043
---------------