New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
x/tools/go/buildutil: split TagsFlagDoc into multiple lines? #23464
Comments
Yes, but that's harder to read since there is no indentation. The end of that long line and the start of the next flag can be confused as one single paragraph. That's a good point that I didn't mention, though. |
Splitting the help string into multiple lines is more viable in Go 1.10, given that https://tip.golang.org/doc/go1.10#flag was done:
(Discovered via https://speakerdeck.com/campoy/the-state-of-go-1-dot-10?slide=23. /cc @campoy FYI.) |
Yes - I saw Francesc's slides too, and the same thing came to mind. I forgot to follow up on this issue, though :) Since the x repos tend to support the latest 2 Go releases, I think it would be okay to add the newlines once 1.10 is out. Those building with 1.9 and using that help string will get output that is slightly off, but I think that is okay. The other option is waiting until 1.11 is out. I'm fine either way. |
ping @alandonovan for decision |
If this problem really needs to be solved, its solution belongs in the flag package, not in every flag docstring, since the author of the flag docstring cannot know how long to make each line as this depends on the indentation applied by the flag package. |
But the @rsc's decision in #20799 (which led to the Go 1.10
The indentation applied by the flag package is fixed and predictable. Since the docstrings are meant to be used with flag package, it's not completely unreasonable for their authors to know about the flag package's indentation. I don't mean it's the best solution, but it is viable. Both of the approaches are. |
On 27 March 2018 at 23:51, Dmitri Shuralyov ***@***.***> wrote:
But the flag package can't reliably do wrapping with indentation either,
not without knowing the width of the terminal where its output is being
shown. Is that possible?
@rsc <https://github.com/rsc>'s decision in #20799
<#20799> (which led to the Go 1.10 flag
change 0828ec1
<0828ec1>,
described at https://golang.org/doc/go1.10#flag) seemed to suggest that
it's ok for the docstring to be split into multiple lines.
Logf does something much simpler: it inserts a number of tabs after each
newline, so that on an infinitely wide terminal, multiline comments indent
nicely. It does not attempt to solve the problem of automatic line
wrapping, which, as you point out, depends on the width of the terminal.
(Under Bazel-like build systems, tests may be executed remotely in a
neutral environment, and their results are sent back to the user's machine,
so the width of the user's terminal, if it exists at all, cannot be an
input to testing.Logf.)
Changing flag to resemble Logf seems fine. Making either guess the
terminal width does not.
|
Oh, but that’s already done. That’s exactly the 1.10 flag change I mentioned above. Sorry if I’ve caused any confusion. I think the decision Steve asked for is whether to wait until 1.11 before splitting |
What version of Go are you using (
go version
)?Does this issue reproduce with the latest release?
Yes.
What did you do?
Add a
-tags
flag to a static analysis tool of mine:Then run
mytool -h
.What did you expect to see?
The long flag usage line to be split in multiple lines somehow.
What did you see instead?
I initially thought that changing the string constant would be enough, for example by adding
"\n\t"
twice to split the one log line into three lines.However, the
flag
package is not consistent about placing the usage line, so I am not sure if that is enough:So perhaps this should be a proposal to add special handling of long flag usage texts in the
flag
package, to wrap them around a certain around of columns. But I imagine that such a feature wouldn't be welcome, as the package is meant to be simple, and one has multiple workarounds available like using shorter texts, using a customUsage
func, or using a third-party flag package.Still, it seems to me like this is a problem with either
buildutil
orflag
./cc @alandonovan @shurcooL
The text was updated successfully, but these errors were encountered: