code review 4257049: doc: describe platform-specific conventions in code.html

doc: describe platform-specific conventions in code.html

[adg, 2011-03-02 06:14:18]

Hello r, rsc (cc: golang-dev@googlegroups.com),

I'd like you to review this change to
https://go.googlecode.com/hg/

[r, 2011-03-02 06:52:54]

http://codereview.appspot.com/4257049/diff/1/doc/code.html
File doc/code.html (right):

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode326
doc/code.html:326: <h2 id="Arch_dependent">Platform-specific code</h2>
is it an arch or a plat?
i prefer arch. see below

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode329
doc/code.html:329: platform they run on. In the vast majority of cases the Go
standard library
can we avoid jargon such platform? i'm not even sure what it means; it's such a
slippery term

the hardware and operating system

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode330
doc/code.html:330: should accommodate any portability concerns. This section is
a guide for
accommodate is the wrong word

The language and standard library handle most portability issues.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode332
doc/code.html:332: platform-specific code.</p>
platform is ok here if you don't use it above

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode334
doc/code.html:334: <p>To write specific code for different operating systems and
architectures,
s/architectures/instruction sets/?

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode337
doc/code.html:337: variables</a> to include the code relevant to each
combination.</p>
rephrase to the active voice.

s/you can.../use the XXX in your Makefile rules to build the package/
or something like that

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode340
doc/code.html:340: operating systems, you could use a <code>Makefile</code> like
this:</p>
a lot of "you" here. just the facts, ma'am.

For example, this Makefile describes a package that builds different code on
different operating systems by parameterizing the file name with $GOOS.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode353
doc/code.html:353: <p>And then put your generic source code in
<code>my.go</code>, and OS-specific
OS-specific code goes in my_linux.go, my_darwin.go, and so on.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode356
doc/code.html:356: <p>Valid file name forms are:</p>
d

If you follow these conventional parameterizations, tools such as goinstall will
work seamlessly with your package:

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode364
doc/code.html:364: <p>(And the same holds for <code>.s</code> (assembly) and
<code>.cgo</code>
drop the parens, drop the And

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode367
doc/code.html:367: <!-- TODO: mention that goinstall observes these conventions,
when it does. -->
d

[r, 2011-03-02 06:55:39]

http://codereview.appspot.com/4257049/diff/1/doc/code.html
File doc/code.html (right):

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode334
doc/code.html:334: <p>To write specific code for different operating systems and
architectures,
maybe say

such as assembly-language support for fast trigonometric functions or
code that implements a common interface above distinct operating systems....

but with all that you'll want to remove the infinitive and rephrase

[adg, 2011-03-03 01:54:04]

http://codereview.appspot.com/4257049/diff/1/doc/code.html
File doc/code.html (right):

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode326
doc/code.html:326: <h2 id="Arch_dependent">Platform-specific code</h2>
On 2011/03/02 06:52:54, r wrote:
> is it an arch or a plat?
> i prefer arch. see below

I went with "Architecure and operating system-specific code" but I'll take
suggestions as to a better title.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode329
doc/code.html:329: platform they run on. In the vast majority of cases the Go
standard library
On 2011/03/02 06:52:54, r wrote:
> can we avoid jargon such platform? i'm not even sure what it means; it's such
a
> slippery term
> 
> the hardware and operating system

Done.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode330
doc/code.html:330: should accommodate any portability concerns. This section is
a guide for
On 2011/03/02 06:52:54, r wrote:
> accommodate is the wrong word
> 
> The language and standard library handle most portability issues.

Done.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode332
doc/code.html:332: platform-specific code.</p>
On 2011/03/02 06:52:54, r wrote:
> platform is ok here if you don't use it above

Done.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode334
doc/code.html:334: <p>To write specific code for different operating systems and
architectures,
On 2011/03/02 06:55:39, r wrote:
> maybe say
> 
> such as assembly-language support for fast trigonometric functions or
> code that implements a common interface above distinct operating systems....
> 
> but with all that you'll want to remove the infinitive and rephrase

I put this in the paragraph above, makes more sense there IMO.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode337
doc/code.html:337: variables</a> to include the code relevant to each
combination.</p>
On 2011/03/02 06:52:54, r wrote:
> rephrase to the active voice.
> 
> s/you can.../use the XXX in your Makefile rules to build the package/
> or something like that

Done.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode340
doc/code.html:340: operating systems, you could use a <code>Makefile</code> like
this:</p>
On 2011/03/02 06:52:54, r wrote:
> a lot of "you" here. just the facts, ma'am.
> 
> For example, this Makefile describes a package that builds different code on
> different operating systems by parameterizing the file name with $GOOS.

Done.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode353
doc/code.html:353: <p>And then put your generic source code in
<code>my.go</code>, and OS-specific
On 2011/03/02 06:52:54, r wrote:
> OS-specific code goes in my_linux.go, my_darwin.go, and so on.

Done.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode356
doc/code.html:356: <p>Valid file name forms are:</p>
On 2011/03/02 06:52:54, r wrote:
> d
> 
> If you follow these conventional parameterizations, tools such as goinstall
will
> work seamlessly with your package:

Done.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode364
doc/code.html:364: <p>(And the same holds for <code>.s</code> (assembly) and
<code>.cgo</code>
On 2011/03/02 06:52:54, r wrote:
> drop the parens, drop the And

Done.

http://codereview.appspot.com/4257049/diff/1/doc/code.html#newcode367
doc/code.html:367: <!-- TODO: mention that goinstall observes these conventions,
when it does. -->
On 2011/03/02 06:52:54, r wrote:
> d

Done.

[r, 2011-03-03 01:57:51]

http://codereview.appspot.com/4257049/diff/5001/doc/code.html
File doc/code.html (right):

http://codereview.appspot.com/4257049/diff/5001/doc/code.html#newcode326
doc/code.html:326: <h2 id="arch_os_specific">Architecure and operating
system-specific code</h2>
s/Architecture/Architecture-/ (two mistakes in there)

http://codereview.appspot.com/4257049/diff/5001/doc/code.html#newcode334
doc/code.html:334: distinct operating systems.
maybe s/distinct/different/

http://codereview.appspot.com/4257049/diff/5001/doc/code.html#newcode336
doc/code.html:336: <p>To write specific code for different operating systems and
instruction sets,
To compile such code, use the GOOS and GOARCH environment variables in your file
names and Makefile.

[adg, 2011-03-03 02:13:47]

http://codereview.appspot.com/4257049/diff/5001/doc/code.html
File doc/code.html (right):

http://codereview.appspot.com/4257049/diff/5001/doc/code.html#newcode326
doc/code.html:326: <h2 id="arch_os_specific">Architecure and operating
system-specific code</h2>
On 2011/03/03 01:57:51, r wrote:
> s/Architecture/Architecture-/ (two mistakes in there)

Done.

http://codereview.appspot.com/4257049/diff/5001/doc/code.html#newcode334
doc/code.html:334: distinct operating systems.
On 2011/03/03 01:57:51, r wrote:
> maybe s/distinct/different/

Done.

http://codereview.appspot.com/4257049/diff/5001/doc/code.html#newcode336
doc/code.html:336: <p>To write specific code for different operating systems and
instruction sets,
On 2011/03/03 01:57:51, r wrote:
> To compile such code, use the GOOS and GOARCH environment variables in your
file
> names and Makefile.

Done.

[r, 2011-03-03 02:19:15]

http://codereview.appspot.com/4257049/diff/4/doc/code.html
File doc/code.html (right):

http://codereview.appspot.com/4257049/diff/4/doc/code.html#newcode338
doc/code.html:338: <code>Makefile</code>.</p>
you missed my point that you need to use them in the file names too

you can find a nice way to say that

[adg, 2011-03-03 02:58:16]

Hello r, rsc (cc: golang-dev@googlegroups.com),

Please take another look.

[r, 2011-03-03 23:08:25]

LGTM

[gri, 2011-03-03 23:22:42]

FYI

http://codereview.appspot.com/4257049/diff/12001/doc/code.html
File doc/code.html (right):

http://codereview.appspot.com/4257049/diff/12001/doc/code.html#newcode334
doc/code.html:334: different operating systems.
missing </p>

[adg, 2011-03-04 01:28:18]

*** Submitted as http://code.google.com/p/go/source/detail?r=d59fca3fc930 ***

doc: describe platform-specific conventions in code.html

R=r, rsc, gri
CC=golang-dev
http://codereview.appspot.com/4257049

http://codereview.appspot.com/4257049/diff/12001/doc/code.html
File doc/code.html (right):

http://codereview.appspot.com/4257049/diff/12001/doc/code.html#newcode334
doc/code.html:334: different operating systems.
On 2011/03/03 23:22:42, gri wrote:
> missing </p>

Done.