Transforms the reflectable capability design document to markdown.

Transforms the reflectable capability design document to markdown.

R=sigurdm@google.com

Committed: https://github.com/dart-lang/reflectable/commit/408d8b4f96d75a6e91bf978a8ba723dfb4c9d3da

[eernst, 2015-08-04 16:04:15]

eernst@google.com changed reviewers:
+ sigurdm@google.com

[eernst, 2015-08-04 16:04:15]

Not as pretty as the Google Docs document, but a standard format for github.

A notable glitch: We sometimes cannot show that certain elements in code are
meta-variables, intended to be replaced by other expressions in a given context.
For instance, we cannot make 'apiSelection' italic in
`admitSubtype(apiSelection*)` to express that 'apiSelection' is a meta-variable.
Added some HTML comments to indicate that this is an unsolved problem.

[sigurdm, 2015-08-05 08:31:56]

LGTM

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
File reflectable/doc/TheDesignOfReflectableCapabilities.md (right):

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:1: # The Design of
Reflectable Capabilities
It would be nice to refer to
http://www.dartdocs.org/documentation/reflectable/0.1.0/index.html#reflectabl...
(or rather the documentation page of the latest version) for an overview of
*using* the capabilities.

The dartdoc of capabilities should then be updated to give a nice introduction.

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:13: artifact which is
importing and using the package reflectable, generally
"software artifact" reads like we're writing a legal document. Maybe call it
"dart program" or similar.

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:338:  
I think github will render the table properly without this.

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:348: instance_invoke |
class_invoke |
Github-flavored markdown does not parse underscores inside words as italics
markers.

Also markdown allows escaping with `\`

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:547: <table>
The tables could also be formatted as 

|header1|header2 |
|-------|--------|
|d1     |d2      |

Not sure what is better.

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:559:
<td>invokingMeta(<i>MetadataClass</i>)</td>
Italics should be possible with _word_

[floitsch, 2015-08-05 11:02:49]

floitsch@google.com changed reviewers:
+ floitsch@google.com

[floitsch, 2015-08-05 11:02:49]

DBC.

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
File reflectable/doc/TheDesignOfReflectableCapabilities.md (right):

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:338:  
I would prefer not to have HTML in the document, unless there is no other way...

[eernst, 2015-08-05 14:22:20]

Gets rid of the HTML parts, at the expense of introducing some very long lines
(using |..| style markdown tables, which solves some other problems).

Will land it now; we can revert the tables later if the long lines are
unacceptable.

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
File reflectable/doc/TheDesignOfReflectableCapabilities.md (right):

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:1: # The Design of
Reflectable Capabilities
On 2015/08/05 08:31:56, sigurdm wrote:
> It would be nice to refer to
>
http://www.dartdocs.org/documentation/reflectable/0.1.0/index.html#reflectabl...
> (or rather the documentation page of the latest version) for an overview of
> *using* the capabilities.
> 
> The dartdoc of capabilities should then be updated to give a nice
introduction.

Done; it actually works to simply replace '0.1.0' by 'latest'. This might create
the problem that a viewer of an older version of package reflectable on github
will see a newer version of the library documentation when clicking on this
link. The trade-off is that this is more convenient than it would be to update
'0.1.0' to the new version number every time the version changes..

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:13: artifact which is
importing and using the package reflectable, generally
On 2015/08/05 08:31:56, sigurdm wrote:
> "software artifact" reads like we're writing a legal document. Maybe call it
> "dart program" or similar.

Obviously, it's illegal. ;-)

The point was that it applies to several different things (including a client
package and a client library). Reworded to preserve the generality without using
the word artifact.

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:338:  
On 2015/08/05 08:31:56, sigurdm wrote:
> I think github will render the table properly without this.

Indeed. Removed.

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:338:  
On 2015/08/05 11:02:49, floitsch wrote:
> I would prefer not to have HTML in the document, unless there is no other
way...

The HTML-free (markdown-style) tables are not pretty (long lines), but otherwise
there were no problems getting rid of the HTML.

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:348: instance_invoke |
class_invoke |
On 2015/08/05 08:31:56, sigurdm wrote:
> Github-flavored markdown does not parse underscores inside words as italics
> markers.
> 
> Also markdown allows escaping with `\`

Using that now.

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:547: <table>
On 2015/08/05 08:31:56, sigurdm wrote:
> The tables could also be formatted as 
> 
> |header1|header2 |
> |-------|--------|
> |d1     |d2      |
> 
> Not sure what is better.

Did that; works nicely, except that I can't see a way to avoid long lines (e.g.,
345 chars long).

https://codereview.chromium.org/1271693005/diff/1/reflectable/doc/TheDesignOf...
reflectable/doc/TheDesignOfReflectableCapabilities.md:559:
<td>invokingMeta(<i>MetadataClass</i>)</td>
On 2015/08/05 08:31:56, sigurdm wrote:
> Italics should be possible with _word_

Not in nested html, which is the reason why I couldn't use a "code block" in
here, which was the main reason why the solution using an HTML table wasn't nice
in the first place.

Now using *italics* in the markdown-style tables. Using `func(`*`expression`*`)`
style elements to indicate that parts of an expression are metavariables. This
produces an ugly bump (a non-boxed stripe) in the middle of the expression, but
everything else is OK. There might be a trick which will enable us to avoid that
bump (saw something about using a "zero width character" for exactly that kind
of situation, but cannot find it right now.

[eernst, 2015-08-05 14:22:38]

Committed patchset #2 (id:20001) manually as
408d8b4f96d75a6e91bf978a8ba723dfb4c9d3da (presubmit successful).

[sigurdm, 2015-08-05 14:33:34]

LGTM

[eernst, 2015-08-05 14:40:56]

Review response.

[eernst, 2015-08-05 14:41:58]

On 2015/08/05 14:40:56, eernst wrote:
> Review response.

Oops, my comments were deleted, I don't know how..

[eernst, 2015-08-05 14:44:31]

On 2015/08/05 14:41:58, eernst wrote:
> On 2015/08/05 14:40:56, eernst wrote:
> > Review response.
> 
> Oops, my comments were deleted, I don't know how..

OK, the comments are not lost, they are in patch set one. I just expected them
to show up here (at the bottom of https://codereview.chromium.org/1271693005) as
well.