Copy edit Learn Basics section.

Copy edit Learn Basics section. Includes first group of new illustrations to make overall site images look googly and at the same time part of a single design process.

BUG=none
R=
TEST=none
NOTRY=true
(documentation only change)

Committed: https://crrev.com/3e1df835d674fd12add70332fda9cd349a7423fa
Cr-Commit-Position: refs/heads/master@{#296017}

[jpmedley, 2014-09-17 22:48:42]

jmedley@chromium.org changed reviewers:
+ jfb@chromium.org, mkearney@chromium.org

[jpmedley, 2014-09-18 14:03:53]

jmedley@chromium.org changed reviewers:
+ smain@chromium.org

[binji, 2014-09-18 17:58:37]

binji@chromium.org changed reviewers:
+ binji@chromium.org

[binji, 2014-09-18 17:58:38]

driveby feedback.

I like the changes, and the new images look great!

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/na...
File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/na...
native_client_sdk/src/doc/nacl-and-pnacl.rst:61: the pexe , even on new
architectures. Moreover, if an existing architecture is
extra space after pexe

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/ov...
File native_client_sdk/src/doc/overview.rst (right):

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/ov...
native_client_sdk/src/doc/overview.rst:60: same level of portability as
JavaScript, but with greater safety.
not quite right; we shouldn't claim to be safer than JavaScript.

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/ov...
native_client_sdk/src/doc/overview.rst:95: * **Existing software components:**
Native Client lets you to repurpose existing
remove "to"

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/ov...
native_client_sdk/src/doc/overview.rst:103: * **Existing functionality:** Native
Client allows you to embed existing
I'm not sure I understand what this first means by "existing functionality"

[native-client-reviews_googlegroups.com, 2014-09-18 18:41:42]

There are more of those to come. I'm going for googly colors and a
consistent design vocabulary. The new ones also have meaningful alt tags.

Joe Medley | Technical Writer | jmedley@google.com | 816-678-7195

On Thu, Sep 18, 2014 at 11:58 AM, <binji@chromium.org> wrote:

> driveby feedback.
>
> I like the changes, and the new images look great!
>
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/nacl-and-pnacl.rst
> File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/nacl-and-pnacl.rst#newcode61
> native_client_sdk/src/doc/nacl-and-pnacl.rst:61: the pexe , even on new
> architectures. Moreover, if an existing architecture is
> extra space after pexe
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/overview.rst
> File native_client_sdk/src/doc/overview.rst (right):
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/overview.rst#newcode60
> native_client_sdk/src/doc/overview.rst:60: same level of portability as
> JavaScript, but with greater safety.
> not quite right; we shouldn't claim to be safer than JavaScript.
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/overview.rst#newcode95
> native_client_sdk/src/doc/overview.rst:95: * **Existing software
> components:** Native Client lets you to repurpose existing
> remove "to"
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/overview.rst#newcode103
> native_client_sdk/src/doc/overview.rst:103: * **Existing
> functionality:** Native Client allows you to embed existing
> I'm not sure I understand what this first means by "existing
> functionality"
>
> https://codereview.chromium.org/581643004/
>

-- 
You received this message because you are subscribed to the Google Groups
"Native-Client-Reviews" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to native-client-reviews+unsubscribe@googlegroups.com.
To post to this group, send email to native-client-reviews@googlegroups.com.
Visit this group at http://groups.google.com/group/native-client-reviews.
For more options, visit https://groups.google.com/d/optout.

[chromium-reviews, 2014-09-18 18:41:43]

There are more of those to come. I'm going for googly colors and a
consistent design vocabulary. The new ones also have meaningful alt tags.

Joe Medley | Technical Writer | jmedley@google.com | 816-678-7195

On Thu, Sep 18, 2014 at 11:58 AM, <binji@chromium.org> wrote:

> driveby feedback.
>
> I like the changes, and the new images look great!
>
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/nacl-and-pnacl.rst
> File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/nacl-and-pnacl.rst#newcode61
> native_client_sdk/src/doc/nacl-and-pnacl.rst:61: the pexe , even on new
> architectures. Moreover, if an existing architecture is
> extra space after pexe
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/overview.rst
> File native_client_sdk/src/doc/overview.rst (right):
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/overview.rst#newcode60
> native_client_sdk/src/doc/overview.rst:60: same level of portability as
> JavaScript, but with greater safety.
> not quite right; we shouldn't claim to be safer than JavaScript.
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/overview.rst#newcode95
> native_client_sdk/src/doc/overview.rst:95: * **Existing software
> components:** Native Client lets you to repurpose existing
> remove "to"
>
> https://codereview.chromium.org/581643004/diff/1/native_
> client_sdk/src/doc/overview.rst#newcode103
> native_client_sdk/src/doc/overview.rst:103: * **Existing
> functionality:** Native Client allows you to embed existing
> I'm not sure I understand what this first means by "existing
> functionality"
>
> https://codereview.chromium.org/581643004/
>

To unsubscribe from this group and stop receiving emails from it, send an email
to chromium-reviews+unsubscribe@chromium.org.

[jpmedley, 2014-09-18 19:03:00]

PTAL

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/na...
File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/na...
native_client_sdk/src/doc/nacl-and-pnacl.rst:61: the pexe , even on new
architectures. Moreover, if an existing architecture is
On 2014/09/18 17:58:38, binji wrote:
> extra space after pexe

Done.

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/ov...
File native_client_sdk/src/doc/overview.rst (right):

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/ov...
native_client_sdk/src/doc/overview.rst:60: same level of portability as
JavaScript, but with greater safety.
On 2014/09/18 17:58:38, binji wrote:
> not quite right; we shouldn't claim to be safer than JavaScript.

I reversed this. Now I want to play devil's advocate. With cross-site scripting
and the ability to do things like dom edits and url swaps, I've never thought of
JS as particularly secure.

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/ov...
native_client_sdk/src/doc/overview.rst:95: * **Existing software components:**
Native Client lets you to repurpose existing
On 2014/09/18 17:58:38, binji wrote:
> remove "to"

Done.

https://codereview.chromium.org/581643004/diff/1/native_client_sdk/src/doc/ov...
native_client_sdk/src/doc/overview.rst:103: * **Existing functionality:** Native
Client allows you to embed existing
On 2014/09/18 17:58:38, binji wrote:
> I'm not sure I understand what this first means by "existing functionality"

I don't remember what I was thinking that day. I'll undo it.

[JF, 2014-09-19 18:16:17]

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:29: platform. This is neither
portable nor conveient, making it ill-suited for the
s/conveient/convenient/

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:49: #. compiling the source code to
a bitcode executable (pexe), and
We usually use **nexe** and **pexe**, though I think we haven't been convenient?

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:58: specific nexes. Since the pexe
uses an abstract, architecture- and os-
Capitalize OS.

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:66: technologies with the
performance and security benefits of Native Client.
Interesting points we may want to make:
 * NaCl is currently an implementation detail of PNaCl: we still benefit from
the security that NaCl has.
 * PNaCl can be more efficient on certain operating systems, and can have novel
sandboxing approaches.

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:108: * Your application uses
certain GNU extensions not supported by PNaCl, like
"not supported by PNaCl's LLVM toolchain".

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
File native_client_sdk/src/doc/overview.rst (right):

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:37: target a specific hardware platform.
Portable can run on any Chrome browser. A
I'd say "on the open web" instead of "any Chrome browser".

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:59: Native Client also aims to give C and
C++ (and eventually other languages) the
I'd drop the "eventually", and say "and other languages targeting it".

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:162: occurs before any code is executed.
I'd say "Translation occurs ahead of time, before any code is executed."

Ahead of time (AOT) is a contrast to just in time (JIT), people know these two
terms.

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:164: * The right side of the diagram
shows **(non-portable) Native Client**. A gcc
GCC should be capitalized.

[jpmedley, 2014-09-19 20:40:33]

PTAL

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:29: platform. This is neither
portable nor conveient, making it ill-suited for the
On 2014/09/19 18:16:17, JF wrote:
> s/conveient/convenient/

Done.

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:49: #. compiling the source code to
a bitcode executable (pexe), and
On 2014/09/19 18:16:17, JF wrote:
> We usually use **nexe** and **pexe**, though I think we haven't been
convenient?

To what end? I don't think it's really needed and it makes pages a little
noisier than they need to be.

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:58: specific nexes. Since the pexe
uses an abstract, architecture- and os-
On 2014/09/19 18:16:17, JF wrote:
> Capitalize OS.

Done.

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:66: technologies with the
performance and security benefits of Native Client.
On 2014/09/19 18:16:17, JF wrote:
> Interesting points we may want to make:
>  * NaCl is currently an implementation detail of PNaCl: we still benefit from
> the security that NaCl has.
>  * PNaCl can be more efficient on certain operating systems, and can have
novel
> sandboxing approaches.

Done.

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:108: * Your application uses
certain GNU extensions not supported by PNaCl, like
On 2014/09/19 18:16:17, JF wrote:
> "not supported by PNaCl's LLVM toolchain".

Done.

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
File native_client_sdk/src/doc/overview.rst (right):

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:37: target a specific hardware platform.
Portable can run on any Chrome browser. A
On 2014/09/19 18:16:17, JF wrote:
> I'd say "on the open web" instead of "any Chrome browser".

Done.

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:59: Native Client also aims to give C and
C++ (and eventually other languages) the
On 2014/09/19 18:16:17, JF wrote:
> I'd drop the "eventually", and say "and other languages targeting it".

Done.

That implies that there ARE other languages targeting it. Are there other
languages?

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:162: occurs before any code is executed.
On 2014/09/19 18:16:17, JF wrote:
> I'd say "Translation occurs ahead of time, before any code is executed."
> 
> Ahead of time (AOT) is a contrast to just in time (JIT), people know these two
> terms.

Done.

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:164: * The right side of the diagram
shows **(non-portable) Native Client**. A gcc
On 2014/09/19 18:16:17, JF wrote:
> GCC should be capitalized.

Done.

[JF, 2014-09-22 16:53:05]

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):

https://codereview.chromium.org/581643004/diff/20001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:49: #. compiling the source code to
a bitcode executable (pexe), and
On 2014/09/19 20:40:33, jmedley wrote:
> On 2014/09/19 18:16:17, JF wrote:
> > We usually use **nexe** and **pexe**, though I think we haven't been
> convenient?
> 
> To what end? I don't think it's really needed and it makes pages a little
> noisier than they need to be.

It just makes them bold. I'm not necessarily advocating either way, just for
consistency (the section above has **nexe** and this one doesn't have **pexe**).

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:25: near-native speeds and taking
advantage of multiple cores with shared memory.
Mention SIMD too? Or maybe rephrase to explain that we expose a CPU's full
capabilities, which includes SIMD and multicore+share memory?

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:107: with a PNaCl port of the
``newlib`` C standard library . Dynamic linking and
There's a space before the period .

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
File native_client_sdk/src/doc/overview.rst (right):

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:59: Native Client also aims to give C and
C++ (and other languages targeting it) the
Drop "aims to"? I'd say we give the same level (if not more) of portability and
safety (though in an entirely different way).

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:170: toolchain should only be used for
applications that wont be distributed on the
s/wont/won't/

[jpmedley, 2014-09-22 17:19:51]

PTAL

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:25: near-native speeds and taking
advantage of multiple cores with shared memory.
On 2014/09/22 16:53:05, JF wrote:
> Mention SIMD too? Or maybe rephrase to explain that we expose a CPU's full
> capabilities, which includes SIMD and multicore+share memory?

Done.

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:107: with a PNaCl port of the
``newlib`` C standard library . Dynamic linking and
On 2014/09/22 16:53:05, JF wrote:
> There's a space before the period .

Done.

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
File native_client_sdk/src/doc/overview.rst (right):

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:59: Native Client also aims to give C and
C++ (and other languages targeting it) the
On 2014/09/22 16:53:05, JF wrote:
> Drop "aims to"? I'd say we give the same level (if not more) of portability
and
> safety (though in an entirely different way).

Done.

https://codereview.chromium.org/581643004/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/overview.rst:170: toolchain should only be used for
applications that wont be distributed on the
On 2014/09/22 16:53:05, JF wrote:
> s/wont/won't/

Done.

[JF, 2014-09-22 17:36:56]

lgtm after line-swap fix.

https://codereview.chromium.org/581643004/diff/60001/native_client_sdk/src/do...
File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):

https://codereview.chromium.org/581643004/diff/60001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:40: Chrome Web Store.
The line swap here seems like a bug.

[jpmedley, 2014-09-22 18:26:15]

The CQ bit was checked by jmedley@chromium.org

[jpmedley, 2014-09-22 18:26:34]

https://codereview.chromium.org/581643004/diff/60001/native_client_sdk/src/do...
File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):

https://codereview.chromium.org/581643004/diff/60001/native_client_sdk/src/do...
native_client_sdk/src/doc/nacl-and-pnacl.rst:40: Chrome Web Store.
On 2014/09/22 17:36:56, JF wrote:
> The line swap here seems like a bug.

Done.

[commit-bot: I haz the power, 2014-09-22 18:26:59]

CQ is trying da patch. Follow status at
 https://chromium-cq-status.appspot.com/patch-status/581643004/80001

[commit-bot: I haz the power, 2014-09-22 18:27:38]

Committed patchset #5 (id:80001) as 54b5ad050eed9b55fefe83b53e419867e617b610

[commit-bot: I haz the power, 2014-09-22 18:28:19]

Patchset 5 (id:??) landed as
https://crrev.com/3e1df835d674fd12add70332fda9cd349a7423fa
Cr-Commit-Position: refs/heads/master@{#296017}