# base/pmatrix-to-pmatrix-env

Rewrite plain-TeX pmatrix to the standard pmatrix environment with row breaks.

https://texform.dev/rules/base/pmatrix-to-pmatrix-env

## Metadata

| Field | Value |
| --- | --- |
| Key | base/pmatrix-to-pmatrix-env |
| Level | authoring |
| Fidelity | reading |
| Enabled by packages | base |
| Profiles | Authoring, Faithful, Corpus, Equiv |

## Rewrite patterns

### cr

From:

```latex
\pmatrix{#1 \cr #2}
```

To:

```latex
\begin{pmatrix} #1 \\ #2 \end{pmatrix}
```

### linebreak-arguments

From:

```latex
\pmatrix{#1 \\*[#2] #3}
```

To:

```latex
\begin{pmatrix} #1 \\*[#2] #3 \end{pmatrix}
```

### newline

From:

```latex
\pmatrix{#1 \newline #2}
```

To:

```latex
\begin{pmatrix} #1 \\ #2 \end{pmatrix}
```

### leading-row-scripts

From:

```latex
\pmatrix{#1 \cr_{#2}^{#3}#4}
```

To:

```latex
\begin{pmatrix} #1 \\{}_{#2}^{#3}#4 \end{pmatrix}
```

### leading-row-primes

From:

```latex
\pmatrix{#1 \cr'#2}
```

To:

```latex
\begin{pmatrix} #1 \\{}'#2 \end{pmatrix}
```

## Examples

Examples show the rule in isolation, not a complete normalization profile.

### Three by three parenthesized matrix

Before:

```latex
\pmatrix{a_{11} & a_{12} & 0 \cr a_{21} & a_{22} & 1 \cr 0 & 1 & \lambda}
```

After this rule:

```latex
\begin{pmatrix} a_{11} & a_{12} & 0 \\ a_{21} & a_{22} & 1 \\ 0 & 1 & \lambda \end{pmatrix}
```

Packages: base, ams.

The rendered result has pixel differences from the input.

### Ams pmatrix env out of scope

Before:

```latex
\begin{pmatrix} x \\ y \end{pmatrix}
```

After this rule:

```latex
\begin{pmatrix} x \\ y \end{pmatrix}
```

Packages: base, ams.

Rendering verified with the declared packages.

## Triggers

- [\\pmatrix](https://texform.dev/latex/commands/pmatrix)

## Eliminates

- [\\pmatrix](https://texform.dev/latex/commands/pmatrix)

## Produces

- [pmatrix](https://texform.dev/latex/environments/pmatrix)

## Touches

- [\\cr](https://texform.dev/latex/commands/cr)
- [\\\\](https://texform.dev/latex/commands/-5c-)
- [\\newline](https://texform.dev/latex/commands/newline)

## Downstream

- [ams/pmatrix-env-to-paren-matrix](https://texform.dev/rules/ams/pmatrix-env-to-paren-matrix): Rewrite the fenced pmatrix environment to explicit parens around a core matrix environment.

## Same family

- [ams/Bmatrix-env-to-brace-matrix](https://texform.dev/rules/ams/Bmatrix-env-to-brace-matrix): Rewrite the fenced Bmatrix environment to explicit braces around a core matrix environment.
- [ams/Vmatrix-env-to-Vert-matrix](https://texform.dev/rules/ams/Vmatrix-env-to-Vert-matrix): Rewrite the fenced Vmatrix environment to explicit double bars around a core matrix environment.
- [ams/bmatrix-env-to-bracket-matrix](https://texform.dev/rules/ams/bmatrix-env-to-bracket-matrix): Rewrite the fenced bmatrix environment to explicit brackets around a core matrix environment.
- [ams/pmatrix-env-to-paren-matrix](https://texform.dev/rules/ams/pmatrix-env-to-paren-matrix): Rewrite the fenced pmatrix environment to explicit parens around a core matrix environment.
- [ams/vmatrix-env-to-vert-matrix](https://texform.dev/rules/ams/vmatrix-env-to-vert-matrix): Rewrite the fenced vmatrix environment to explicit vertical bars around a core matrix environment.
- [base/cases-to-cases-env](https://texform.dev/rules/base/cases-to-cases-env): Rewrite plain-TeX cases to the standard cases environment with row breaks.
- [base/eqalign-to-aligned-env](https://texform.dev/rules/base/eqalign-to-aligned-env): Rewrite eqalign to the standard aligned environment.
- [base/eqalignno-to-align-env](https://texform.dev/rules/base/eqalignno-to-align-env): Rewrite eqalignno to the standard align* environment.
- [base/matrix-to-matrix-env](https://texform.dev/rules/base/matrix-to-matrix-env): Rewrite plain-TeX matrix to the standard matrix environment with row breaks.
- [physics/antidiagonalmatrix-to-admat](https://texform.dev/rules/physics/antidiagonalmatrix-to-admat): Collapse antidiagonalmatrix to the shorter admat helper.
- [physics/diagonalmatrix-to-dmat](https://texform.dev/rules/physics/diagonalmatrix-to-dmat): Collapse diagonalmatrix to the shorter dmat helper.
- [physics/matrixdeterminant-to-mdet](https://texform.dev/rules/physics/matrixdeterminant-to-mdet): Collapse matrixdeterminant to the shorter mdet determinant helper.
- [physics/bmqty-to-mqty](https://texform.dev/rules/physics/bmqty-to-mqty): Expand bmqty to the core mqty builder with bracket fence syntax.
- [physics/mdet-to-vmqty](https://texform.dev/rules/physics/mdet-to-vmqty): Expand mdet to the vmqty determinant-style builder.
- [physics/pmqty-to-mqty](https://texform.dev/rules/physics/pmqty-to-mqty): Expand pmqty to the core mqty builder with paren fence syntax.
- [physics/zmat-to-xmat](https://texform.dev/rules/physics/zmat-to-xmat): Expand zmat to the explicit xmat zero-filled builder.

## Notes

Convert only known body-level \cr, \\, and \newline row separators. Normalize \cr and \newline to an unstarred linebreak with no spacing argument; preserve the original star and optional spacing slots on \\ (including \\*, \\[2pt], and \\*[2pt]). Split a separator through any Scripted base chain, transfer its leading subscript, superscript, and Prime content to a fresh empty base at the start of the next row, and preserve nested script layers. Do not split separators inside explicit groups or nested environments, and leave unknown names such as \crcr untouched. Preserve real internal empty rows and the body sequence, including trailing separators. Only the plain-TeX source command is eliminated; existing AMS environments are out of scope.

## Disable this rule

```python
TransformEngine(profile="corpus", disable_rules=["base/pmatrix-to-pmatrix-env"])
```

```javascript
new TransformEngine({ profile: 'corpus', disableRules: ['base/pmatrix-to-pmatrix-env'] })
```

[Open in Playground](https://play.texform.dev/?input=%5Cpmatrix%7Ba_%7B11%7D+%26+a_%7B12%7D+%26+0+%5Ccr+a_%7B21%7D+%26+a_%7B22%7D+%26+1+%5Ccr+0+%26+1+%26+%5Clambda%7D)