# JSS Rule Catalogue
**Source of truth**: [catalogue.yaml](catalogue.yaml). This markdown is generated by `python -m tools.render_catalogue`; edits here are overwritten.
**Schema version**: 1
**Vendored sources**: `docs/jss-template/jss.cls` dated 2021-05-23
**Rule count**: 62
**Category count**: 16
---
## Preamble
_preamble_ — 8 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-PRE-001` | error | Document class must be jss with a valid class option (article, codesnippet, bookreview, softwarereview) | jss_cls | `jss.cls:37` | — |
| `JSS-PRE-002` | error | Preamble defines \Address{} with author affiliation and contact | jss_cls | `jss.cls:\Address` | — |
| `JSS-PRE-003` | error | When \title{} contains LaTeX markup, preamble also defines \Plaintitle{} with the markup-free form | jss_cls | `jss.cls:\Plaintitle` | ✓ |
| `JSS-PRE-004` | error | \Abstract{} is present and overrides the sentinel placeholder from jss.cls | jss_cls | `jss.cls:120` | — |
| `JSS-PRE-005` | error | \Keywords{} is present and overrides the sentinel placeholder from jss.cls | jss_cls | `jss.cls:197` | — |
| `JSS-PRE-006` | warning | \Plaintitle, \Plainauthor, \Plainkeywords contain no LaTeX markup (PDF metadata must be plain text) | jss_cls | `jss.cls:\Plaintitle` | ✓ |
| `JSS-PRE-007` | error | When \author{} contains LaTeX markup, preamble also defines \Plainauthor{} with the markup-free form | jss_cls | `jss.cls:\Plainauthor` | ✓ |
| `JSS-PRE-008` | error | When \Keywords{} contains LaTeX markup, preamble also defines \Plainkeywords{} with the markup-free form | jss_cls | `jss.cls:\Plainkeywords` | ✓ |
## Structure
_structure_ — 6 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-STRUCT-001` | warning | Document ends with a summary / discussion section before the bibliography | article_tex | `article.tex:378` | — |
| `JSS-STRUCT-002` | warning | Acknowledgments section uses American spelling (not "Acknowledgements") | article_tex | `article.tex:407` | ✓ |
| `JSS-STRUCT-003` | warning | Appendix sections have proper titles instead of a bare "Appendix" | article_tex | `article.tex:438` | — |
| `JSS-STRUCT-004` | error | References are declared via \bibliography{} rather than a hand-written thebibliography environment | style_guide | `#what-are-the-most-important-style-guidelines-in-jss` | — |
| `JSS-STRUCT-005` | warning | \author{} separates authors with \And or \AND (not lowercase \and) | article_tex | `article.tex:22` | ✓ |
| `JSS-STRUCT-006` | warning | Appendix follows the bibliography with a \newpage (or \clearpage) separator | article_tex | `article.tex:430` | ✓ |
## Markup
_markup_ — 4 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-MARKUP-001` | warning | Programming-language names in prose are wrapped in \proglang{} | jss_cls | `jss.cls:\proglang` | ✓ |
| `JSS-MARKUP-002` | warning | Software-package names in prose are wrapped in \pkg{} | jss_cls | `jss.cls:\pkg` | ✓ |
| `JSS-MARKUP-003` | warning | Inline function, argument, command names, and R sentinel values are wrapped in \code{} | jss_cls | `jss.cls:\code` | ✓ |
| `JSS-MARKUP-004` | warning | Section titles containing markup supply a plain-text shim via \section[plain]{markup} | style_guide | `#my-latex-paper-does-not-compile-when-there-is-jss-markup-in-section-titles-what-should-i-do` | ✓ |
## Citations
_citations_ — 3 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-CITE-002` | warning | First occurrence of a software package has a citation within the same paragraph | style_guide | `#what-are-the-most-important-style-guidelines-in-jss` | — |
| `JSS-CITE-003` | warning | Avoid bracket-in-bracket citation forms like (\cite{...}); use \citep{...} instead | style_guide | `#what-are-the-different-cite-citet-citep-commands-about` | ✓ |
| `JSS-CITE-004` | warning | Citations use natbib commands (\cite, \citet, \citep, \citealp) rather than hardcoded author-year text | jss_cls | `jss.cls:62` | — |
## References
_references_ — 6 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-REFS-001` | warning | BibTeX entries carry a year field so natbib author-year citations render correctly | style_guide | `#what-are-the-most-important-style-guidelines-in-jss` | — |
| `JSS-REFS-003` | info | BibTeX entries include a doi field where one is available (advisory) | article_tex | `article.tex:421` | — |
| `JSS-REFS-004` | warning | BibTeX titles use JSS markup (\proglang, \pkg, \code) for language and package names | style_guide | `#how-to-cite-r-packages` | — |
| `JSS-REFS-005` | warning | Journal titles in BibTeX entries are not abbreviated | article_tex | `article.tex:473` | — |
| `JSS-REFS-006` | warning | BibTeX titles are in title style — loose heuristic (flags lowercase first word or unusual mixed case) | style_guide | `#what-are-the-most-important-style-guidelines-in-jss` | — |
| `JSS-REFS-007` | warning | Journal titles in BibTeX entries are in title case | article_tex | `article.tex:473` | — |
## BibTeX
_bibtex_ — 5 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-BIBTEX-001` | error | Every BibTeX entry has a non-empty citation key | style_guide | `#how-to-cite-r-packages` | — |
| `JSS-BIBTEX-002` | error | BibTeX citation keys are unique within the database | style_guide | `#how-to-cite-r-packages` | — |
| `JSS-BIBTEX-003` | error | BibTeX entries carry the fields required for their entry type (article, book, inproceedings, …) | style_guide | `#how-to-cite-r-packages` | — |
| `JSS-BIBTEX-004` | warning | Entries with 6+ authors use \shortcites{} or the shortnames class option is enabled | jss_cls | `jss.cls:45` | — |
| `JSS-BIBTEX-005` | error | No BibTeX field key is repeated within a single entry | style_guide | `#how-to-cite-r-packages` | — |
## Naming
_naming_ — 2 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-NAME-001` | warning | Programming-language names use their canonical capitalisation | style_guide | `#which-naming-conventions-are-used-for-software-journal-and-publisher-names-in-jss` | ✓ |
| `JSS-NAME-002` | warning | Publisher and journal names follow JSS conventions (e.g., "Springer-Verlag", "The Annals of Statistics") | style_guide | `#which-naming-conventions-are-used-for-software-journal-and-publisher-names-in-jss` | ✓ |
## Capitalization
_capitalization_ — 3 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-CAP-001` | warning | \title{} is in title style (principal words capitalised) | style_guide | `#what-are-the-most-important-style-guidelines-in-jss` | — |
| `JSS-CAP-002` | warning | Section titles are in sentence style (first word capitalised; others lowercase except proper names) | style_guide | `#what-are-the-most-important-style-guidelines-in-jss` | — |
| `JSS-CAP-004` | warning | \Keywords{} is comma-separated and in sentence case | article_tex | `article.tex:48` | — |
## Typography
_typography_ — 4 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-TYPO-001` | warning | Figure and table captions end with a period | style_guide | `#how-to-format-figuretable-captions` | ✓ |
| `JSS-TYPO-002` | warning | Figure / table captions avoid emphasis macros wrapping the whole caption (\emph, \textbf, \textit on full caption) | style_guide | `#how-to-format-figuretable-captions` | — |
| `JSS-TYPO-003` | warning | Tables do not use footnote-style annotations; annotations go in the caption | style_guide | `#how-to-format-figuretable-captions` | — |
| `JSS-TYPO-004` | warning | \caption{} appears after the figure / table content, not before | style_guide | `#how-to-format-figuretable-captions` | — |
## Abbreviations
_abbreviations_ — 1 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-ABBR-001` | warning | Abbreviations are in uppercase without periods or additional formatting | style_guide | `#how-should-abbrevations-be-formatted` | ✓ |
## Code style
_code_style_ — 3 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-CODE-001` | warning | Verbatim / CodeInput blocks do not contain comments; comments belong in the surrounding LaTeX text | style_guide | `#how-should-code-be-formatted-in-the-manuscript` | — |
| `JSS-CODE-002` | warning | R library() and data() calls quote their first argument | style_guide | `#miscellaneous` | ✓ |
| `JSS-CODE-003` | warning | Code samples use spaces around operators and after commas | style_guide | `#how-should-code-be-formatted-in-the-manuscript` | ✓ |
## Code width
_code_width_ — 1 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-WIDTH-001` | warning | Code input / output inside Sinput / CodeInput / CodeOutput environments fits within the configured column limit | style_guide | `#how-should-code-be-formatted-in-the-manuscript` | — |
## Operators
_operators_ — 4 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-OPER-001` | warning | Symbol-plus-noun constructs like p-value and t-statistic are typeset as $p$~value and $t$~statistic (tie, no hyphen) | style_guide | `#miscellaneous` | ✓ |
| `JSS-OPER-002` | warning | Transpose is typeset with \top rather than a superscript prime or literal T | style_guide | `#miscellaneous` | ✓ |
| `JSS-OPER-003` | warning | Display equations have no blank lines immediately before or after (use % to suppress paragraph breaks) | article_tex | `article.tex:154` | ✓ |
| `JSS-OPER-004` | warning | Expectation / variance / covariance / probability use jss.cls shortcuts \E, \VAR, \COV, \Prob | jss_cls | `jss.cls:484` | ✓ |
## Cross-references
_crossrefs_ — 7 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-XREF-001` | warning | Figures and tables are referenced via \ref{} rather than by manual numbering | style_guide | `#what-are-the-most-important-style-guidelines-in-jss` | — |
| `JSS-XREF-002` | info | Equation references prefer Equation~\ref{...} (capitalised) over bare (\ref{...}) or \eqref{...} | style_guide | `#miscellaneous` | ✓ |
| `JSS-XREF-003` | warning | Cross-references to subsections use "Section x.y" rather than "Subsection x.y" | style_guide | `#miscellaneous` | — |
| `JSS-XREF-004` | info | Numbered equations carry \label{} and are referenced from the text | style_guide | `#what-are-the-most-important-style-guidelines-in-jss` | — |
| `JSS-XREF-005` | warning | Figures and tables carry \label{} and are referenced from the text | style_guide | `#what-are-the-most-important-style-guidelines-in-jss` | — |
| `JSS-XREF-006` | warning | Figure and table floats carry a \caption{} | style_guide | `#what-are-the-most-important-style-guidelines-in-jss` | — |
| `JSS-XREF-007` | info | Cross-reference nouns are spelled out (Figure/Section/Table), not abbreviated (Fig./Sec./Tab.) | style_guide | `#miscellaneous` | ✓ |
## House style
_house_style_ — 3 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-HOUSE-001` | warning | "e.g." and "i.e." are followed by a comma so LaTeX does not treat the period as a sentence end | style_guide | `#miscellaneous` | ✓ |
| `JSS-HOUSE-002` | warning | Book editions are indicated as 2nd, 3rd, etc., not as "second" or "2e" | style_guide | `#miscellaneous` | ✓ |
| `JSS-HOUSE-003` | info | Preamble avoids loading LaTeX packages that jss.cls already provides (graphicx, xcolor, ae, fancyvrb, hyperref) | jss_cls | `jss.cls:54` | ✓ |
## Project
_project_ — 2 rule(s)
| Rule ID | Severity | Description | Authority | Authority ref | Auto-fixable |
|---|---|---|---|---|---|
| `JSS-PROJECT-001` | error | A cycle exists in the \input/\include/\subfile/\bibliography reference graph | author_instructions | `multi-file-projects` | — |
| `JSS-PROJECT-002` | error | A \input/\include/\subfile/\bibliography target could not be found | author_instructions | `multi-file-projects` | — |
## Rule details
### JSS-PRE-001
**Category**: `preamble` · **Severity**: `error` · **Auto-fixable**: no
Document class must be jss with a valid class option (article, codesnippet, bookreview, softwarereview)
**Authority**: `jss_cls` → `jss.cls:37`
**Inspects**: `tex_files`
Example violation
```latex
\documentclass{article}
\usepackage{jss}
```
Example fix
```latex
\documentclass[article]{jss}
```
**Notes**: The class line defines four mutually-exclusive publication types (jss.cls:37-44); one must be selected.
Class-option default: `\@articletrue` at jss.cls:26 means `article` is the silent default if no option is
specified. If multiple mutually-exclusive options are specified, the last one wins (jss.cls:37-44 call
\@articlefalse / \@codesnippettrue / etc sequentially). The rule flags the "wrong class" case
(\documentclass{article} with a \usepackage{jss} instead of \documentclass[...]{jss}).
---
### JSS-PRE-002
**Category**: `preamble` · **Severity**: `error` · **Auto-fixable**: no
Preamble defines \Address{} with author affiliation and contact
**Authority**: `jss_cls` → `jss.cls:\Address`
**Inspects**: `tex_files`
Example violation
```latex
\documentclass[article]{jss}
\author{Jane Doe\\University X}
\title{A short demo}
\begin{document}
```
Example fix
```latex
\documentclass[article]{jss}
\author{Jane Doe\\University X}
\title{A short demo}
\Address{
Jane Doe\\
University X\\
E-mail: \email{jane@example.org}
}
\begin{document}
```
---
### JSS-PRE-003
**Category**: `preamble` · **Severity**: `error` · **Auto-fixable**: yes
When \title{} contains LaTeX markup, preamble also defines \Plaintitle{} with the markup-free form
**Authority**: `jss_cls` → `jss.cls:\Plaintitle`
**Inspects**: `tex_files`
Example violation
```latex
\title{Regression Models in \proglang{R}}
```
Example fix
```latex
\title{Regression Models in \proglang{R}}
\Plaintitle{Regression Models in R}
```
**Notes**: jss.cls:82 defines \Plaintitle; article.tex:30 uses it. Rule fires only when \title{} contains a LaTeX
macro call (\proglang, \pkg, \code, \emph, \textit, etc). A plain-text \title{} does not require a
companion \Plaintitle{} — the two are identical in that case.
---
### JSS-PRE-004
**Category**: `preamble` · **Severity**: `error` · **Auto-fixable**: no
\Abstract{} is present and overrides the sentinel placeholder from jss.cls
**Authority**: `jss_cls` → `jss.cls:120`
**Inspects**: `tex_files`
Example violation
```latex
\documentclass[article]{jss}
\title{A short demo}
\begin{document}
\maketitle
Introduction...
```
Example fix
```latex
\documentclass[article]{jss}
\title{A short demo}
\Abstract{This paper demonstrates the linter on a minimal manuscript.}
\begin{document}
\maketitle
Introduction...
```
**Notes**: jss.cls:120 sets a sentinel "---!!!---an abstract is required---!!!---"; a real paper must override it.
---
### JSS-PRE-005
**Category**: `preamble` · **Severity**: `error` · **Auto-fixable**: no
\Keywords{} is present and overrides the sentinel placeholder from jss.cls
**Authority**: `jss_cls` → `jss.cls:197`
**Inspects**: `tex_files`
Example violation
```latex
\documentclass[article]{jss}
\Abstract{...}
\begin{document}
```
Example fix
```latex
\documentclass[article]{jss}
\Abstract{...}
\Keywords{regression, \proglang{R}, count data}
\begin{document}
```
**Notes**: jss.cls:197 sets a sentinel "---!!!---at least one keyword is required---!!!---"; a real paper must override it.
---
### JSS-PRE-006
**Category**: `preamble` · **Severity**: `warning` · **Auto-fixable**: yes
\Plaintitle, \Plainauthor, \Plainkeywords contain no LaTeX markup (PDF metadata must be plain text)
**Authority**: `jss_cls` → `jss.cls:\Plaintitle`
**Inspects**: `tex_files`
Example violation
```latex
\Plaintitle{Regression Models in \proglang{R}}
\Plainauthor{\textbf{Achim Zeileis}}
```
Example fix
```latex
\Plaintitle{Regression Models in R}
\Plainauthor{Achim Zeileis}
```
**Notes**: jss.cls:82/84/94 define the plain-text twin commands for PDF metadata (pdftitle, pdfauthor, pdfkeywords
via hyperref — see jss.cls:449-465). Any LaTeX macro inside these values lands verbatim in the PDF info
dictionary, producing strings like "Regression Models in \proglang{R}" in reader metadata panels.
---
### JSS-PRE-007
**Category**: `preamble` · **Severity**: `error` · **Auto-fixable**: yes
When \author{} contains LaTeX markup, preamble also defines \Plainauthor{} with the markup-free form
**Authority**: `jss_cls` → `jss.cls:\Plainauthor`
**Inspects**: `tex_files`
Example violation
```latex
\author{Achim Zeileis~\orcidlink{0000-0003-0918-3766}\\Universit\"at Innsbruck
\And Second Author\\Plus Affiliation}
```
Example fix
```latex
\author{Achim Zeileis~\orcidlink{0000-0003-0918-3766}\\Universit\"at Innsbruck
\And Second Author\\Plus Affiliation}
\Plainauthor{Achim Zeileis, Second Author}
```
**Notes**: jss.cls:84 defines \Plainauthor; jss.cls:121 sets its default to `\@author` (i.e., whatever is in
\author{} verbatim). When \author{} contains macros (\orcidlink, affiliation \\ separators, \textbf, …)
the default value leaks raw LaTeX into the PDF's pdfauthor metadata (jss.cls:449-465 via hyperref).
Rule fires only when \author{} contains a LaTeX macro call. Closes the §1.1 jss.cls:84 `\Plainauthor`
gap from the reviewer checklist. Severity matches JSS-PRE-003 (parallel case for \title ↔ \Plaintitle).
---
### JSS-PRE-008
**Category**: `preamble` · **Severity**: `error` · **Auto-fixable**: yes
When \Keywords{} contains LaTeX markup, preamble also defines \Plainkeywords{} with the markup-free form
**Authority**: `jss_cls` → `jss.cls:\Plainkeywords`
**Inspects**: `tex_files`
Example violation
```latex
\Keywords{JSS, style guide, comma-separated, not capitalized, \proglang{R}}
```
Example fix
```latex
\Keywords{JSS, style guide, comma-separated, not capitalized, \proglang{R}}
\Plainkeywords{JSS, style guide, comma-separated, not capitalized, R}
```
**Notes**: jss.cls:94 defines \Plainkeywords; jss.cls:153/161 set its default to `\@Keywords` verbatim. When
\Keywords{} contains a LaTeX macro, the default value leaks raw LaTeX into the PDF's pdfkeywords
metadata. Rule fires only when \Keywords{} contains a LaTeX macro call. Closes the §1.1 jss.cls:94
`\Plainkeywords` gap from the reviewer checklist.
---
### JSS-STRUCT-001
**Category**: `structure` · **Severity**: `warning` · **Auto-fixable**: no
Document ends with a summary / discussion section before the bibliography
**Authority**: `article_tex` → `article.tex:378`
**Inspects**: `tex_files`
Example violation
```latex
\section{Illustrations}
...
\bibliography{refs}
```
Example fix
```latex
\section{Illustrations}
...
\section{Summary and discussion}
...
\bibliography{refs}
```
**Notes**: DRAFT — reviewer flagged 2026-04-23 for either a better authority anchor or removal. Template comment at
article.tex:381 says "As usual …" (placeholder) which is weak grounding. Candidate for removal in the
next review round unless a firmer style-guide anchor surfaces.
---
### JSS-STRUCT-002
**Category**: `structure` · **Severity**: `warning` · **Auto-fixable**: yes
Acknowledgments section uses American spelling (not "Acknowledgements")
**Authority**: `article_tex` → `article.tex:407`
**Inspects**: `tex_files`
Example violation
```latex
\section*{Acknowledgements}
Thanks to everyone.
```
Example fix
```latex
\section*{Acknowledgments}
Thanks to everyone.
```
**Notes**: article.tex:407 carries the explicit template comment "note the AE spelling".
---
### JSS-STRUCT-003
**Category**: `structure` · **Severity**: `warning` · **Auto-fixable**: no
Appendix sections have proper titles instead of a bare "Appendix"
**Authority**: `article_tex` → `article.tex:438`
**Inspects**: `tex_files`
Example violation
```latex
\begin{appendix}
\section*{Appendix}
Additional proofs.
\end{appendix}
```
Example fix
```latex
\begin{appendix}
\section{More technical details}
Additional proofs.
\end{appendix}
```
---
### JSS-STRUCT-004
**Category**: `structure` · **Severity**: `error` · **Auto-fixable**: no
References are declared via \bibliography{} rather than a hand-written thebibliography environment
**Authority**: `style_guide` → `#what-are-the-most-important-style-guidelines-in-jss`
**Inspects**: `tex_files`
Example violation
```latex
\begin{thebibliography}{99}
\bibitem{knuth} Knuth 1984.
\end{thebibliography}
```
Example fix
```latex
\bibliography{refs}
```
---
### JSS-STRUCT-005
**Category**: `structure` · **Severity**: `warning` · **Auto-fixable**: yes
\author{} separates authors with \And or \AND (not lowercase \and)
**Authority**: `article_tex` → `article.tex:22`
**Inspects**: `tex_files`
Example violation
```latex
\author{Alice Smith \and Bob Jones}
```
Example fix
```latex
\author{Alice Smith \And Bob Jones}
```
**Notes**: article.tex:22-23 template comment specifies `\And` (inline separator) or `\AND` (line-break separator);
the lowercase `\and` is LaTeX's default but is not wired to jss.cls's title-block layout (jss.cls:339-344)
so it produces incorrect spacing between authors. Closes the §1.2 article.tex:22 gap from the reviewer
checklist.
---
### JSS-STRUCT-006
**Category**: `structure` · **Severity**: `warning` · **Auto-fixable**: yes
Appendix follows the bibliography with a \newpage (or \clearpage) separator
**Authority**: `article_tex` → `article.tex:430`
**Inspects**: `tex_files`
Example violation
```latex
\bibliography{refs}
\begin{appendix}
\section{More technical details}
...
\end{appendix}
```
Example fix
```latex
\bibliography{refs}
\newpage
\begin{appendix}
\section{More technical details}
...
\end{appendix}
```
**Notes**: article.tex:430 places an explicit `\newpage` between `\bibliography{refs}` (line 423) and the
`\begin{appendix}` env (line 432). Appendices start on a fresh page in JSS papers. The check fires when
both \bibliography{} and \begin{appendix} exist and there is no \newpage / \clearpage / \pagebreak
between them in source order. Closes the §1.2 article.tex:430 gap (reviewer flagged add-rule 2026-04-23).
---
### JSS-MARKUP-001
**Category**: `markup` · **Severity**: `warning` · **Auto-fixable**: yes
Programming-language names in prose are wrapped in \proglang{}
**Authority**: `jss_cls` → `jss.cls:\proglang`
**Inspects**: `tex_files`
Example violation
```latex
We compare implementations in R and Python.
```
Example fix
```latex
We compare implementations in \proglang{R} and \proglang{Python}.
```
**Notes**: Style guide SG-005 mirrors this. jss.cls:476 defines \proglang as \textsf. Cross-checked against
terms.LANGUAGES. FP-reduction strategies required for reasonable precision:
* Mask math-mode content — "let $R$ be the covariance matrix" must not flag R as a language.
* Skip Pascal — nobody uses it in JSS manuscripts, FP rate too high.
* Filter out initials — "J. R. Statistical Society" has R as an initial, not the language.
* Only scan plain body text (not \section titles, not \code, not verbatim envs).
---
### JSS-MARKUP-002
**Category**: `markup` · **Severity**: `warning` · **Auto-fixable**: yes
Software-package names in prose are wrapped in \pkg{}
**Authority**: `jss_cls` → `jss.cls:\pkg`
**Inspects**: `tex_files`
Example violation
```latex
The MASS package provides \fct{glm.nb}.
```
Example fix
```latex
The \pkg{MASS} package provides \fct{glm.nb}.
```
**Notes**: Style guide SG-005 mirrors this. Cross-checked against terms.R_PACKAGES so the rule does not false-positive on normal English words.
---
### JSS-MARKUP-003
**Category**: `markup` · **Severity**: `warning` · **Auto-fixable**: yes
Inline function, argument, command names, and R sentinel values are wrapped in \code{}
**Authority**: `jss_cls` → `jss.cls:\code`
**Inspects**: `tex_files`
Example violation
```latex
The glm() function takes a family argument and may return NULL.
```
Example fix
```latex
The \code{glm()} function takes a \code{family} argument and may return \code{NULL}.
```
**Notes**: Style guide SG-030 mirrors this. Reviewer feedback on jss5342 (R5-r3) explicitly required NULL -> \code{NULL} throughout Table 3, motivating the R-sentinel-value coverage.
---
### JSS-MARKUP-004
**Category**: `markup` · **Severity**: `warning` · **Auto-fixable**: yes
Section titles containing markup supply a plain-text shim via \section[plain]{markup}
**Authority**: `style_guide` → `#my-latex-paper-does-not-compile-when-there-is-jss-markup-in-section-titles-what-should-i-do`
**Inspects**: `tex_files`
Example violation
```latex
\section{Regression in \proglang{R}}
```
Example fix
```latex
\section[Regression in R]{Regression in \proglang{R}}
```
---
### JSS-CITE-002
**Category**: `citations` · **Severity**: `warning` · **Auto-fixable**: no
First occurrence of a software package has a citation within the same paragraph
**Authority**: `style_guide` → `#what-are-the-most-important-style-guidelines-in-jss`
**Inspects**: `tex_files`
Example violation
```latex
We fit the model using \pkg{mgcv}.
```
Example fix
```latex
We fit the model using \pkg{mgcv} \citep{Wood:2006}.
```
**Notes**: Strict same-paragraph definition: "paragraph" is the token span bounded by char nodes containing blank
lines (`\n\n`) or by environment / group boundaries. The check: first \pkg{X} mention per distinct X
requires a \cite / \citet / \citep / \citealp / \citealt / \citeauthor / \citeyear macro within the same
paragraph, either before or after \pkg{X}. Subsequent \pkg{X} mentions are silent even if uncited
(package already introduced).
---
### JSS-CITE-003
**Category**: `citations` · **Severity**: `warning` · **Auto-fixable**: yes
Avoid bracket-in-bracket citation forms like (\cite{...}); use \citep{...} instead
**Authority**: `style_guide` → `#what-are-the-different-cite-citet-citep-commands-about`
**Inspects**: `tex_files`
Example violation
```latex
Regression models (\cite{Cameron+Trivedi:2013}) are common.
```
Example fix
```latex
Regression models \citep{Cameron+Trivedi:2013} are common.
```
---
### JSS-CITE-004
**Category**: `citations` · **Severity**: `warning` · **Auto-fixable**: no
Citations use natbib commands (\cite, \citet, \citep, \citealp) rather than hardcoded author-year text
**Authority**: `jss_cls` → `jss.cls:62`
**Inspects**: `tex_files`
Example violation
```latex
The method of (Knuth, 1984) predates this work.
```
Example fix
```latex
The method of \citet{Knuth1984} predates this work.
```
**Notes**: jss.cls:62 loads natbib in author-year mode; hardcoded references bypass the bibliography and cannot be
back-linked to refs.bib. The regex-based match MUST mask:
* Content inside \code{}, \verb{}, \url{} — parenthetical years inside literal strings are not
citations (e.g., \code{as.Date("2020-01-01")} must not flag).
* Content inside verbatim, Code, CodeInput, CodeOutput, Sinput, Soutput, Scode environments.
* Bibliography-rendering envs (thebibliography, BibTeX output).
---
### JSS-REFS-001
**Category**: `references` · **Severity**: `warning` · **Auto-fixable**: no
BibTeX entries carry a year field so natbib author-year citations render correctly
**Authority**: `style_guide` → `#what-are-the-most-important-style-guidelines-in-jss`
**Inspects**: `bib_files`
Example violation
```bibtex
@article{Knuth1984,
author = {Donald Knuth},
title = {Literate Programming},
journal = {The Computer Journal}
}
```
Example fix
```bibtex
@article{Knuth1984,
author = {Donald Knuth},
title = {Literate Programming},
journal = {The Computer Journal},
year = {1984}
}
```
**Notes**: Retrofit of the Step 1 smoke rule bib_001_year.py. natbib in author-year mode (jss.cls:62) emits "(????)" when year is missing.
---
### JSS-REFS-003
**Category**: `references` · **Severity**: `info` · **Auto-fixable**: no
BibTeX entries include a doi field where one is available (advisory)
**Authority**: `article_tex` → `article.tex:421`
**Inspects**: `bib_files`
Example violation
```bibtex
@article{Knuth1984,
author = {Donald Knuth},
title = {Literate Programming},
journal = {The Computer Journal},
year = {1984}
}
```
Example fix
```bibtex
@article{Knuth1984,
author = {Donald Knuth},
title = {Literate Programming},
journal = {The Computer Journal},
year = {1984},
doi = {10.1093/comjnl/27.2.97}
}
```
**Notes**: Advisory-only. Fires on article / inproceedings / incollection / book entry types lacking a `doi` field.
The rule cannot verify "where available" — some entries legitimately have no DOI (older journals, book
chapters, technical reports). `info` severity acknowledges the uncertainty and prompts the author to
double-check rather than declaring a violation.
---
### JSS-REFS-004
**Category**: `references` · **Severity**: `warning` · **Auto-fixable**: no
BibTeX titles use JSS markup (\proglang, \pkg, \code) for language and package names
**Authority**: `style_guide` → `#how-to-cite-r-packages`
**Inspects**: `bib_files`
Example violation
```bibtex
@manual{MASS,
title = {MASS: Support Functions for the book Modern Applied Statistics with S},
year = {2023}
}
```
Example fix
```bibtex
@manual{MASS,
title = {\pkg{MASS}: Support Functions for the book Modern Applied Statistics with \proglang{S}},
year = {2023}
}
```
---
### JSS-REFS-005
**Category**: `references` · **Severity**: `warning` · **Auto-fixable**: no
Journal titles in BibTeX entries are not abbreviated
**Authority**: `article_tex` → `article.tex:473`
**Inspects**: `bib_files`
Example violation
```bibtex
@article{Demo,
author = {Jane Doe},
title = {On Counting},
journal = {J. Stat. Softw.},
year = {2020}
}
```
Example fix
```bibtex
@article{Demo,
author = {Jane Doe},
title = {On Counting},
journal = {Journal of Statistical Software},
year = {2020}
}
```
**Notes**: Template comment at article.tex:473 pins this: "Journal titles should not be abbreviated and in title case."
This rule covers the not-abbreviated half; JSS-REFS-007 covers the title-case half. Heuristic — flag journal
fields that contain periods or obvious abbreviations (J\.|Jnl\.|Proc\.|Trans\.).
---
### JSS-REFS-006
**Category**: `references` · **Severity**: `warning` · **Auto-fixable**: no
BibTeX titles are in title style — loose heuristic (flags lowercase first word or unusual mixed case)
**Authority**: `style_guide` → `#what-are-the-most-important-style-guidelines-in-jss`
**Inspects**: `bib_files`
Example violation
```bibtex
@article{Demo,
title = {literate Programming: a Survey},
year = {2020}
}
```
Example fix
```bibtex
@article{Demo,
title = {Literate Programming: A Survey},
year = {2020}
}
```
**Notes**: Title-case heuristic. Checks: first word must be capitalised; word after a colon or hyphen must be
capitalised (style-guide SG-013 cross-reference); principal words must be capitalised. Also flags
entirely-lowercase multi-word titles (the role formerly split into JSS-REFS-002, retired 2026-06-14),
while exempting single coined words. Tuned via the precision gate on the real corpus.
---
### JSS-REFS-007
**Category**: `references` · **Severity**: `warning` · **Auto-fixable**: no
Journal titles in BibTeX entries are in title case
**Authority**: `article_tex` → `article.tex:473`
**Inspects**: `bib_files`
Example violation
```bibtex
@article{Demo,
author = {Jane Doe},
title = {On Counting},
journal = {journal of statistical software},
year = {2020}
}
```
Example fix
```bibtex
@article{Demo,
author = {Jane Doe},
title = {On Counting},
journal = {Journal of Statistical Software},
year = {2020}
}
```
**Notes**: article.tex:473 mandates "Journal titles should not be abbreviated and in title case." JSS-REFS-005 covers
the not-abbreviated half; this rule covers the title-case half. Same principal-word heuristic as REFS-006.
---
### JSS-BIBTEX-001
**Category**: `bibtex` · **Severity**: `error` · **Auto-fixable**: no
Every BibTeX entry has a non-empty citation key
**Authority**: `style_guide` → `#how-to-cite-r-packages`
**Inspects**: `bib_files`
Example violation
```bibtex
@article{,
author = {Donald Knuth},
title = {Literate Programming},
year = {1984}
}
```
Example fix
```bibtex
@article{Knuth1984,
author = {Donald Knuth},
title = {Literate Programming},
year = {1984}
}
```
**Notes**: Style-guide SG-017 requires BibTeX to be valid. An entry without a key cannot be cited and fails BibTeX validation.
---
### JSS-BIBTEX-002
**Category**: `bibtex` · **Severity**: `error` · **Auto-fixable**: no
BibTeX citation keys are unique within the database
**Authority**: `style_guide` → `#how-to-cite-r-packages`
**Inspects**: `bib_files`
Example violation
```bibtex
@article{Knuth1984,
author = {Donald Knuth},
year = {1984}
}
@book{Knuth1984,
author = {Donald Knuth},
year = {1984}
}
```
Example fix
```bibtex
@article{Knuth1984a,
author = {Donald Knuth},
year = {1984}
}
@book{Knuth1984b,
author = {Donald Knuth},
year = {1984}
}
```
---
### JSS-BIBTEX-003
**Category**: `bibtex` · **Severity**: `error` · **Auto-fixable**: no
BibTeX entries carry the fields required for their entry type (article, book, inproceedings, …)
**Authority**: `style_guide` → `#how-to-cite-r-packages`
**Inspects**: `bib_files`
Example violation
```bibtex
@article{Demo,
author = {Jane Doe},
year = {2020}
}
```
Example fix
```bibtex
@article{Demo,
author = {Jane Doe},
title = {On Counting},
journal = {Journal of Statistical Software},
year = {2020}
}
```
**Notes**: Required-field matrix (per BibTeX standard + JSS SG-017 "valid BibTeX"):
* article → author, title, journal, year
* book → author|editor, title, publisher, year
* inproceedings → author, title, booktitle, year
* incollection → author, title, booktitle, publisher, year
* inbook → author|editor, title, chapter|pages, publisher, year
* manual → title
* mastersthesis → author, title, school, year
* phdthesis → author, title, school, year
* techreport → author, title, institution, year
* unpublished → author, title, note
* misc → (no required fields)
Missing required fields produce silently malformed citation output.
---
### JSS-BIBTEX-004
**Category**: `bibtex` · **Severity**: `warning` · **Auto-fixable**: no
Entries with 6+ authors use \shortcites{} or the shortnames class option is enabled
**Authority**: `jss_cls` → `jss.cls:45`
**Inspects**: `bib_files`
Example violation
```bibtex
% preamble does NOT set [shortnames] on \documentclass[article]{jss}
@article{Many,
author = {A. Smith and B. Jones and C. Chen and D. Lopez and E. Patel and F. Nguyen and G. Walker},
title = {Study},
journal = {Stats},
year = {2020}
}
% main text:
Following \citet{Many} we extend...
```
Example fix
```bibtex
\documentclass[article,shortnames]{jss}
% ... same bib entry, main text:
Following \citet{Many} we extend...
```
**Notes**: natbib's default author-year output for 6+-author entries produces "A. Smith, B. Jones, C. Chen, D. Lopez,
E. Patel, F. Nguyen, and G. Walker (2020)" which overflows line wrapping and clutters the text.
jss.cls:45 defines the `shortnames` class option (passed through to natbib) that collapses to
"Smith et al. (2020)" on first mention. Alternative: \shortcites{key} in the preamble for per-entry
control. The rule fires when an entry has ≥6 authors AND the preamble lacks both mitigations.
---
### JSS-BIBTEX-005
**Category**: `bibtex` · **Severity**: `error` · **Auto-fixable**: no
No BibTeX field key is repeated within a single entry
**Authority**: `style_guide` → `#how-to-cite-r-packages`
**Inspects**: `bib_files`
Example violation
```bibtex
@article{Knuth1984,
author = {Donald Knuth},
author = {Leslie Lamport},
title = {Literate Programming},
journal = {Journal of Examples},
year = {1984}
}
```
Example fix
```bibtex
@article{Knuth1984,
author = {Donald Knuth and Leslie Lamport},
title = {Literate Programming},
journal = {Journal of Examples},
year = {1984}
}
```
**Notes**: Style-guide SG-017 requires valid BibTeX. A field repeated within one
entry (e.g., two `author =` lines) is malformed: BibTeX keeps only the
first occurrence and silently drops the rest, so the rendered citation
loses data. bibtexparser routes such an entry into `failed_blocks` as a
DuplicateFieldKeyBlock; the parser treats it as recoverable (the kept
first value still parses) rather than a fatal JSS-PARSE-000, and this
rule reports the dropped duplicate field(s).
---
### JSS-NAME-001
**Category**: `naming` · **Severity**: `warning` · **Auto-fixable**: yes
Programming-language names use their canonical capitalisation
**Authority**: `style_guide` → `#which-naming-conventions-are-used-for-software-journal-and-publisher-names-in-jss`
**Inspects**: `tex_files`
Example violation
```latex
We implemented a prototype in JAVA and also in matlab.
```
Example fix
```latex
We implemented a prototype in \proglang{Java} and also in \proglang{MATLAB}.
```
**Notes**: Style guide SG-044..SG-047 pin "Fortran", "Java", "MATLAB", "S-PLUS". Lookup goes through terms.canonical_form(); the rule only fires on tokens the shared list knows about.
---
### JSS-NAME-002
**Category**: `naming` · **Severity**: `warning` · **Auto-fixable**: yes
Publisher and journal names follow JSS conventions (e.g., "Springer-Verlag", "The Annals of Statistics")
**Authority**: `style_guide` → `#which-naming-conventions-are-used-for-software-journal-and-publisher-names-in-jss`
**Inspects**: `bib_files`
Example violation
```latex
@book{Example,
publisher = {Springer},
year = {2020}
}
```
Example fix
```latex
@book{Example,
publisher = {Springer-Verlag},
year = {2020}
}
```
**Notes**: Style guide SG-048..SG-052 pin the canonical forms for a handful of journals and publishers that appear frequently in JSS references.
---
### JSS-CAP-001
**Category**: `capitalization` · **Severity**: `warning` · **Auto-fixable**: no
\title{} is in title style (principal words capitalised)
**Authority**: `style_guide` → `#what-are-the-most-important-style-guidelines-in-jss`
**Inspects**: `tex_files`
Example violation
```latex
\title{regression models for count data in r}
```
Example fix
```latex
\title{Regression Models for Count Data in \proglang{R}}
```
**Notes**: Style guide SG-007 and SG-014. Pragmatic heuristic: flag titles whose first word is lowercase OR whose
every word is lowercase. Common function words (of, and, the, in, for, a, an, to, with) may stay
lowercase; principal words should be capitalised. Title style also requires capitalising the first word
after a colon ("Do capitalize the first word after a colon") — flagged even when that word is a stop word
the principal-word check would otherwise skip, with the same exemptions as CAP-002's colon check
(markup/math-wrapped token, non-letter start, known lowercase-canonical package/language name). Full
dictionary-based title-case validation is deferred; the narrow heuristic ships first and is tuned via the
precision gate on the real corpus.
---
### JSS-CAP-002
**Category**: `capitalization` · **Severity**: `warning` · **Auto-fixable**: no
Section titles are in sentence style (first word capitalised; others lowercase except proper names)
**Authority**: `style_guide` → `#what-are-the-most-important-style-guidelines-in-jss`
**Inspects**: `tex_files`
Example violation
```latex
\section{Models And Software}
```
Example fix
```latex
\section{Models and software}
```
**Notes**: Style guide SG-009. Also covers SG-013 "In sentence style, capitalise only the first word and the first
word after a colon or a hyphen; proper names remain uppercase". The rule enforces TWO directions:
(1) over-capitalisation — flag section titles with a capitalised non-first non-proper word (cross-checked
against terms.LANGUAGES and terms.R_PACKAGES); (2) capital-after-colon — flag when the first token after a
colon starts lowercase, exempting a markup/math-wrapped token (\pkg{}/\code{}/\proglang{}/$...$), a token
starting with a non-letter, and known lowercase-canonical package/language names (mirrors JSS-REFS-006's
bib-title after-colon check). The capital-after-HYPHEN half of SG-013 is DELIBERATELY NOT enforced: read
literally it would demand "Model-Based clustering", contradicting the universal compound-modifier
convention, so the colon is enforced and the hyphen is documented as an intentional narrowing. Tuned via
the precision gate.
---
### JSS-CAP-004
**Category**: `capitalization` · **Severity**: `warning` · **Auto-fixable**: no
\Keywords{} is comma-separated and in sentence case
**Authority**: `article_tex` → `article.tex:48`
**Inspects**: `tex_files`
Example violation
```latex
\Keywords{JSS, Style Guide, Comma-Separated}
```
Example fix
```latex
\Keywords{JSS, style guide, comma-separated}
```
**Notes**: article.tex:48 carries the template comment "Should be comma-separated and in sentence case."
---
### JSS-TYPO-001
**Category**: `typography` · **Severity**: `warning` · **Auto-fixable**: yes
Figure and table captions end with a period
**Authority**: `style_guide` → `#how-to-format-figuretable-captions`
**Inspects**: `tex_files`
Example violation
```latex
\caption{\label{fig:quine} Frequency distribution for number of days absent}
```
Example fix
```latex
\caption{\label{fig:quine} Frequency distribution for number of days absent.}
```
---
### JSS-TYPO-002
**Category**: `typography` · **Severity**: `warning` · **Auto-fixable**: no
Figure / table captions avoid emphasis macros wrapping the whole caption (\emph, \textbf, \textit on full caption)
**Authority**: `style_guide` → `#how-to-format-figuretable-captions`
**Inspects**: `tex_files`
Example violation
```latex
\caption{\label{tab:ov} \emph{Overview of the regression models}.}
```
Example fix
```latex
\caption{\label{tab:ov} Overview of the regression models.}
```
**Notes**: Applies only to emphasis macros wrapping the whole caption (or the full non-label portion of it). Targeted
formatting on short phrases within a caption is allowed — e.g., italicising a Latin species name, a
journal title inside the caption, or a subsection label. The rule flags the "entire caption is one
\emph{...}" / "entire caption is one \textit{...}" pattern, not intra-caption markup.
---
### JSS-TYPO-003
**Category**: `typography` · **Severity**: `warning` · **Auto-fixable**: no
Tables do not use footnote-style annotations; annotations go in the caption
**Authority**: `style_guide` → `#how-to-format-figuretable-captions`
**Inspects**: `tex_files`
Example violation
```latex
\begin{table}
...\footnote{Significant at the 5\% level.}...
\end{table}
```
Example fix
```latex
\begin{table}
...
\caption{\label{tab:x} Results. Entries marked with an asterisk are significant at the 5\% level.}
\end{table}
```
---
### JSS-TYPO-004
**Category**: `typography` · **Severity**: `warning` · **Auto-fixable**: no
\caption{} appears after the figure / table content, not before
**Authority**: `style_guide` → `#how-to-format-figuretable-captions`
**Inspects**: `tex_files`
Example violation
```latex
\begin{figure}
\caption{\label{fig:x} Frequency distribution.}
\includegraphics{visualization}
\end{figure}
```
Example fix
```latex
\begin{figure}
\includegraphics{visualization}
\caption{\label{fig:x} Frequency distribution.}
\end{figure}
```
**Notes**: Style guide SG-021: "Captions appear below the corresponding figure/table." Closes the §1.3 SG-021 gap
from the reviewer checklist. Caption placement before content produces visual separation between the
caption and its target even when LaTeX compiles cleanly.
---
### JSS-ABBR-001
**Category**: `abbreviations` · **Severity**: `warning` · **Auto-fixable**: yes
Abbreviations are in uppercase without periods or additional formatting
**Authority**: `style_guide` → `#how-should-abbrevations-be-formatted`
**Inspects**: `tex_files`
Example violation
```latex
Data collected in the U.S.A. during 2020.
```
Example fix
```latex
Data collected in the USA during 2020.
```
---
### JSS-CODE-001
**Category**: `code_style` · **Severity**: `warning` · **Auto-fixable**: no
Verbatim / CodeInput blocks do not contain comments; comments belong in the surrounding LaTeX text
**Authority**: `style_guide` → `#how-should-code-be-formatted-in-the-manuscript`
**Inspects**: `tex_files`
Example violation
```latex
\begin{CodeInput}
R> m <- glm(y ~ x, family = poisson) # fit Poisson model
\end{CodeInput}
```
Example fix
```latex
We fit the Poisson model as follows.
\begin{CodeInput}
R> m <- glm(y ~ x, family = poisson)
\end{CodeInput}
```
---
### JSS-CODE-002
**Category**: `code_style` · **Severity**: `warning` · **Auto-fixable**: yes
R library() and data() calls quote their first argument
**Authority**: `style_guide` → `#miscellaneous`
**Inspects**: `tex_files`
Example violation
```latex
\begin{CodeInput}
R> library(MASS)
R> data(quine)
\end{CodeInput}
```
Example fix
```latex
\begin{CodeInput}
R> library("MASS")
R> data("quine")
\end{CodeInput}
```
---
### JSS-CODE-003
**Category**: `code_style` · **Severity**: `warning` · **Auto-fixable**: yes
Code samples use spaces around operators and after commas
**Authority**: `style_guide` → `#how-should-code-be-formatted-in-the-manuscript`
**Inspects**: `tex_files`
Example violation
```latex
\code{y=a+b*x}
```
Example fix
```latex
\code{y = a + b * x}
```
---
### JSS-WIDTH-001
**Category**: `code_width` · **Severity**: `warning` · **Auto-fixable**: no
Code input / output inside Sinput / CodeInput / CodeOutput environments fits within the configured column limit
**Authority**: `style_guide` → `#how-should-code-be-formatted-in-the-manuscript`
**Inspects**: `raw_source`
Example violation
```latex
\begin{CodeInput}
R> summary(glm(Days ~ (Eth + Sex + Age + Lrn)^2, data = quine, family = poisson, control = glm.control(maxit = 100)))
\end{CodeInput}
```
Example fix
```latex
\begin{CodeInput}
R> summary(glm(Days ~ (Eth + Sex + Age + Lrn)^2, data = quine,
+ family = poisson,
+ control = glm.control(maxit = 100)))
\end{CodeInput}
```
**Notes**: Retrofit of the Step 1 smoke rule src_001_width.py. Line-length checks are byte-level, not structural —
Constitution §II carve-out applies (line width is intrinsically textual). Default column limit is 80,
tracking SG-031's "fits within normal textwidth"; the limit is **configurable** via ToolConfig so authors
using a wider code-block style can set their own max (per reviewer 2026-04-23).
---
### JSS-OPER-001
**Category**: `operators` · **Severity**: `warning` · **Auto-fixable**: yes
Symbol-plus-noun constructs like p-value and t-statistic are typeset as $p$~value and $t$~statistic (tie, no hyphen)
**Authority**: `style_guide` → `#miscellaneous`
**Inspects**: `tex_files`
Example violation
```latex
The p-value is below 0.05 and the t-statistic exceeds 2.
```
Example fix
```latex
The $p$~value is below 0.05 and the $t$~statistic exceeds 2.
```
---
### JSS-OPER-002
**Category**: `operators` · **Severity**: `warning` · **Auto-fixable**: yes
Transpose is typeset with \top rather than a superscript prime or literal T
**Authority**: `style_guide` → `#miscellaneous`
**Inspects**: `tex_files`
Example violation
```latex
The design matrix is $X^T X$.
```
Example fix
```latex
The design matrix is $X^\top X$.
```
---
### JSS-OPER-003
**Category**: `operators` · **Severity**: `warning` · **Auto-fixable**: yes
Display equations have no blank lines immediately before or after (use % to suppress paragraph breaks)
**Authority**: `article_tex` → `article.tex:154`
**Inspects**: `tex_files`
Example violation
```latex
The mean is given by
\begin{equation} \label{eq:mean}
\log(\mu) = x^\top \beta.
\end{equation}
where the coefficients are estimated by ML.
```
Example fix
```latex
The mean is given by
%
\begin{equation} \label{eq:mean}
\log(\mu) = x^\top \beta.
\end{equation}
%
where the coefficients are estimated by ML.
```
**Notes**: article.tex:161-165 template comment says "no spaces before/after equations so that 'normal' spacing is
used and not a new paragraph started". Carve-out: when the equation's content ends with a period (full
sentence ending inside the display), the following paragraph is legitimately ending and the surrounding
`%` is unnecessary — the rule MUST NOT fire in that case. Detection: inspect the last non-whitespace
token inside the equation body for a trailing `.`.
---
### JSS-OPER-004
**Category**: `operators` · **Severity**: `warning` · **Auto-fixable**: yes
Expectation / variance / covariance / probability use jss.cls shortcuts \E, \VAR, \COV, \Prob
**Authority**: `jss_cls` → `jss.cls:484`
**Inspects**: `tex_files`
Example violation
```latex
The expectation $\mathbb{E}[X]$ and variance $\mathsf{Var}(X)$.
```
Example fix
```latex
The expectation $\E[X]$ and variance $\VAR(X)$.
```
**Notes**: jss.cls:484-487 define \E, \VAR, \COV, \Prob (all as \mathsf). Ad-hoc alternatives (\mathbb{E},
\mathrm{Var}, \operatorname{Cov}, \mathrm{P}) produce visually inconsistent output across JSS papers.
The rule flags \mathbb{E}, \mathsf{Var}, \mathrm{Var}, \operatorname{Cov}, \mathrm{P}, \Pr and their
common siblings inside math mode.
---
### JSS-XREF-001
**Category**: `crossrefs` · **Severity**: `warning` · **Auto-fixable**: no
Figures and tables are referenced via \ref{} rather than by manual numbering
**Authority**: `style_guide` → `#what-are-the-most-important-style-guidelines-in-jss`
**Inspects**: `tex_files`
Example violation
```latex
See Figure 2 for the frequency distribution.
```
Example fix
```latex
See Figure~\ref{fig:quine} for the frequency distribution.
```
**Notes**: This rule covers only the cross-reference *form*: a prose mention of a float by hardcoded number
("Figure 2", "Table 3") should instead use Figure~\ref{...} / Table~\ref{...}. The complementary
orphan check — that every captioned figure/table actually carries a \label{} and is referenced from
the text — lives in JSS-XREF-005 (the float analogue of JSS-XREF-004 for equations).
---
### JSS-XREF-002
**Category**: `crossrefs` · **Severity**: `info` · **Auto-fixable**: yes
Equation references prefer Equation~\ref{...} (capitalised) over bare (\ref{...}) or \eqref{...}
**Authority**: `style_guide` → `#miscellaneous`
**Inspects**: `tex_files`
Example violation
```latex
See (\ref{eq:mean}) or \eqref{eq:mean} for the derivation.
```
Example fix
```latex
See Equation~\ref{eq:mean} for the derivation.
```
**Notes**: SG-060 makes this advisory for manuscripts with many equation references; the rule ships at info severity
and is easy to suppress per-paper.
---
### JSS-XREF-003
**Category**: `crossrefs` · **Severity**: `warning` · **Auto-fixable**: no
Cross-references to subsections use "Section x.y" rather than "Subsection x.y"
**Authority**: `style_guide` → `#miscellaneous`
**Inspects**: `tex_files`
Example violation
```latex
See Subsection 3.2 for details.
```
Example fix
```latex
See Section~\ref{sec:details} for details.
```
---
### JSS-XREF-004
**Category**: `crossrefs` · **Severity**: `info` · **Auto-fixable**: no
Numbered equations carry \label{} and are referenced from the text
**Authority**: `style_guide` → `#what-are-the-most-important-style-guidelines-in-jss`
**Inspects**: `tex_files`
Example violation
```latex
\begin{equation}
\log(\mu) = x^\top \beta.
\end{equation}
```
Example fix
```latex
\begin{equation} \label{eq:mean}
\log(\mu) = x^\top \beta.
\end{equation}
The mean is given by Equation~\ref{eq:mean}.
```
**Notes**: Companion to JSS-XREF-001 for numbered equations only; info severity because unreferenced numbered
equations are a style nit, not a missing-callout signal (the reader still sees the equation in place).
`{equation*}` / unnumbered displays are out of scope — they have no counter to label.
---
### JSS-XREF-005
**Category**: `crossrefs` · **Severity**: `warning` · **Auto-fixable**: no
Figures and tables carry \label{} and are referenced from the text
**Authority**: `style_guide` → `#what-are-the-most-important-style-guidelines-in-jss`
**Inspects**: `tex_files`
Example violation
```latex
\begin{figure}
\includegraphics{quine}
\caption{Frequency distribution.}
\end{figure}
```
Example fix
```latex
\begin{figure}
\includegraphics{quine}
\caption{Frequency distribution.}
\label{fig:quine}
\end{figure}
Figure~\ref{fig:quine} shows the frequency distribution.
```
**Notes**: The float analogue of JSS-XREF-004 (which covers numbered equations). Walks `figure` / `table`
environments (and their starred variants) that carry a `\caption` — i.e. numbered floats — and fires
when the float has no `\label{}`, or has label(s) none of which is referenced anywhere via a
`\ref`-family macro (an orphan float, signalling a missing prose callout). Warning severity matches
JSS-XREF-001's reasoning: an unreferenced figure/table is a missing-callout signal, stronger than the
info-severity equation nit. Captionless (unnumbered) floats are out of scope — they have no counter to
label. JSS-XREF-001 separately covers the reference *form* (use `\ref{}`, not a hardcoded number).
---
### JSS-XREF-006
**Category**: `crossrefs` · **Severity**: `warning` · **Auto-fixable**: no
Figure and table floats carry a \caption{}
**Authority**: `style_guide` → `#what-are-the-most-important-style-guidelines-in-jss`
**Inspects**: `tex_files`
Example violation
```latex
\begin{figure}
\includegraphics{quine}
\end{figure}
```
Example fix
```latex
\begin{figure}
\includegraphics{quine}
\caption{Frequency distribution.}
\label{fig:quine}
\end{figure}
```
**Notes**: The precondition for JSS-XREF-005: a `figure` / `table` float (and starred variants) with no `\caption`
(or `\captionof`) is unnumbered and cannot be cross-referenced, so XREF-005 deliberately skips it. This
rule catches the missing caption itself. Sub-float environments (`subfigure`, `subtable`, `subfloat`,
`minipage`, `wrapfigure` / `wraptable`, sideways variants) are carved out: a panel nested inside a parent
float legitimately relies on the parent's caption. A float that contains a sub-float is therefore not
flagged for its own caption either, since the sub-float wrapper signals a composite figure whose caption
may sit on an inner panel.
---
### JSS-XREF-007
**Category**: `crossrefs` · **Severity**: `info` · **Auto-fixable**: yes
Cross-reference nouns are spelled out (Figure/Section/Table), not abbreviated (Fig./Sec./Tab.)
**Authority**: `style_guide` → `#miscellaneous`
**Inspects**: `tex_files`
Example violation
```latex
As shown in Fig.~\ref{fig:overview} and Sec.~\ref{sec:method}.
```
Example fix
```latex
As shown in Figure~\ref{fig:overview} and Section~\ref{sec:method}.
```
**Notes**: Fires only on an abbreviation (`Fig.` / `Figs.` / `Sec.` / `Secs.` / `Tab.` / `Tabs.`) immediately
preceding a `\ref` macro (across an optional `~`), so the `\ref` disambiguates it from unrelated
uses ("sec." = seconds). `\autoref` / `\cref` generate the noun themselves and are out of scope, as
is `Eq.` (JSS-XREF-002). Ships at info severity; auto-fixable (rewrites to the spelled-out noun with a
non-breaking space).
---
### JSS-HOUSE-001
**Category**: `house_style` · **Severity**: `warning` · **Auto-fixable**: yes
"e.g." and "i.e." are followed by a comma so LaTeX does not treat the period as a sentence end
**Authority**: `style_guide` → `#miscellaneous`
**Inspects**: `tex_files`
Example violation
```latex
Regression models (e.g. Poisson) are used here.
```
Example fix
```latex
Regression models (e.g., Poisson) are used here.
```
---
### JSS-HOUSE-002
**Category**: `house_style` · **Severity**: `warning` · **Auto-fixable**: yes
Book editions are indicated as 2nd, 3rd, etc., not as "second" or "2e"
**Authority**: `style_guide` → `#miscellaneous`
**Inspects**: `bib_files`
Example violation
```latex
@book{Example,
edition = {second},
year = {2020}
}
```
Example fix
```latex
@book{Example,
edition = {2nd},
year = {2020}
}
```
---
### JSS-HOUSE-003
**Category**: `house_style` · **Severity**: `info` · **Auto-fixable**: yes
Preamble avoids loading LaTeX packages that jss.cls already provides (graphicx, xcolor, ae, fancyvrb, hyperref)
**Authority**: `jss_cls` → `jss.cls:54`
**Inspects**: `tex_files`
Example violation
```latex
\documentclass[article]{jss}
\usepackage{graphicx}
\usepackage{hyperref}
```
Example fix
```latex
\documentclass[article]{jss}
```
**Notes**: jss.cls:54 loads graphicx/xcolor/ae/fancyvrb and jss.cls:254 loads hyperref; duplicate \usepackage calls are silently ignored by LaTeX but clutter the preamble. Style guide SG-002 ("keep LaTeX code as simple as possible") backs this.
---
### JSS-PROJECT-001
**Category**: `project` · **Severity**: `error` · **Auto-fixable**: no
A cycle exists in the \input/\include/\subfile/\bibliography reference graph
**Authority**: `author_instructions` → `multi-file-projects`
**Inspects**: `tex_files`
Example violation
```latex
% a.tex
\input{b}
% b.tex
\input{a}
```
Example fix
```latex
% a.tex
\input{b}
% b.tex
No back-reference to a.tex here.
```
---
### JSS-PROJECT-002
**Category**: `project` · **Severity**: `error` · **Auto-fixable**: no
A \input/\include/\subfile/\bibliography target could not be found
**Authority**: `author_instructions` → `multi-file-projects`
**Inspects**: `tex_files`, `bib_files`
Example violation
```latex
\input{missing-file}
```
Example fix
```latex
\input{existing-file}
```
---