Fix various broken links and out-of-date text

old_link_check.py

@@ -8,6 +8,15 @@
 DOCS_DIR = pathlib.Path(__file__).parent / 'docs'
 LINK_FINDER = re.compile(r'(?:version,\s+<a\s+href="(.*)">view\s+current)|(?:link\s+rel="canonical"\s+href="(.*)"\s+/>)')
 
+
+redirected = set()
+with open('redirects.txt', 'r') as f:
+    for line in f:
+        if line.startswith("#"):
+            continue
+        old, new = line.strip().split()
+        redirected.add(old)
+
 links = set()
 
 def walk_html():
@@ -26,6 +35,10 @@ def find_links():
 def check_links():
     broken = 0
     for (i, link) in enumerate(links):
+        raw_link = link.split('#')[0]
+        if raw_link in redirected:
+            print(f'Redirected link: {link}')
+            continue
         if i % 50 == 0:
             # don't spam the server
             time.sleep(2)

src/cmdstan-guide/installation.qmd

@@ -22,10 +22,9 @@ With conda, you can install CmdStan from the
 [conda-forge channel](https://conda-forge.org/).
 This will install a pre-built version of CmdStan along with the required
 dependencies (i.e. a C++ compiler, a version of Make, and required
-libraries) detailed below under [Source installation].
-The conda installation is designed so one can use the R or Python
-bindings to CmdStan seamlessly. Additionally, it provides the command
-`cmdstan_model` to activate the CmdStan makefile from anywhere.
+libraries). The conda installation is designed so one can use the R or
+Python bindings to CmdStan seamlessly. Additionally, it provides the
+command `cmdstan_model` to activate the CmdStan makefile from anywhere.
 
 _Note_: This requires that conda has been installed already on your machine.
 You can either install [miniconda](https://docs.conda.io/en/latest/miniconda.html), a free, minimal installer for conda
@@ -224,7 +223,7 @@ On Linux and macOS:
 > make examples/bernoulli/bernoulli
 
 # fit to provided data (results of 10 trials, 2 out of 10 successes)
-> ./examples/bernoulli/bernoulli sample\ 
+> ./examples/bernoulli/bernoulli sample\
   data file=examples/bernoulli/bernoulli.data.json
 
 # default output written to file `output.csv`,
@@ -587,7 +586,7 @@ CmdStan v2.33.1 help
     4. Build the diagnose utility bin/diagnose
     5. Build all libraries and object files compile and link an executable Stan program
 
-    Note: to build using multiple cores, use the -j option to make, e.g., 
+    Note: to build using multiple cores, use the -j option to make, e.g.,
     for 4 cores:
     > make build -j4
 

src/cmdstan-guide/parallelization.qmd

@@ -50,7 +50,7 @@ Example:
 ```
 
 When the model is compiled with `STAN_THREADS` we can sample with multiple chains with a single
-executable (see section [running multiple chains]{#multi-chain-sampling} for cases when this is
+executable (see section [running multiple chains](mcmc_config.qmd#multi-chain-sampling) for cases when this is
 available). When running multiple chains `num_threads` is the maximum number of threads that can
 be used by all the chains combined. The exact number of threads that will be used for each chain
 at a given point in time is determined by the TBB scheduler. The following example start 2 chains

src/functions-reference/deprecated_functions.qmd

@@ -12,7 +12,7 @@ replace it.
 Starting in Stan 2.29, deprecated functions with drop in replacements (such as
 the renaming of `get_lp` or `multiply_log`) will be removed 3 versions later
 e.g., functions deprecated in Stan 2.20 will be removed in Stan 2.23 and placed
-in [Removed Functions]. The Stan compiler can
+in [Removed Functions](removed_functions.qmd). The Stan compiler can
 [automatically update](https://mc-stan.org/docs/stan-users-guide/using-stanc.html#stanc-pretty-printing)
 these on the behalf of the user for the entire deprecation window and at least
 one version following the removal.

src/functions-reference/integer-valued_basic_functions.qmd

@@ -218,7 +218,7 @@ in the Stan Reference Manual.
 Return the value `x` truncated to an integer. This will throw an error
 if the value of `x` is too big to represent as a 32-bit signed integer.
 
-This is similar to `trunc` (see [Rounding functions]) but the return type is of
+This is similar to `trunc` (see [Rounding functions](real-valued_basic_functions.qmd#rounding-functions)) but the return type is of
 type `int`. For example, `to_int(3.9)` is `3`, and `to_int(-3.9)` is `-3`.
 {{< since 2.31 >}}
 

src/reference-manual/blocks.qmd

@@ -171,7 +171,7 @@ applied once per chain.*
 `model` | yes | evaluate / leapfrog step
 `generated quantities` | yes | eval / sample
   |   | write / sample
-`\slshape (initialization)` | n/a | read, transform / chain
+*`(initialization)`* | n/a | read, transform / chain
 
 **Variable Declaration Table.**
 <a id="where-to-declare-table"></a>
@@ -271,7 +271,7 @@ generated quantities {
 }
 ```
 
-In this example, `y[N]` is a modeled data vector.  Although it is
+In this example, `y` is an array of modeled data.  Although it is
 specified in the `data` block, and thus must have a known value
 before the program may be run, it is modeled as if it were generated
 randomly as described by the model.

src/reference-manual/deprecations.qmd

@@ -9,7 +9,7 @@ to replace it.
 
 Starting with Stan 2.29, minor (syntax-level) deprecations can be removed 3
 versions after release; e.g., syntax deprecated in Stan 2.20 will be removed in
-Stan 2.23 and placed in [Removed Features]. The Stan compiler can
+Stan 2.23 and placed in [Removed Features](removals.qmd). The Stan compiler can
 [automatically update](https://mc-stan.org/docs/stan-users-guide/using-stanc.html#stanc-pretty-printing)
 many of these on the behalf of the user for at least one version after they are
 removed.

src/reference-manual/diagnostics.qmd

@@ -51,9 +51,8 @@ the reference manual chapter on transforms.
 
 The log density includes the Jacobian adjustment implied by the
 constraints declared on variables.  The Jacobian adjustment for
-constrained parameter transforms will be turned off if optimization is
-used in practice, but there is as of yet no way to turn it off in
-diagnostic mode.
+constrained parameter transforms may be turned off for optimization,
+but there is as of yet no way to turn it off in diagnostic mode.
 
 
 ## Configuration options

src/reference-manual/execution.qmd

@@ -57,7 +57,7 @@ displayed.
 
 ## Initialization
 
-Initialization is the same for sampling, optimization, and diagnosis
+Initialization is the same for all of Stan's algorithms.
 
 
 ### User-supplied initial values {-}

src/reference-manual/expressions.qmd

@@ -158,8 +158,7 @@ The following built in functions are also reserved and
 cannot be used as variable names:
 
 ```
-print, reject, profile, get_lp, increment_log_prob,
-target
+print, reject, profile, target
 ```
 
 The following block identifiers are reserved and cannot be used as variable names:
@@ -1117,7 +1116,11 @@ For example, this means `array[,] int` may be used where `array [,]
 real` or `array [,] complex` is required; as another example, `array[]
 real` may be used anywhere `array[] complex` is required.
 
+Tuples have the natural extension of the above rules, applied to all
+sub-types at once
 
+8. A `tuple(U1, ..., UN)` may be promoted to a `tuple(T1, ..., TN)` if
+ every `Un` can be promoted to `Tn` for `n` in `1:N`
 
 #### Literals {-}
 

src/reference-manual/includes.qmd

@@ -83,7 +83,7 @@ contents of the included file.
 
 ## Recursive includes
 
-Recursive includes will be ignored.  For example, suppose
+Recursive includes will lead to a compiler error.  For example, suppose
 `a.stan` contains
 
 ```stan
@@ -96,9 +96,20 @@ and `b.stan` contains
 #include a.stan
 ```
 
-The result of processing this file will be empty, because
-`a.stan` will include `b.stan`, from which the include of
-`a.stan` is ignored and a warning printed.
+This will result in an error explaining the circular dependency:
+
+```
+Syntax error in './b.stan', line 1, column 0, included from
+'./a.stan', line 1, column 0, included from
+'./b.stan', line 1, column 0, included from
+'a.stan', line 1, column 0, include error:
+   -------------------------------------------------
+     1:  #include a.stan
+         ^
+   -------------------------------------------------
+
+File a.stan recursively included itself.
+```
 
 ## Include paths
 

src/reference-manual/licenses.qmd

@@ -61,6 +61,14 @@ SUNDIALS is distributed under the
 The copyright of SUNDIALS is owned by Lawrence Livermore National
 Security Lab.
 
+## Threaded Building Blocks (TBB) License
+
+Stan uses the Threaded Building Blocks (TBB) library for parallel computations.
+TBB is distributed under the
+
+* [Apache License, version 2](https://opensource.org/license/apache-2-0)
+
+The copyright of TBB is owned by Intel Corporation.
 
 ## Google test license
 

src/reference-manual/statements.qmd

@@ -124,11 +124,12 @@ an expression of type `vector` may be assigned to an lvalue of type
 ### Lvalue summary {-}
 
 The expressions that are legal left-hand sides of assignment
-statements are known as "lvalues."  In Stan, there are only two
+statements are known as "lvalues."  In Stan, there are three
 kinds of legal lvalues,
 
 * a variable, or
-* a variable with one or more indices.
+* a variable with one or more indices, or
+* a comma separated list of lvalues surrounded by `(` and `)`
 
 To be used as an lvalue, an indexed variable must have at least as
 many dimensions as the number of indices provided.  An array of real
@@ -1140,12 +1141,8 @@ message that it is already defined.
 ### No constraints on local variables {-}
 
 Local variables may not have constraints on their declaration.  The
-only types that may be used are
-
-```
-int, real, vector[K], row_vector[K], matrix[M, N].
-```
-
+only types that may be used are listed in the [types table](types.qmd#id:constrained-types.figure)
+under "local".
 
 ### Blocks within blocks {-}
 
@@ -1430,6 +1427,10 @@ value of the log probability accumulator before and after each
 sampling statement, it's possible to isolate where the log probability
 becomes ill-defined (i.e., becomes not-a-number).
 
+Note that print statements may not always be displayed immediately,
+but rather at the end of an operation (e.g., leapfrog step). As such,
+some issues such as infinite loops are difficult to debug effectively
+with this technique.
 
 ## Reject statements {#reject-statements.section}
 

src/reference-manual/syntax.qmd

@@ -492,6 +492,6 @@ A second condition is that there not be more indexes provided than
 dimensions of the underlying expression (in general) or variable (on
 the left side of assignments) being indexed.  A vector or row vector
 adds 1 to the array dimension and a matrix adds 2.  That is, the type
-`matrix[ , , ]`, a three-dimensional array of matrices, has five
+`array[ , , ] matrix`, a three-dimensional array of matrices, has five
 index positions: three for the array, one for the row of the matrix
 and one for the column.

src/reference-manual/types.qmd

@@ -83,7 +83,7 @@ size $6 \times 7$ containing values that are $3 \times 3$ matrices,
 and declares `z` to be a $12 \times 8 \times 15$ array of complex numbers.
 
 Prior to 2.26 Stan models used a different syntax which has since been removed.
-See the [Removed Features] chapter for more details.
+See the [Removed Features](removals.qmd) chapter for more details.
 
 ### Tuple types {-}
 
@@ -167,13 +167,14 @@ Stan uses 32-bit (4-byte) integers for all of its integer
 representations.  The maximum value that can be represented
 as an integer is $2^{31}-1$; the minimum value is $-(2^{31})$.
 
-When integers overflow, their values wrap.  Thus it is up to the Stan
+When integers overflow, their value is determined by the underlying architecture.
+On most, their values wrap, but this cannot be guaranteed.  Thus it is up to the Stan
 programmer to make sure the integer values in their programs stay in
 range.  In particular, every intermediate expression must have an
 integer value that is in range.
 
 Integer arithmetic works in the expected way for addition,
-subtraction, and multiplication, but rounds the result of division
+subtraction, and multiplication, but truncates the result of division
 (see [the Stan Functions Reference integer-valued arithmetic operators
 section](https://mc-stan.org/docs/functions-reference/integer-valued_basic_functions.html#int-arithmetic)
 for more information).
@@ -398,8 +399,7 @@ real<lower=-1, upper=1> rho;
 Lower bounds that are negative infinity or upper bounds that are
 positive infinity are ignored.  Stan provides constants
 `positive_infinity()` and `negative_infinity()` which may
-be used for this purpose, or they may be read as data in the dump
-format.
+be used for this purpose, or they may be supplied as data.
 
 
 ### Affinely transformed real {-}

src/reference-manual/user-functions.qmd

@@ -418,6 +418,10 @@ and the recursive cases are that
 * a conditional statement qualifies if it has a default else
   clause and all of its body statements qualify.
 
+An exception is made for "obviously infinite" loops like `while (1)`, which contain
+a `return` statement and no `break` statements. The only way to exit such a loop
+is to return, so they are considered as returning statements.
+
 These rules disqualify
 
 ```stan

src/stan-users-guide/posterior-predictive-checks.qmd

@@ -160,7 +160,7 @@ lower variance than the original data.  That is, the model's not
 appropriately capturing the variance of the data.
 
 
-## Posterior ``p-values''
+## Posterior ''p-values''
 
 If a model captures the data well, summary statistics such as
 sample mean and standard deviation, should have similar values in
@@ -176,7 +176,7 @@ $$
 \cdot p\left( y^{\textrm{rep}} \mid y \right)
 \, \textrm{d}{y^{\textrm{rep}}}.
 $$
-It is important to note that``p-values'' is in quotes because these
+It is important to note that ''p-values'' is in quotes because these
 statistics are not classically calibrated, and thus will not in
 general have a uniform distribution even when the model is well
 specified [@BayarriBerger:2000].