feat: fields for VisibleFlags name/alias and Usage

[midischwarz12]

Checklist

• Are you running the latest v3 release? The list of releases is here.
• Did you check the manual for your release? The v3 manual is here.
• Did you perform a search about this feature? Here's the GitHub guide about searching.

What problem does this solve?

When customizing the AppHelpTemplate, it would be preferable to change how the first and second column are formatted, ie - the description of the flag on a separate line, tabbed out, and restricted to a width of 80 characters. In the current state of .VisiableFlags, there is no way to separate the two columns beyond a slice of strings. Each flag has its name and description (.Usage) clumped together as a single string which is difficult or nearly impossible to parse using go's template actions.

Solution description

The two columns should be exposed as separate fields.

For the first column, .Name does not truly suffice as it both contains the long Name, Aliases, and has the input values marked by the respective name or alias. A fitting name for this could be .Names or .Flags.

For the second column, something equivalent to .Usage is sufficient.

Describe alternatives you've considered

I've tried to loop through .VisiableFlags and coerce each flag to its original type such as StingFlag and then create a custom template to load which would effectively recreate the first column. But this served to be very tedious, and admittedly, I'm not good enough in golang to do this with ease.

I also thought of potentially hand writing this part of the help template. But this deemed tedious as well and goes against the spirit of urfave/cli as it does not autogenerate based on the visible flags.

[dearchap]

@midirhee12 you could cast the Flag to a DocGenerationFlag to extract further information if you'd like. Admittingly its not elegant but might work ?

[midischwarz12]

How would this be casted and used within the AppHelpTemplate?

[midischwarz12]

@dearchap From what I know, you would have to map the function into the template before being evaluated. Is there a way this is being exposed?

[midischwarz12]

Either way, even if it is possible, I think there should be a more straightforward and clean way to access this since formatting the templates could be quite frequent among users.

[midischwarz12]

@dearchap Actually, on second thought. Is it possible to expose .VisibleFlagTemplate and such instead?

[dearchap]

@midirhee12 yes. you want to make a PR ?

[IslamElsayed]

@dearchap I'd like to pick this up, but the thread ends on two different proposals and I want to build the one you said yes to rather than guess.

Reading it back, your "yes. you want to make a PR?" answers @midischwarz12's "Is it possible to expose .VisibleFlagTemplate and such instead?" — not the original ask for separate name/alias/usage fields. So I'd implement the exposure, not new fields. Please correct me if I have that backwards.

Why the current state blocks people. The top-level templates are exported and overridable — RootCommandHelpTemplate, CommandHelpTemplate, SubcommandHelpTemplate, FishCompletionTemplate. The pieces they compose from are not:

var visibleFlagTemplate = `{{range $i, $e := .VisibleFlags}}
   {{wrap $e.String 6}}{{end}}`

So someone can restructure the help layout wholesale, but cannot change how the flag list itself renders, because that {{wrap $e.String 6}} lives in an unexported var they can neither override nor reference. That is the actual wall, and it explains why the workaround you suggested didn't land — there is nowhere to put it.

Why exposure alone may be the whole fix. text/template resolves methods against the dynamic value, not the static one. So inside {{range .VisibleFlags}}, even though the element's static type is Flag, a user-supplied template can call {{$e.GetUsage}} and {{$e.Names}} directly, since the built-in flags implement DocGenerationFlag. If that holds, this needs no new interface method, no funcMap helper and no wrapper type — just exporting the vars. I'd pin it with a test rather than assert it, since a flag type that doesn't implement DocGenerationFlag would fail at execution time instead of compile time, and that failure mode is worth a documented note either way.

Three questions before I write anything:

1. Which vars? Just the flag-related three — visibleFlagTemplate, visiblePersistentFlagTemplate, visibleFlagCategoryTemplate — or the whole set including visibleCommandTemplate, visibleCommandCategoryTemplate, versionTemplate and copyrightTemplate? Exporting all seven is more consistent; exporting three keeps the new surface to what was actually asked for. I lean to the three.
2. Rename or alias? Export by renaming outright, or add exported vars and keep the unexported ones as internal references? The former is cleaner, the latter avoids touching call sites.
3. Does this want make v3approve for the godoc surface diff, and is adding exported vars acceptable mid-v3, or does it need to wait for a version boundary? That is the part most likely to make this a no, so I'd rather hear it now.

@midischwarz12 you were the one asked to open the PR — are you still planning to? Happy to leave it with you if so.

Disclosure: I use AI assistance when working on patches, and I check and test everything before submitting.