code review 5782043: doc: various update to command documents

doc: various update to command documents
        1. consistent usage section (go tool xxx)
        2. reformat cmd/ld document with minor correction
           document which -H flags are valid on which ld
           document -d flag can't be used on Windows.
           document -Hwindowsgui

[minux1, 2012-03-07 20:51:32]

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

I'd like you to review this change to
https://code.google.com/p/go/

[r, 2012-03-08 01:48:41]

http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go
File src/cmd/ld/doc.go (right):

http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode12
src/cmd/ld/doc.go:12: architecture (5.out, 6.out, 8.out) by default (if $GOOS is
windows, .exe suffix
s/.exe./a .exe/

i assume the claim is true

http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode23
src/cmd/ld/doc.go:23: Substitute 6l with 8l or 5l where appropriate.
s/where/as/

http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode29
src/cmd/ld/doc.go:29: is statically linked and does not refer to dynamic linker.
 Without this option
s/dynamic linker/a dynamic linker/

http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode30
src/cmd/ld/doc.go:30: (the default), the binary's contents are identical but it
is loaded with dynamic
ditto

http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode31
src/cmd/ld/doc.go:31: linker. This flag can't not be used when $GOOS is windows.
s/can't not/cannot/

http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode46
src/cmd/ld/doc.go:46: but it might change it meaning to Windows GUI PE binary)
s/it/its/

what does "might change its meaning" mean? are there plans to do this?
probably better to drop the (...) and just document what it does, not what it
might do later.

[minux1, 2012-03-08 13:40:46]

PTAL.
On 2012/03/08 01:48:41, r wrote:
http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode12
> src/cmd/ld/doc.go:12: architecture (5.out, 6.out, 8.out) by default (if $GOOS
is
> windows, .exe suffix
> s/.exe./a .exe/
Done.
> i assume the claim is true
http://tip.golang.org/src/cmd/8l/obj.c#L158
http://tip.golang.org/src/cmd/6l/obj.c#L153

> http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode23
> src/cmd/ld/doc.go:23: Substitute 6l with 8l or 5l where appropriate.
> s/where/as/
Done.

> http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode29
> src/cmd/ld/doc.go:29: is statically linked and does not refer to dynamic
linker.
>  Without this option
> s/dynamic linker/a dynamic linker/
> 
> http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode30
> src/cmd/ld/doc.go:30: (the default), the binary's contents are identical but
it
> is loaded with dynamic
> ditto
Both done.
 
> http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode31
> src/cmd/ld/doc.go:31: linker. This flag can't not be used when $GOOS is
windows.
> s/can't not/cannot/
Done.

> http://codereview.appspot.com/5782043/diff/1001/src/cmd/ld/doc.go#newcode46
> src/cmd/ld/doc.go:46: but it might change it meaning to Windows GUI PE binary)
> s/it/its/
> 
> what does "might change its meaning" mean? are there plans to do this?
> probably better to drop the (...) and just document what it does, not what it
> might do later.
I dropped the sentence in parentheses. I used to assume -Hwindowsgui measn GUI
mode
windows app, and -Hwindows means Console mode windows app, but to my surprise
the
former is only an alias of the latter; so I thought this might change in the
future.

[rsc, 2012-03-08 15:27:19]

On Thu, Mar 8, 2012 at 08:40,  <minux.ma@gmail.com> wrote:
> I dropped the sentence in parentheses. I used to assume -Hwindowsgui
> measn GUI mode
> windows app, and -Hwindows means Console mode windows app, but to my
> surprise the
> former is only an alias of the latter; so I thought this might change in
> the future.

They are different today.  The check is in ld/pe.c

	if(strcmp(headstring, "windowsgui") == 0)
		set(Subsystem, IMAGE_SUBSYSTEM_WINDOWS_GUI);
	else
		set(Subsystem, IMAGE_SUBSYSTEM_WINDOWS_CUI);

[minux1, 2012-03-08 16:48:26]

PTAL.
On 2012/03/08 15:27:19, rsc wrote:
> On Thu, Mar 8, 2012 at 08:40,  <mailto:minux.ma@gmail.com> wrote:
> > I dropped the sentence in parentheses. I used to assume -Hwindowsgui
> > measn GUI mode
> > windows app, and -Hwindows means Console mode windows app, but to my
> > surprise the
> > former is only an alias of the latter; so I thought this might change in
> > the future.
> 
> They are different today.  The check is in ld/pe.c
> 
> 	if(strcmp(headstring, "windowsgui") == 0)
> 		set(Subsystem, IMAGE_SUBSYSTEM_WINDOWS_GUI);
> 	else
> 		set(Subsystem, IMAGE_SUBSYSTEM_WINDOWS_CUI);
Oh, great, then. Updated the corresponding document.

[rsc, 2012-03-08 17:01:05]

LGTM

[minux1, 2012-03-08 17:31:25]

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

doc: various update to command documents
        1. consistent usage section (go tool xxx)
        2. reformat cmd/ld document with minor correction
           document which -H flags are valid on which ld
           document -d flag can't be used on Windows.
           document -Hwindowsgui

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