docs: updates from Homebrew/brew

docs/Kernel.html

@@ -953,9 +953,6 @@ <h3 class="signature first" id="disk_usage_readable-instance_method">
       <pre class="lines">
 
 
-415
-416
-417
 418
 419
 420
@@ -974,10 +971,13 @@ <h3 class="signature first" id="disk_usage_readable-instance_method">
 433
 434
 435
-436</pre>
+436
+437
+438
+439</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 415</span>
+      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 418</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_disk_usage_readable'>disk_usage_readable</span><span class='lparen'>(</span><span class='id identifier rubyid_size_in_bytes'>size_in_bytes</span><span class='rparen'>)</span>
   <span class='kw'>if</span> <span class='id identifier rubyid_size_in_bytes'>size_in_bytes</span> <span class='op'>&gt;=</span> <span class='int'>1_073_741_824</span>
@@ -1042,7 +1042,10 @@ <h3 class="signature " id="ensure_executable!-instance_method">
 406
 407
 408
-409</pre>
+409
+410
+411
+412</pre>
     </td>
     <td>
       <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 398</span>
@@ -1053,6 +1056,9 @@ <h3 class="signature " id="ensure_executable!-instance_method">
   <span class='id identifier rubyid_executable'>executable</span> <span class='op'>=</span> <span class='lbracket'>[</span>
     <span class='id identifier rubyid_which'>which</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span><span class='comma'>,</span>
     <span class='id identifier rubyid_which'>which</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='comma'>,</span> <span class='const'><span class='object_link'><a href="top-level-namespace.html#ORIGINAL_PATHS-constant" title="ORIGINAL_PATHS (constant)">ORIGINAL_PATHS</a></span></span><span class='rparen'>)</span><span class='comma'>,</span>
+    <span class='comment'># We prefer the opt_bin path to a formula&#39;s executable over the prefix
+</span>    <span class='comment'># path where available, since the former is stable during upgrades.
+</span>    <span class='const'><span class='object_link'><a href="top-level-namespace.html#HOMEBREW_PREFIX-constant" title="HOMEBREW_PREFIX (constant)">HOMEBREW_PREFIX</a></span></span><span class='op'>/</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>opt/</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_formula_name'>formula_name</span><span class='embexpr_end'>}</span><span class='tstring_content'>/bin/</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_name'>name</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
     <span class='const'><span class='object_link'><a href="top-level-namespace.html#HOMEBREW_PREFIX-constant" title="HOMEBREW_PREFIX (constant)">HOMEBREW_PREFIX</a></span></span><span class='op'>/</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>bin/</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_name'>name</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
   <span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_compact'>compact</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span>
   <span class='kw'>return</span> <span class='id identifier rubyid_executable'>executable</span> <span class='kw'>if</span> <span class='id identifier rubyid_executable'>executable</span><span class='period'>.</span><span class='id identifier rubyid_exist?'>exist?</span>
@@ -1400,14 +1406,14 @@ <h3 class="signature " id="number_readable-instance_method">
       <pre class="lines">
 
 
-438
-439
-440
 441
-442</pre>
+442
+443
+444
+445</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 438</span>
+      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 441</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_number_readable'>number_readable</span><span class='lparen'>(</span><span class='id identifier rubyid_number'>number</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_numstr'>numstr</span> <span class='op'>=</span> <span class='id identifier rubyid_number'>number</span><span class='period'>.</span><span class='id identifier rubyid_to_i'>to_i</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span>
@@ -2026,12 +2032,12 @@ <h3 class="signature " id="paths-instance_method">
       <pre class="lines">
 
 
-411
-412
-413</pre>
+414
+415
+416</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 411</span>
+      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 414</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_paths'>paths</span>
   <span class='ivar'>@paths</span> <span class='op'>||=</span> <span class='const'><span class='object_link'><a href="top-level-namespace.html#ORIGINAL_PATHS-constant" title="ORIGINAL_PATHS (constant)">ORIGINAL_PATHS</a></span></span><span class='period'>.</span><span class='id identifier rubyid_uniq'>uniq</span><span class='period'>.</span><span class='id identifier rubyid_map'>map</span><span class='lparen'>(</span><span class='op'>&amp;</span><span class='symbol'>:to_s</span><span class='rparen'>)</span>
@@ -2288,14 +2294,14 @@ <h3 class="signature " id="redact_secrets-instance_method">
       <pre class="lines">
 
 
-513
-514
-515
 516
-517</pre>
+517
+518
+519
+520</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 513</span>
+      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 516</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_redact_secrets'>redact_secrets</span><span class='lparen'>(</span><span class='id identifier rubyid_input'>input</span><span class='comma'>,</span> <span class='id identifier rubyid_secrets'>secrets</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_secrets'>secrets</span><span class='period'>.</span><span class='id identifier rubyid_compact'>compact</span>
@@ -2484,20 +2490,20 @@ <h3 class="signature " id="tap_and_name_comparison-instance_method">
       <pre class="lines">
 
 
-501
-502
-503
 504
 505
 506
 507
 508
 509
 510
-511</pre>
+511
+512
+513
+514</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 501</span>
+      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 504</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_tap_and_name_comparison'>tap_and_name_comparison</span>
   <span class='id identifier rubyid_proc'>proc</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='id identifier rubyid_b'>b</span><span class='op'>|</span>
@@ -2543,9 +2549,6 @@ <h3 class="signature " id="truncate_text_to_approximate_size-instance_method">
       <pre class="lines">
 
 
-448
-449
-450
 451
 452
 453
@@ -2569,10 +2572,13 @@ <h3 class="signature " id="truncate_text_to_approximate_size-instance_method">
 471
 472
 473
-474</pre>
+474
+475
+476
+477</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 448</span>
+      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 451</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_truncate_text_to_approximate_size'>truncate_text_to_approximate_size</span><span class='lparen'>(</span><span class='id identifier rubyid_str'>str</span><span class='comma'>,</span> <span class='id identifier rubyid_max_bytes'>max_bytes</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_front_weight'>front_weight</span> <span class='op'>=</span> <span class='id identifier rubyid_options'>options</span><span class='period'>.</span><span class='id identifier rubyid_fetch'>fetch</span><span class='lparen'>(</span><span class='symbol'>:front_weight</span><span class='comma'>,</span> <span class='float'>0.5</span><span class='rparen'>)</span>
@@ -2836,9 +2842,6 @@ <h3 class="signature " id="with_env-instance_method">
       <pre class="lines">
 
 
-486
-487
-488
 489
 490
 491
@@ -2849,10 +2852,13 @@ <h3 class="signature " id="with_env-instance_method">
 496
 497
 498
-499</pre>
+499
+500
+501
+502</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 486</span>
+      <pre class="code"><span class="info file"># File 'extend/kernel.rb', line 489</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_with_env'>with_env</span><span class='lparen'>(</span><span class='id identifier rubyid_hash'>hash</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_old_values'>old_values</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span>