Add initial batch of descriptions (desc stanza)

[waldyrious]

Follow-up of #87301 and Homebrew/brew#8137.

I used the list of descriptions provided by @core-code here, and cleaned them up by:

• Removing entries that contained no information (e.g. The main <cask name> repository, <cask name> desktop app, etc.)

• Removing entries not in English:

  • eudic 是专为苹果系统开发的词典参考软件
  • youdaodict 选择有道词典，就是选择与5亿语言学习用户一起享受有道为您提供的周到服务。
  • bilimini 藏起来！哔哩哔哩
  • xiami 虾米音乐 发现音乐新世界
  • ximalaya 听书、听课、听段子，6亿用户的选择！
  • bob 端翻译软件，翻译方式支持划词翻译和截图翻译，翻译引擎支持有道翻译、百度翻译和谷歌翻译~
  • editaro エディ太郎
  • ieasemusic 网易云音乐第三方
  • imgotv 《乘风破浪的姐姐》三十而骊
  • kugoumusic 内容提要：
  • mailmaster 「网易邮箱大师」是网易官方出品的全平台邮箱客户端
  • majsoul-plus 雀魂majsoul专用PC浏览器，提供了一些专有特性
  • masterway-note # 大师笔记
  • mob Mob - 一个高颜值的喜马拉雅桌面客户端，支持 Mac、Win 和 Linux
  • wechatwork 内容提要\n企业微信，是腾讯微信团队为企业打造的高效办公平台
  • qqlive 【强大播放功能】支持mkv、rmvb、mp4、avi等常用视频格式 支持双指滑动手势操作，贴合使用习惯 支持倍速播放，快速浏览精彩内容 官方QQ号，任何反馈欢迎咨询
  • qiyimedia 爱奇艺mac客户端，简洁轻量的视频客户端
  • powerword 金山词霸
  • platelet けっしょうばん
  • moefe-google-translate Google 翻译 Mac 客户端

• Shortening long entries to conform to the 80-char limit (although most of them —about 230— were removed altogether, as it would be impractical to manually fix them all)

• Removing embellishing language (fast, smart, easy, easiest, simple, beautiful, powerful, modern, advanced...)

• Removing A/An and the cask names from the beginning of the descriptions

• Replacing action-centric descriptions (Does foo and bar) with declarative descriptions (Tool to do foo and bar)

• Removing instances of "your"

I also added descriptions to some casks not included in that list.

I'm opening this PR as a draft because the fixes mentioned above haven't been completed. I'd appreciate any help in identifying descriptions in need of such cleanup/improvements, since many of the edits mentioned above are manual tasks that rely on human judgment.

(Of course, we don't have to make all descriptions be perfect from the get-go; as a collaborative, evolving project, anything that we miss in this initial pass can be fixed in later PRs.)

[waldyrious]

For future reference → to integrate the descriptions from @core-code's file (whose syntax was name: description, one entry per line) into the cask files, I replaced the : separators with tabs, then used the following bash script:

#!/bin/bash

# read file with descs and parse it line by line,
# extracting the name and var into separate vars
while IFS=$'\t' read -r name desc
do
  # in the file named after the name var, find "homepage"
  # and prepend a line with the contents of the desc var
  perl -p -i -e "s/  homepage/  desc \"$desc\"\n  homepage/" "../Casks/$name.rb"
done < "descriptions.tsv"

Note that I first had to replace / with \/ in the descriptions, to avoid inadvertently passing regex flags in the Perl script.

I'll also point out that while this looks deceptively simple, it was the result of a lot of trial and error and trips to StackOverflow (which is why I thought it might be useful to list it here, as it is not trivial.)

[waldyrious]

For the record, I wasn't able to run the rubocop checks locally. I first tried in my local fork of this repo, which I had cloned independently of Homebrew, and realized that brew cask audit and brew cask style were instead using Homebrew's internal homebrew-cask repository in /usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask. (This however led me to notice existing audit failures related to the "CN" locale, whose fix I provisionally included as a commit in this PR)

I then went into Homebrew's internal homebrew-cask repo, added my fork as a remote and checked-out this branch, but then running brew cask style failed with a strange error, like this:

An error occurred while Cask/Desc cop was inspecting /usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/abstract.rb:1:0.
To see the complete backtrace run rubocop -d.
An error occurred while Cask/Desc cop was inspecting /usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/air-video-server-hd.rb:1:0.
To see the complete backtrace run rubocop -d.
An error occurred while Cask/Desc cop was inspecting /usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/aircall.rb:1:0.
To see the complete backtrace run rubocop -d.
An error occurred while Cask/Desc cop was inspecting /usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/airparrot.rb:1:0.
To see the complete backtrace run rubocop -d.
An error occurred while Cask/Desc cop was inspecting /usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/airunlock.rb:1:0.
To see the complete backtrace run rubocop -d.
...

That's why this PR will most likely fail the CI checks. I'll fix the style offenses locally once they are reported.

[core-code]

we actually have some guidelines for these descriptions, but it seems they were not met in about half the cases (often because they come this way from the vendor) ;(

a few offenders:

• some descriptions mention 'for mac/macOS/OS X' etc. i think this is not necessary, all of them are obviously for mac (there are rare exceptions here where it makes sense to mention this)
• some descriptions mention that this is 'an app that does xyz'. everyhing is an app(lication) so thats superfluous as well
• also some just start with the appname which isn't needed either (could be caught by rubocop).

name "Airpass"
   desc "Airpass - status bar Mac app to overcome time constrained WiFi networks"

[waldyrious]

@reitermarkus Four descriptions are failing the Description should start with a capital letter rule:

• beacon-scanner.rb: "iBeacon scanning utility app"
• iexplorer.rb: "iOS device backup software and file manager"
• imazing.rb: "iPhone management application"
• therm.rb: "iTerm2 fork that aims to have good defaults and minimum features"

Given that "macOS" is currently exempted from this rule, I'd assume that iOS and iPhone should too. What about the other two?

[reitermarkus]

The other two: Reword them.

[reitermarkus]

@waldyrious, can you rebase this? Homebrew/brew#8328 is finally merged now.

[waldyrious]

@reitermarkus Done! Btw, if you could, please take a look at the comment I left above.

[reitermarkus]

Many are mentioning “macOS” or similar still, should be detected once Homebrew/brew#8557 is merged.

[waldyrious]

Many are mentioning “macOS” or similar still, should be detected once Homebrew/brew#8557 is merged.

I've fixed some of these, and will continue working on the rest as time permits — but there are several instances that are legitimate, e.g.:

• aquamacs: Text editor based on GNU Emacs with the UI modified to suit macOS
• autodmg: App for creating deployable system images from a macOS installer
• crossover: Tool to run Windows software on macOS

How should these be handled?

[reitermarkus]

How should these be handled?

• Text editor based on GNU Emacs
• App for creating deployable system images from a system installer
• Tool to run Windows software

[reitermarkus]

@waldyrious, can you rebase this again?

Maybe open another pull request for those that are passing now so we can get those merged and review the remaining ones here.

[waldyrious]

Hey @reitermarkus — Thanks for checking in! I've been slowly chipping away at the remaining ones over the past few days. Progress has been slow, but I'll should be able to finish them up today, as I have some more time available.

[waldyrious]

@reitermarkus I believe with the last push I fixed the issues for all casks, except for hackintool:

Patching tool to install macOS on 'Hackintosh' computers

What would you suggest here?

[reitermarkus]

Hackintosh patching tool

[waldyrious]

Alright, should be ready now :)

[reitermarkus]

@Homebrew/cask, please skim over this if you have a minute.

@waldyrious, one last rebase and this should be good to go unless someone finds anything else that needs changing in the meantime.

[waldyrious]

@waldyrious, one last rebase and this should be good to go

Done! And no worries if further rebases are needed; the conflicts have been pretty easy to fix so far, and most of them have revealed improved versions of the descriptions that this PR initially added.

[core-code]

@Homebrew/cask, please skim over this if you have a minute.

one minute doesn't quite cut it at 1300 descriptions :)

basically it looks good. ideally there would be stricter guidelines how the descriptions should be worded. all we have to say is:

It should start with an uppercase letter, avoid including the Cask’s name, and have no more than 80 characters.

thats an awful lot of freedom. i think more recommendations would be better to enforce a common style.

we basically have 3 types of descriptions
• those that say what it is (e.g. "Dictionary conversion tool")
• those that say what it can do (e.g. "Opens RAW files and renders them on-the-fly")
• those that say what a user can do with it (e.g. "Visually compare and merge files")

at least the last two are interchangeable and could be reduced to one style for consistency.

there are still many many in there that mention that something is 'software' or 'an app'. i think this is superfluous.

but overall it looks fine as a start, i don't think there is much point in deferring this trying even to make the initial descriptions perfect. we can use them as a start and improve later.

some specific ones i've noticed.

"File share software"

shouldn't it be "file sharing"?

"Tool to help searching the web more efficiently"

shouldn't it be "tool to help search the ...."?

[reitermarkus]

we basically have 3 types of descriptions

Yeah, I think the common denominator would be the first style, i.e. the last two could be:

• Tool for rendering RAW files on-the-fly
• Visual compare and merge tool

I don't think we can easily enforce this, but an example in the documentation would certainly help not to deviate too far from this style.

[waldyrious]

Yeah, I think the common denominator would be the first style

I agree — a single style is more consistent and easier to review and to describe. I actually tried to make this change (away from action-oriented descriptions) to as many entries as I could in the course of working on this PR, but at some point I had to cave in and accept that this batch would contain some less than ideal descriptions as a starting point that the community can then improve upon.

By the way, other guidelines I'd suggest (as I mentioned in the opening comment of the PR) are avoiding references to "you"/"your", and avoiding promotional/embellishing language: "smart", "easy", "beautiful", "powerful", "modern", "advanced", etc. These could be easily enforced by maintaining a list of forbidden words (just like we don't allow "macOS" or "OS X" at the moment). But I'd say those adjustments should be part of a separate PR, otherwise this one will never get done :)

@core-code I'll make the "file share" → "file sharing" change you pointed out above; the other one is not necessarily incorrect, and indeed both forms feel acceptable to me, but I can change it too if you prefer.

[vitorgalvao]

enforce a common style.

Agreed.

I think the common denominator would be the first style

Disagreed only because it requires us to use the word “tool” every time. The third style looks better to me (so far, with limited examples).

avoiding references to "you"/"your"

Agreed.

and avoiding promotional/embellishing language: "smart", "easy", "beautiful", "powerful", "modern", "advanced", etc.

Agreed. In general, ban adjectives; descriptions should consist mostly of verbs and nouns: what the app does to what.

[waldyrious]

we basically have 3 types of descriptions
• those that say what it is (e.g. "Dictionary conversion tool")
• those that say what it can do (e.g. "Opens RAW files and renders them on-the-fly")
• those that say what a user can do with it (e.g. "Visually compare and merge files")

I think the common denominator would be the first style

Disagreed only because it requires us to use the word “tool” every time.

That's a good point. Ideally every program would belong to a known category (e.g. web browser, text editor, music player, etc.) but in practice many of these casks represent very specific needs that don't have a common name, so we are forced to use "tool", "app", "utility", "software", etc. In this light, it does seem that using the action-oriented descriptions has a better shot at providing a universal format without too much gymnastics to adhere to the preferred style.

[tjluoma]

Wow! What an undertaking. I counted 1415 casks that were updated as a result of this. Just wanted to say thank you for taking the time to do something like this which could go largely unnoticed, despite being a “quality of life” improvement for anyone who uses one of these.