[question] Should we highlight email?

[Freed-Wu]

In many programs' --help, the last line is Report bugs to <email>. e.g.:

❯ man --help|rg 'Report bugs'
Report bugs to [email protected].
❯ help2man --help|rg 'Report bugs'
Report bugs to <[email protected]>.
❯ latexmk --help|rg 'Report bugs'
Report bugs etc to John Collins <jcc8 at psu.edu>.

This is the requirements of help2man, i.e., if a program's --help have ^Report bugs, help2man can use its --help to generate a man automatically.

So should we highlight the email or the username even URL? I think when user want to find the email to report a bug, the highlighted email and username can be found more easily.

Thanks.

[victor-gp]

Good point!

In particular, I'd agree to scope: [email protected], <[email protected]>, <jcc8 at psu.edu>.

I believe the last one is what you mean by "the username even", right?

I'd scope all of this with the same color:

• the username csjwatson
• the @ character
• the domain debian.org
• the angle quotes < & > in the last 2 examples
• the at in the last example too
• maybe not the whitespace around at
  • but it'd be tricky to get that right, I have yet to find a way to do so for other similar patterns
  • scoping the whitespace is good enough for a first implementation, and can remain like that for all I care

Similar to how we do option dashes -- like the rest of the option name, or the angle quotes in option arguments. All of these elements are part of one token, the email address.

(I'll follow-up with a comment on implementation concerns + roadmap later.)

[victor-gp]

Implementation concerns:

• Let's only parse this at beginning of line
• I guess it should only be at indent-0 if we trust the help2man requirements
  • But I'm not opposed to having it at indent-1-2. Not confident about indent-3-8 though.
• Let's call the context that checks this report-bugs and let's match "Report bugs" to commit to an inner context.
  • The inner context parses the tail looking for an email address string.
• I think it's ok to add all 3 help messages to the tests body. We can always summarize them if tests run slow.

Roadmap: ~~one of the big tasks I have pending is an overhaul of the scopes (=> colors) to:~~ scope names have been finalized, see this comment below, you can skip the rest of this comment.

• improve how the syntax looks on the default Monokai theme
  • i.e.: colorize headings and arguments with a different color
  • (we should definitely optimize/overfit for the out-of-the-box UX)
• see if we can make other themes look better when they currently don't
  • e.g.: gruvbox, ansi
  • ideally without losing support for current themes, but no holds barred aside from Monokai and a few that I fancy

That overhaul is going to affect the set of scopes (& colors) that are open for this new class. So I'd rather do this later.

A perfectly valid outcome is this gets scoped the same as a pre-existing class.

Prime candidate: filenames. There are not many in help messages, not that we scope at least. So the intersection with commands that have a report-bugs email should be pretty narrow.~~

[victor-gp]

I'm tagging this as "good first issue" with a change in scope.

Whoever does this, don't mind about the scope name you use for it. You only need to choose one that will be assigned a color by the default Monokai theme (the one used in tests).

After the detection logic for this is sound (and it shouldn't be too hard), we'll worry about assigning it a scope that plays well with the rest of the syntax.

[victor-gp]

Btw, scope names have been finalized.

Whoever tackles this, please add the following scope names variable, and reference it within the new report-bugs context:

scope_variables:
  ...
  - &MAILTO_SCOPES
    constant.character.escape.mailto.cmd-help
    variable.parameter.mailto.cmd-help
    meta.function.block.start.handlebars.mailto.cmd-help