From 2b8c37b04e4885f321b05f9e2b92ce306efaf247 Mon Sep 17 00:00:00 2001
From: Eric Knibbe <enk3@outlook.com>
Date: Mon, 7 Aug 2023 15:21:39 -0400
Subject: [PATCH] Formula-Cookbook: revise download strategy docs

---
 docs/Formula-Cookbook.md | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index d9e11589ed..ee4060652f 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -612,24 +612,20 @@ For `url`/`regex` guidelines and additional `livecheck` block examples, refer to
 
 ### Unstable versions (`head`)
 
-Formulae can specify an alternate download for the upstream project’s development cutting-edge source (e.g. `master`/`main`/`trunk`) using [`head`](https://rubydoc.brew.sh/Formula#head-class_method), which can be activated by passing `--HEAD` when installing. Homebrew auto-detects most Git, SVN and Mercurial URLs. Specifying it is easy:
+Formulae can specify an alternate download for the upstream project’s development cutting-edge source (e.g. `master`/`main`/`trunk`) using [`head`](https://rubydoc.brew.sh/Formula#head-class_method), which can be activated by passing `--HEAD` when installing. Specifying it is done in the same manner as [`url`](https://rubydoc.brew.sh/Formula#url-class_method):
 
 ```ruby
 class Foo < Formula
-  head "https://github.com/mxcl/lastfm-cocoa.git"
+  head "https://github.com/some/package.git", branch: "main" # the default is "master"
 end
 ```
 
 You can also bundle the URL and any `head`-specific dependencies and resources in a `head do` block.
 
-To use a specific commit, tag, or branch from a repository, specify [`head`](https://rubydoc.brew.sh/Formula#head-class_method) with the `:tag` and `:revision`, `:revision`, or `:branch` option, like so:
-
 ```ruby
 class Foo < Formula
   head do
-    url "https://github.com/some/package.git", branch: "main" # the default is "master"
-                                         # or tag: "1_0_release", revision: "090930930295adslfknsdfsdaffnasd13"
-                                         # or revision: "090930930295adslfknsdfsdaffnasd13"
+    url "https://svn.code.sf.net/p/project/code/trunk"
     depends_on "pkg-config" => :build
   end
 end
@@ -637,14 +633,25 @@ end
 
 You can test whether the [`head`](https://rubydoc.brew.sh/Formula#head-class_method) is being built with `build.head?` in the `install` method.
 
-### Specifying the download strategy explicitly
+### URL download strategies
 
-To use one of Homebrew’s built-in download strategies, specify the `using:` flag on a [`url`](https://rubydoc.brew.sh/Formula#url-class_method) or [`head`](https://rubydoc.brew.sh/Formula#head-class_method). For example:
+When parsing a download URL, Homebrew auto-detects the resource type it points to, whether archive (e.g. tarball, zip) or version control repository (e.g. Git, SVN, Mercurial) and chooses an appropriate download strategy. Some strategies can be passed additional options to alter what's downloaded. For example, to use a specific commit, tag, or branch from a repository, specify [`url`](https://rubydoc.brew.sh/Formula#url-class_method) or [`head`](https://rubydoc.brew.sh/Formula#head-class_method) with the `:tag` and `:revision`, `:revision`, or `:branch` options, like so:
+
+```ruby
+class Foo < Formula
+  homepage "https://github.com/some/package"
+  url "https://github.com/some/package.git",
+      tag:      "v1.6.2",
+      revision: "344cd2ee3463abab4c16ac0f9529a846314932a2"
+end
+```
+
+If not inferable, specify which of Homebrew’s built-in download strategies to use with the `using:` option. For example:
 
 ```ruby
 class Nginx < Formula
   homepage "https://nginx.org/"
-  url "https://nginx.org/download/nginx-1.23.2.tar.gz"
+  url "https://nginx.org/download/nginx-1.23.2.tar.gz", using: :homebrew_curl
   sha256 "a80cc272d3d72aaee70aa8b517b4862a635c0256790434dbfc4d618a999b0b46"
   head "https://hg.nginx.org/nginx/", using: :hg
 ```
@@ -664,7 +671,7 @@ Homebrew offers anonymous download strategies.
 | `:post`          | `CurlPostDownloadStrategy`
 | `:svn`           | `SubversionDownloadStrategy`
 
-If you need more control over the way files are downloaded and staged, you can create a custom download strategy and specify it using the [`url`](https://rubydoc.brew.sh/Formula#url-class_method) method's `:using` option:
+If you need more control over the way files are downloaded and staged, you can create a custom download strategy and specify it with the `:using` option:
 
 ```ruby
 class MyDownloadStrategy < SomeHomebrewDownloadStrategy