fmt: docs slightly disorganized and slightly contradictory

[seebs]

Please answer these questions before submitting your issue. Thanks!

What version of Go are you using (go version)?

1.11

Does this issue reproduce with the latest release?

yes

What operating system and processor architecture are you using (go env)?

N/A

What did you do?

Read the fmt docs. Someone in IRC asked about padding, and I went and looked, and thought "that seems slightly inaccurate", then reread it and thought "wait that can't be right, can it?" and eventually concluded that things were confusing.

What did you expect to see?

Something I could follow without much effort.

What did you see instead?

A confusing tangle. Width and explicit argument indexes are both "immediately preceeding the verb", but actually width won't immediately preceed the verb if precision is present, or an explicit argument index for that matter. I know what width and precision are because I'm used to C, but some kind of vague conceptual introduction might be nice. Explicit argument indexes are described separately from every other aspect of the formatting verbs, after an unrelated tangle of things.

Before filing this, I decided to see if I could write something I thought was better. After some effort, I'm pleased to state that I have no idea but I have at least made an effort, so I should have a change submitted for code review "soon". (I think it's justified just by getting the explicit argument indexes moved in with the rest of the stuff.)

[ianlancetaylor]

CC @robpike

[gopherbot]

Change https://golang.org/cl/146024 mentions this issue: fmt: Clean up and slightly restructure Printf docs