Skip to content
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

Add word-wrap support, with wrap length provided by the user #1119

Merged
merged 1 commit into from Jun 18, 2022

Conversation

mostynb
Copy link
Contributor

@mostynb mostynb commented Apr 28, 2020

What type of PR is this?

  • feature

What this PR does / why we need it:

The help text is difficult to read when the lines are long. This patch attempts to wrap long lines, if the user provides a terminal width to wrap at.

Which issue(s) this PR fixes:

Updated version of #1044.

Refers to #287.

Testing

Added a unit test (which can be expanded).

Release Notes

The help text is now wrapped to fit the terminal window.

@mostynb mostynb requested a review from a team as a code owner April 28, 2020 06:46
@mostynb mostynb requested review from coilysiren and asahasrabuddhe and removed request for a team April 28, 2020 06:46
@mostynb mostynb changed the title Add word-wrap support based on terminal size (updated) WiP: Add word-wrap support based on terminal size (updated) Apr 29, 2020
internal/build/build.go Outdated Show resolved Hide resolved
termwidth_misc.go Outdated Show resolved Hide resolved
@mostynb mostynb changed the title WiP: Add word-wrap support based on terminal size (updated) Add word-wrap support, with wrap length provided by the user May 9, 2020
@mostynb
Copy link
Contributor Author

mostynb commented May 9, 2020

How does this look?

  • Is it OK to add a new field to helpPrinter?
  • The template probably needs tweaking to support wrapping more fields, but I don't know offhand which other fields to test.
  • This makes no attempt to break long words.

@coilysiren coilysiren self-requested a review May 13, 2020 21:59
go.mod Outdated Show resolved Hide resolved
@coilysiren
Copy link
Member

I see you just force pushed, so I'm not sure what changed? Can you re-request my review when this is ready for eyes again, and please not force push until after the PR is ready to merge?

@mostynb
Copy link
Contributor Author

mostynb commented May 19, 2020

I see you just force pushed, so I'm not sure what changed? Can you re-request my review when this is ready for eyes again, and please not force push until after the PR is ready to merge?

Sorry about that- I squashed the commit in an attempt to make it easy to verify that no new modules were added.

I have re-pushed the branch with the original commit followed by a fixup that removes the newly added module.

@mostynb mostynb requested a review from coilysiren May 19, 2020 17:38
@coilysiren
Copy link
Member

I'll try to give this a look soon!

@ericmillin
Copy link

@lynncyrin Would love to see this merged.

@coilysiren
Copy link
Member

Oops 😄

Copy link
Member

@coilysiren coilysiren left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have 1 blocking question, since I'm not following the template.go changes @mostynb

template.go Outdated Show resolved Hide resolved
@mostynb mostynb requested a review from coilysiren July 29, 2020 22:09
@xordspar0
Copy link
Contributor

Is this ready to be merged?

@mostynb
Copy link
Contributor Author

mostynb commented Oct 9, 2020

Is this ready to be merged?

It's stalled, waiting for review.

rliebz
rliebz previously requested changes Oct 22, 2020
help.go Outdated Show resolved Hide resolved
Copy link
Member

@rliebz rliebz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the contribution!

This is a sweet feature, just had a few minor comments.

help.go Outdated Show resolved Hide resolved
help.go Outdated Show resolved Hide resolved
@@ -4,16 +4,16 @@ package cli
// cli.go uses text/template to render templates. You can
// render custom help text by setting this variable.
var AppHelpTemplate = `NAME:
{{.Name}}{{if .Usage}} - {{.Usage}}{{end}}
{{$v := offset .Name 6}}{{wrap .Name 3}}{{if .Usage}} - {{wrap .Usage $v}}{{end}}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like we're wrapping most of the fields in the template, but not all of the fields. This PR also omits wrapping for command help and sub-command help.

Is there a reason NOT to expand wrapping to all sections of all templates?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mostly because I don't know all the variations that need to be tested. I suspect there will be some fields that aren't worth trying to wrap because they're only a problem in unusual cases, but command and sub-command help are worth supporting.

I will try to expand this a bit.

template.go Outdated Show resolved Hide resolved
help.go Show resolved Hide resolved
@mostynb
Copy link
Contributor Author

mostynb commented Nov 7, 2020

I was looking into the conflicting files, and noticed that #1175 has landed, which implements a subset of the feature here.

I locally tested a squashed version of this with two fixes appended, which makes TestWrappedHelp also test user specifed indenting, and another change which makes Test_ShowAppHelp_MultiLineDescription on master pass if I revert the code changes from be9c037 and then apply this PR.

How should we proceed?

@meatballhat meatballhat added the status/conflicts contains merge conflicts label May 8, 2022
@meatballhat
Copy link
Member

@mostynb Are you up for resolving the conflicts and moving this work forward? No worries if not. I'm happy to pick it up ❤️

@mostynb
Copy link
Contributor Author

mostynb commented May 22, 2022

I'll take a look and let you know if I run into trouble.

@mostynb mostynb force-pushed the word_wrap_v2 branch 3 times, most recently from d193e40 to 5dcce36 Compare May 22, 2022 19:39
@mostynb
Copy link
Contributor Author

mostynb commented May 22, 2022

@meatballhat: the failing test also fails for me locally on the tip of main. The CI failure is also visible in this typo fix PR: #1402

@meatballhat
Copy link
Member

@mostynb this looks like the problem of the docs tests running against latest release instead of current working tree 😩

bumping the priority of that work now...

@meatballhat
Copy link
Member

@mostynb Attempted fix for the test-docs step at #1403

We could try to automatically detect the terminal width and wrap at that
point, but this would increase the binary footprint for all users even
if not using this feature.

Instead, we can allow users to specify their preferred line length limit
(if any), and those who want to bear the cost of checking the terminal
size can do so if they wish. This also makes the feature more testable.

Original patch by Sascha Grunert <sgrunert@suse.com>
@mostynb
Copy link
Contributor Author

mostynb commented May 23, 2022

@meatballhat: CI is green after rebasing on main.

"offset": offset,
}

if customFuncs["wrapAt"] != nil {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is better to define a type for this function signature.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not quite sure what you mean- are you suggesting that we export a WrapAtFunc type alias, and then only use customFuncs["wrapAt"] if it is created as a WrapAtFunc explicitly?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gentle ping on this :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes correct

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This requires some boilerplate for the caller, but I'm not sure how it makes things better. How does this help? I couldn't find any examples of this pattern in a quick web search, but I'm not sure what to call this so maybe I'm missing something obvious.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fwiw I'm happy to defer resolution of this to a later PR, so I'm going to move forward with merging the current work 👍🏼

@mostynb mostynb removed the status/conflicts contains merge conflicts label May 30, 2022
@meatballhat meatballhat dismissed stale reviews from rliebz and coilysiren June 18, 2022 14:13

Defer to later 👍

@meatballhat meatballhat merged commit e576ba4 into urfave:main Jun 18, 2022
@mostynb mostynb deleted the word_wrap_v2 branch June 18, 2022 14:18
@tonglil
Copy link

tonglil commented Sep 3, 2022

Is there any docs for this?

@mostynb
Copy link
Contributor Author

mostynb commented Sep 3, 2022

Is there any docs for this?

Perhaps it could be more discoverable, but you need to set HelpPrinterCustom or HelpPrinter to add a wrapAt function to the funcMap. eg:
https://github.com/urfave/cli/pull/1119/files#diff-4d3f36d62cad94424544bb84fc93b33b73ffe3491a4ddca81a7f825539afc19cR1161-R1169

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/v2 relates to / is being considered for v2 kind/feature describes a code enhancement / feature request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

9 participants