following up on #3094
- rename `THE_CASK_LANGUAGE.md` to `CASK_LANGUAGE_REFERENCE.md`
- expand `CASK_LANGUAGE_REFERENCE.md` to more fully specify the Cask DSL
- add sections: "Casks Are Ruby Classes" and "The Cask Language Is Declarative"
- import content from `FAQ.md` to `CASK_LANGUAGE_REFERENCE.md`, create multiple sections
listing all stanzas according to category.
- document which stanzas are permitted multiple times
- add previously undocumented `before_install` and `before_uninstall`
- doc that `Hardware::CPU.is_64_bit?` (and 32-bit) are acceptable in conditionals
- doc that `:target` may contain an absolute path (this works more reliably after #3075)
- doc that `uninstall` is optional in the DSL, but required by the community
- link examples
- standardize mixed language on "stanza" over "field"
- further shrink `CONTRIBUTING.md` by deleting rarely used stanzas
and referencing `CASK_LANGUAGE_REFERENCE.md`
Rationale:
- lengthy CONTRIBUTING.md may itself discourage new Cask authors
- it is doubtful that everyone reads to the end, where there
are important notes about squashing.
CONTRIBUTING.md reduced from 7947 words to 1927 words.
This was accomplished principally by spinning out "details" sections
into a new reference file `doc/THE_CASK_LANGUAGE.md`, but also by
ruthless re-organization, removal of duplication, and trimming of
phrases. Content remains 99% identical, though a few typos were
caught along the way, and a table of contents was added.
There's only one substantive change in this patch, which is
that the Canonical App name is defined exactly by the name
of the App bundle on disk. The suggestion that the author's
website be consulted for orthography is removed.
Now that 'Link Details' exists, it's a great place to discuss how to handle subfolders within zip files. "relative path" is unclear in the world of zip folders, as the root isn't clear either, so an example seemed prudent. Seemed better here than in the link discussion.
Squashed from https://github.com/phinze/homebrew-cask/pull/2617
Package IDs are contained within <pkg-info> tags within PackageInfo
files. These files can be located by unpackaging a package with
`pkgutil --expand` and then using the `find` command.
Make caveats a first-class member of the Cask DSL. It no longer has to
be specified with "def caveats", but can be given as "caveats do ... end"
as with after_install blocks.
In addition, create a mini-DSL which can be used within caveats blocks,
providing standard messages when manual installers must be used,
reboot-required, etc.
Add alternate form: caveats can also accept a compile-time string for
simple cases.
This is 99% compatible with old Casks, as it still works by defining
a caveats method. However, all Casks containing caveats are cleaned
up and adapted according to the new DSL.
Full docs in CONTRIBUTING.md.