Update NaCl technical overview for the PNaCl world

This updates the Native Client technical overview to the new bright world of PNaCl. As discussed in the team meeting, I'm still focusing on Native Client as the umbrella name for the technology, but trying to present PNaCl as the default toolchain. 

This update also removes some duplication from the document (with itself and with other documents), and introduces new, consistent diagrams. The other documents touched are just adding placeholders for links to look nicely in rendering.

It's still rough along the edges and has some TODOs, but I think it's ready for an initial review.

BUG=None
R=binji@chromium.org

Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=221511

[binji, 2013-09-04 21:51:07]

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
File native_client_sdk/src/doc/overview.rst (right):

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:45: give C and C++ (and eventually other
languages) the same level of portability
should we call out additional languages here? We haven't added another compiled
language yet...

Oh, wait. C#!

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:52: multiple threads, and access memory
directly - all without requiring
Why not em-dash?

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:66: comparable to a desktop app (within
5-15% of native speed); it also allows
Do we want to be this explicit about speed here?

We describe it as "close to native speed" below.

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:77: Client enables you to reuse current
software modules in a web application -
emdash?

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:111: Native Client is an umbrella name
for a set of inter-related software components
interrelated

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:133: * The NaCl sandbox ensures that code
accesses system resources only through
The rest of the document has one or more bold elements in each list. Maybe do
the same here?

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:148: An important part of the Native
Client approach is *PNaCl* - Portable Native
Maybe remove this line, and define PNaCl in the next line?

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:151: OS and architecture independent
format that can be freely distributed on the
OS- and architecture-independent
(I think)

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:163: **nexe** modules on the open web is
impossible. **nexe** modules can only be
impossible is inaccurate. Maybe "not allowed"?

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:165: browser plugins.
what do you mean by "in browser plugins"?

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:196: suitable for the JavaScript layer.
mention communicating with the NaCl module?

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:234: Salt and Pepper
This seems out of place now. Maybe just remove?

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:248: Versioning
Seems strange to have versioning below "where to go next"

[eliben, 2013-09-05 18:15:31]

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
File native_client_sdk/src/doc/overview.rst (right):

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:45: give C and C++ (and eventually other
languages) the same level of portability
On 2013/09/04 21:51:07, binji wrote:
> should we call out additional languages here? We haven't added another
compiled
> language yet...
> 
> Oh, wait. C#!

Do you mean that we should list more languages, or just not mention this at all?
It was my impression that the goal here is to make it clear that other languages
are possible, but there isn't one actually supported in the first release.

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:52: multiple threads, and access memory
directly - all without requiring
On 2013/09/04 21:51:07, binji wrote:
> Why not em-dash?

Done.

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:66: comparable to a desktop app (within
5-15% of native speed); it also allows
On 2013/09/04 21:51:07, binji wrote:
> Do we want to be this explicit about speed here?
> 

Yeah, I think we do. We've also mentioned it explicitly in the Google I/O
presentation.

> We describe it as "close to native speed" below.

I don't want to repeat the actual numbers everywhere, so I'm trying to use
"close to native speed" in the other places.

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:77: Client enables you to reuse current
software modules in a web application -
On 2013/09/04 21:51:07, binji wrote:
> emdash?

Done.

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:111: Native Client is an umbrella name
for a set of inter-related software components
On 2013/09/04 21:51:07, binji wrote:
> interrelated

Done.

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:133: * The NaCl sandbox ensures that code
accesses system resources only through
On 2013/09/04 21:51:07, binji wrote:
> The rest of the document has one or more bold elements in each list. Maybe do
> the same here?

I'm not sure bolding makes sense here (maybe it should not be done in other
places too?)

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:148: An important part of the Native
Client approach is *PNaCl* - Portable Native
On 2013/09/04 21:51:07, binji wrote:
> Maybe remove this line, and define PNaCl in the next line?

I want to be clear that PNaCl is part of NaCl. Any suggestions on how to express
this clearly?

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:151: OS and architecture independent
format that can be freely distributed on the
On 2013/09/04 21:51:07, binji wrote:
> OS- and architecture-independent
> (I think)

I'll add the second hyphen, but leave OS-? Really?

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:163: **nexe** modules on the open web is
impossible. **nexe** modules can only be
On 2013/09/04 21:51:07, binji wrote:
> impossible is inaccurate. Maybe "not allowed"?

Done.

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:165: browser plugins.
On 2013/09/04 21:51:07, binji wrote:
> what do you mean by "in browser plugins"?

Should say extensions instead, perhaps?

[though PPAPI has "plugin" in its name, I guess the line is vague?]

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:196: suitable for the JavaScript layer.
On 2013/09/04 21:51:07, binji wrote:
> mention communicating with the NaCl module?

Done and made the paragraph shorter. I think "simple programming tasks...
suitable for..." is kind of patronizing so I removed it :)

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:234: Salt and Pepper
On 2013/09/04 21:51:07, binji wrote:
> This seems out of place now. Maybe just remove?

Gladly

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:248: Versioning
On 2013/09/04 21:51:07, binji wrote:
> Seems strange to have versioning below "where to go next"

Done.

[binji, 2013-09-05 20:28:58]

lgtm

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
File native_client_sdk/src/doc/overview.rst (right):

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:45: give C and C++ (and eventually other
languages) the same level of portability
On 2013/09/05 18:15:31, eliben wrote:
> On 2013/09/04 21:51:07, binji wrote:
> > should we call out additional languages here? We haven't added another
> compiled
> > language yet...
> > 
> > Oh, wait. C#!
> 
> Do you mean that we should list more languages, or just not mention this at
all?
> It was my impression that the goal here is to make it clear that other
languages
> are possible, but there isn't one actually supported in the first release.

Sorry, my comment was unclear. I was suggesting that we don't call out other
languages at all, because we don't really support other languages.

Then I remembered that we do support C# (sort of), but perhaps this isn't the
place to mention that.

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:66: comparable to a desktop app (within
5-15% of native speed); it also allows
On 2013/09/05 18:15:31, eliben wrote:
> On 2013/09/04 21:51:07, binji wrote:
> > Do we want to be this explicit about speed here?
> > 
> 
> Yeah, I think we do. We've also mentioned it explicitly in the Google I/O
> presentation.
> 
> > We describe it as "close to native speed" below.
> 
> I don't want to repeat the actual numbers everywhere, so I'm trying to use
> "close to native speed" in the other places.
> 

OK.

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:139: These come in addition to the
existing sandbox in the browser - the Native
another mdash

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:148: An important part of the Native
Client approach is *PNaCl* - Portable Native
On 2013/09/05 18:15:31, eliben wrote:
> On 2013/09/04 21:51:07, binji wrote:
> > Maybe remove this line, and define PNaCl in the next line?
> 
> I want to be clear that PNaCl is part of NaCl. Any suggestions on how to
express
> this clearly?

Not sure ... this sentence just doesn't say much to me other than "Portable
Native Client is called PNaCl", which is why I suggested moving that to the next
line.

The sentence seems a bit circuitous to me, but maybe I'm being too nitpicky.

Also, if you decide to keep it, use an mdash.

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:151: OS and architecture independent
format that can be freely distributed on the
On 2013/09/05 18:15:31, eliben wrote:
> On 2013/09/04 21:51:07, binji wrote:
> > OS- and architecture-independent
> > (I think)
> 
> I'll add the second hyphen, but leave OS-? Really?

I found this link:
http://english.stackexchange.com/questions/39860/can-a-hyphen-be-used-without...

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:165: browser plugins.
On 2013/09/05 18:15:31, eliben wrote:
> On 2013/09/04 21:51:07, binji wrote:
> > what do you mean by "in browser plugins"?
> 
> Should say extensions instead, perhaps?
> 
> [though PPAPI has "plugin" in its name, I guess the line is vague?]

I guess I was confused because extensions are installed from the Chrome Web
Store, and if they aren't they can't run NEXEs (without a flag).

https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
native_client_sdk/src/doc/overview.rst:196: suitable for the JavaScript layer.
On 2013/09/05 18:15:31, eliben wrote:
> On 2013/09/04 21:51:07, binji wrote:
> > mention communicating with the NaCl module?
> 
> Done and made the paragraph shorter. I think "simple programming tasks...
> suitable for..." is kind of patronizing so I removed it :)

I like the new paragraph better.

[eliben, 2013-09-05 20:43:57]

>
https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
> native_client_sdk/src/doc/overview.rst:139: These come in addition to the
> existing sandbox in the browser - the Native
> another mdash

done

> 
>
https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
> native_client_sdk/src/doc/overview.rst:148: An important part of the Native
> Client approach is *PNaCl* - Portable Native
> On 2013/09/05 18:15:31, eliben wrote:
> > On 2013/09/04 21:51:07, binji wrote:
> > > Maybe remove this line, and define PNaCl in the next line?
> > 
> > I want to be clear that PNaCl is part of NaCl. Any suggestions on how to
> express
> > this clearly?
> 
> Not sure ... this sentence just doesn't say much to me other than "Portable
> Native Client is called PNaCl", which is why I suggested moving that to the
next
> line.
> 
> The sentence seems a bit circuitous to me, but maybe I'm being too nitpicky.
> 

Ah, I see what you mean. Yes, I can simplify it as you suggest.

> Also, if you decide to keep it, use an mdash.
> 
>
https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
> native_client_sdk/src/doc/overview.rst:151: OS and architecture independent
> format that can be freely distributed on the
> On 2013/09/05 18:15:31, eliben wrote:
> > On 2013/09/04 21:51:07, binji wrote:
> > > OS- and architecture-independent
> > > (I think)
> > 
> > I'll add the second hyphen, but leave OS-? Really?
> 
> I found this link:
>
http://english.stackexchange.com/questions/39860/can-a-hyphen-be-used-without...
> 

Who am I to argue with the Chicago manual of style? Done!

>
https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
> native_client_sdk/src/doc/overview.rst:165: browser plugins.
> On 2013/09/05 18:15:31, eliben wrote:
> > On 2013/09/04 21:51:07, binji wrote:
> > > what do you mean by "in browser plugins"?
> > 
> > Should say extensions instead, perhaps?
> > 
> > [though PPAPI has "plugin" in its name, I guess the line is vague?]
> 
> I guess I was confused because extensions are installed from the Chrome Web
> Store, and if they aren't they can't run NEXEs (without a flag).
> 
>
https://codereview.chromium.org/23629023/diff/8001/native_client_sdk/src/doc/...
> native_client_sdk/src/doc/overview.rst:196: suitable for the JavaScript layer.
> On 2013/09/05 18:15:31, eliben wrote:
> > On 2013/09/04 21:51:07, binji wrote:
> > > mention communicating with the NaCl module?
> > 
> > Done and made the paragraph shorter. I think "simple programming tasks...
> > suitable for..." is kind of patronizing so I removed it :)
> 
> I like the new paragraph better.

[eliben, 2013-09-05 20:53:07]

Committed patchset #5 manually as r221511 (presubmit successful).