From 012a9f5a7b156c06086c0490058baee85fa7f6f3 Mon Sep 17 00:00:00 2001
From: Roland Walker <walker@pobox.com>
Date: Wed, 15 Oct 2014 09:26:37 -0400
Subject: [PATCH] document `appcast` stanza

The :latest_version key stays undocumented, as it is not
clear yet whether it is useful
---
 doc/CASK_LANGUAGE_REFERENCE.md | 19 ++++++++++++++++++-
 doc/cask_language_deltas.md    |  1 +
 lib/cask/dsl/appcast.rb        |  4 ++--
 3 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/doc/CASK_LANGUAGE_REFERENCE.md b/doc/CASK_LANGUAGE_REFERENCE.md
index 63e01982efd..c43bbedf801 100644
--- a/doc/CASK_LANGUAGE_REFERENCE.md
+++ b/doc/CASK_LANGUAGE_REFERENCE.md
@@ -14,6 +14,7 @@ Cask Domain-Specific Language (DSL) which are not needed in most cases.
  * [Caveats Stanza Details](#caveats-stanza-details)
  * [Checksum Stanza Details](#checksum-stanza-details)
  * [URL Stanza Details](#url-stanza-details)
+ * [Appcast Stanza Details](#appcast-stanza-details)
  * [Tags Stanza Details](#tags-stanza-details)
  * [License Stanza Details](#license-stanza-details)
  * [App Stanza Details](#app-stanza-details)
@@ -102,6 +103,7 @@ Each Cask must declare one or more *artifacts* (i.e. something to install)
 | ---------------------- |------------------------------ | ----------- |
 | `uninstall`            | yes                           | procedures to uninstall a Cask. Optional unless the `pkg` stanza is used. (see also [Uninstall Stanza Details](#uninstall-stanza-details))
 | `zap`                  | yes                           | additional procedures for a more complete uninstall, including user files and shared resources. (see also [Zap Stanza Details](#zap-stanza-details))
+| `appcast`              | no                            | a URL providing an appcast feed to find updates for this Cask.  (see also [Appcast Stanza Details](#appcast-stanza-details))
 | `depends_on`           | yes                           | a list of dependencies required by this Cask (see also [Depends_on Stanza Details](#depends_on-stanza-details))
 | `caveats`              | yes                           | a string or Ruby block providing the user with Cask-specific information at install time (see also [Caveats Stanza Details](#caveats-stanza-details))
 | `preflight`            | yes                           | a Ruby block containing preflight install operations (needed only in very rare cases)
@@ -285,7 +287,6 @@ have to test each of them:
 $ ./developer/bin/list_url_attributes_on_file <file>
 ```
 
-
 ### Subversion URLs
 
 In rare cases, a distribution may not be available over ordinary HTTP/S.
@@ -299,6 +300,22 @@ following key/value pairs to `url`:
 | `:trust_cert`      | set to `true` to automatically trust the certificate presented by the server (avoiding an interactive prompt)
 
 
+## Appcast Stanza Details
+
+The value of the `appcast` stanza is a string, holding the URL for an
+appcast which provides information on future updates.  Generally, the
+appcast URL returns Sparkle-compatible XML, though that is not required.
+
+Example: [adium.rb](../../d7f8eafa4fc01a6c383925d9962b5da33876a8b6/Casks/adium.rb#L6)
+
+### Additional Appcast Parameters
+
+| key                | value       |
+| ------------------ | ----------- |
+| `:sha256`          | a string holding the SHA-256 checksum of the most recent appcast which matches the current Cask versioning
+| `:format`          | a symbol describing the appcast format.  One of: `:sparkle`, `:plaintext`, `:unknown`, where `:sparkle` is the default.
+
+
 ## License Stanza Details
 
 The `license` stanza is not free-form.  The value must be chosen from a
diff --git a/doc/cask_language_deltas.md b/doc/cask_language_deltas.md
index 2391dfb02d1..997296e62b8 100644
--- a/doc/cask_language_deltas.md
+++ b/doc/cask_language_deltas.md
@@ -31,6 +31,7 @@ This notice will be removed for the final form.**
 
 ## Additions (1.0)
 
+ * `appcast`
  * `artifact`
  * `depends_on :cask`
    * *stub* - not yet functional
diff --git a/lib/cask/dsl/appcast.rb b/lib/cask/dsl/appcast.rb
index 79a36d9ddc8..265aad780c2 100644
--- a/lib/cask/dsl/appcast.rb
+++ b/lib/cask/dsl/appcast.rb
@@ -1,6 +1,6 @@
 class Cask::DSL::Appcast
 
-  # note  :latest_version is considered experimental
+  # todo  :latest_version is considered experimental
   #       and may be removed
 
   APPCAST_FORMATS = Set.new [
@@ -15,7 +15,7 @@ class Cask::DSL::Appcast
     @parameters     = parameters
     @uri            = Cask::UnderscoreSupportingURI.parse(uri)
     @sha256         = @parameters[:sha256]
-    @latest_version = @parameters[:latest_version]
+    @latest_version = @parameters[:latest_version]    # experimental
     @format         = @parameters[:format]
     @format         = APPCAST_FORMATS.first if @format.nil?
     unless APPCAST_FORMATS.include?(@format)