Proposal: add desc stanza

[brandonkal]

Description of feature/enhancement

Just like normal brew formulas have a description, casks should also accept a description.

This is not a request that all existing casks include a description, as that would require time. Rather, it is a request that The desc stanza will work as expected.

Would you accept a PR that adds this capability?

Justification

brew bundle dump can include descriptions in the generated Brewfile. This is quite useful when sharing a list of installed applications between multiple machines and people. Unfortunately, that only works for formula, which makes up 25% of my Brewfile. Adding descriptive comments manually is of course possible, but impractical.

[vitorgalvao]

This has been discussed in the past. At the time we decided against it for being impractical, but today it seems feasible.

My suggestion to go through with it would be to add the desc stanza as an alias to name and slowly add it to casks. If it ever reaches sufficient adoption, we get rid of name; if it doesn’t, we get rid of desc. search already considers the contents of name anyway—though we may which to only make that work behind a flag, like the formulae search works—so it’s great as a drop-in replacement.

Pinging @Homebrew/cask.

[reitermarkus]

I'm on board with that. I think a description is much more useful than a name, given that the name in most cases is only a capitalised token with spaces included.

[ran-dall]

LGTM

[vitorgalvao]

Seems like there’s no opposition to the idea. Are you still interested in working on a PR for this, @brandonkal? Let’s start slow.

[brandonkal]

I don't have the cycles to work on this right now or much familiarity with ruby outside of writing vagrant scripts and formula so it is probably best someone else takes this on.

If there is something I could do in a few months when I have time available I'd be open to it.

[vitorgalvao]

I don't have (…) much familiarity with ruby

I thought you could do it, considering you said above:

Would you accept a PR that adds this capability?

In that case, I doubt this will happen any time soon, as it’s incredibly low priority.

[waldyrious]

@vitorgalvao I'd like to work on this, but I'm confused by your earlier comment above — why should desc eventually replace name (if it gets sufficient adoption)? I would expect both to be present, providing different content. For example, for the fontforge.rb cask, I'd expect the new contents would become something like this:

   name 'FontForge'
+  desc 'Font editor and converter for outline and bitmap fonts'
   homepage 'https://fontforge.github.io/en-US/'

Was your point that the cask title/filename duplicates the name stanza? That indeed seems to be mostly the case for simple names, but fails for casks with spaces or even punctuation (e.g. "0-ad" vs "0 A.D."). Or am I missing something?

[vitorgalvao]

@waldyrious You make some good points. Let’s get desc done first and decide later if name remains or goes, it’s not something we need to decide now.

[waldyrious]

Great! Can you point me towards where I should start the work to implement this?

[vitorgalvao]

Great! Can you point me towards where I should start the work to implement this?

Ping @reitermarkus.

[reitermarkus]

@waldyrious, name is implemented here: https://github.com/Homebrew/brew/blob/master/Library/Homebrew/cask/dsl.rb#L89-L94

[waldyrious]

@reitermarkus thanks for the pointer, but I'm afraid I'll need a bit more context. Can you outline, in broad strokes, the changes that would need to be done? I suspect even a barebones implementation will not merely a matter of adding a similar block in that file, just replacing name with desc.

I suppose I also need to (at least):

• add an entry to the DSL_METHODS methods set in cask/dsl.rb
• add an entry to this group in rubocops/cask/constants/stanza.rb.
• add an entry to the list in cask/cask.rb
• update the template in cask/cmd/create.rb to include the desc stanza

The tests would also need to be updated:

• add a new block similar to this one for the name stanza in test/cask/dsl_spec.rb (or possibly a simpler one, similar to the ones for the url or the homepage stanzas?)
• update the test for cask/cmd/create.rb to match the change in the source

One would also need to update the documentation in this repo:

• add a new doc/cask_language_reference/stanzas/desc.md file similar to name.md;
• add a new entry to the list at doc/cask_language_reference/readme.md#stanza-order, and possibly also include it in the example in the first section;
• add a new entry to doc/cask_language_reference/all_stanzas.md

...and likely other changes that I'm missing in this list. I'd appreciate any guidance regarding the changes that need to be done. (Feel free to edit this comment to add, edit or remove items from the list in case it is useful as a starting point.)

[reitermarkus]

@waldyrious, for the stanza order, the stanza will also have to be added to the RuboCop rule.

Other than that I think you have pretty much everything covered.

[waldyrious]

@waldyrious, for the stanza order, the stanza will also have to be added to the RuboCop rule.

@reitermarkus it seems to me that the correct order is already derived automatically, according to

https://github.com/Homebrew/brew/blob/2b33f995f371d0a4dc534c8f800954e6a8425b28/Library/Homebrew/rubocops/cask/stanza_order.rb#L24

and

https://github.com/Homebrew/brew/blob/2b33f995f371d0a4dc534c8f800954e6a8425b28/Library/Homebrew/rubocops/cask/ast/cask_block.rb#L29-L39

So as far as I can tell, it looks like we don't need to change anything for the order (and grouping) of the new stanza to be tested. Am I perhaps missing something?