# RR turns an EBNF grammar into a railroad diagram, and also rewrites the grammar while it is there

> RR is a railroad diagram generator that takes W3C-style EBNF and produces syntax diagrams, either through a browser GUI or in batch mode from the command line, and it applies factorization and elimination of direct recursion on the way. It suits a language designer documenting a grammar, and it is a Java program distributed as a war file rather than a library you embed in a build.

**GuntherRademacher/rr** — RR - Railroad Diagram Generator

- Repository: https://github.com/GuntherRademacher/rr
- Website: https://www.bottlecaps.de/rr/ui
- Stars: 552 · Forks: 55
- Language: XQuery
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/guntherrademacher-rr

## A grammar in, a syntax diagram out

RR is a generator of syntax diagrams, also known as railroad diagrams. It is described as a self-contained tool with both a browser-based GUI and a batch mode, and that pairing is the shape of the whole project: one program that can be handed a grammar by a person or by a script.

The input format is W3C-style EBNF. The README points at the W3C specification of the notation and notes that some other representations, including some parser generator input notations, can be converted to W3C-style using the ebnf-convert Grammar Converter, which is maintained by the same author and available on GitHub. That conversion step is a separate program, and knowing it exists is part of understanding the workflow: RR reads one notation well, and other tools' notations are a conversion problem rather than a parsing problem.

The output is SVG. The repository ships two example diagrams taken from the Python grammar, one for the if_stmt production and one for try_stmt, and those two files are the clearest statement of the quality you get. A railroad diagram is a picture of the grammar's structure, with the alternatives and repetitions laid out as paths that a reader can follow, which is a different and often clearer way to present a syntax than a formal BNF listing.

The repository is small by design: a src/ directory, build.gradle, settings.gradle, the Gradle wrapper, and the two example SVGs at the root next to rr.svg.

## The grammar transformation is the part most people miss

RR does more than draw. Besides generating diagrams from EBNF rules, it can perform some grammar transformation, and the README names two: factorization and elimination of direct recursion. The stated effect is that to some extent this transforms BNF to EBNF, yielding more compact diagrams.

That is the interesting engineering claim. A diagram drawn directly from a naive BNF grammar is long and repetitive, because the same alternatives get redrawn at every level. Factoring pulls a common prefix out of a production so it can be drawn once, and eliminating direct recursion rewrites a rule that refers to itself so it no longer needs a loop back edge. Both operations shrink the picture, and both change the grammar text, so the tool is a grammar rewriter with a diagram as its output format.

This is why RR is worth a look even if you have another way to produce diagrams. If your grammar has drifted into a form with a lot of repeated structure, running it through RR gives you a smaller diagram and a tidier grammar, and you can diff the result to see what the transformation did.

The caveat is that the transformation is described in the README in one sentence, with no flags documented for controlling it or for inspecting an intermediate result. The README does not document how to turn the transformations off, or how to see the rewritten grammar without a diagram, so treat the behaviour as something to check against your own grammar rather than a feature you can tune.

## Running it: a Java war file with a GUI and a batch mode

Distribution is a .zip containing a .war file. The war file can be deployed in servlet containers like Tomcat or Jetty for serving the GUI, and that deployment is what makes up the webapp running on the original website at bottlecaps.de/rr/ui.

The war file is also a Java executable war, so it can be started standalone from the command line, and two tasks are available in that mode. The first is serving the GUI.

```bash
   java -jar rr.war -gui
```

The second is batch diagram generation, where you pass the grammar file.

```bash
   java -jar rr.war grammar.ebnf
```

And running it with no arguments at all lists the full set of available options.

```bash
   java -jar rr.war
```

So the tool needs a JRE and nothing else, and you can produce a diagram from a file in a script without ever opening the interface. The presence of a documented option listing is a small quality signal, and it is also the place to look for the flags this README does not mention.

If you would rather not host it, the hosted GUI at www.bottlecaps.de/rr/ui is the same webapp, and using it means uploading your grammar to somebody else's server, which is worth weighing if the grammar describes a protocol you intend to keep private.

## Building from source and using RR as a dependency

Building the distribution zip from the repository requires JDK 17 or higher. In the project folder, the Gradle wrapper does the work.

```bash
gradlew
```

The wrapper is committed, so the build does not depend on a Gradle version you have installed, which is the usual reason to prefer the wrapper over a system Gradle.

For Java projects that want the generator as part of a build rather than as a separate tool, RR is on Maven Central under the groupId de.bottlecaps.rr, with two artifactIds. rr-webapp is the artifact for rr.war, and rr-lib is the artifact for rr.jar, which can be added to other projects as a dependency.

That distinction is the one worth remembering. rr-lib is the library form, and if you are generating diagrams as part of a documentation pipeline, that is the artifact you want. rr-webapp is the deployment form. The README does not show a code sample for calling rr-lib, so you would be working from the API surface yourself rather than from a documented example.

The build also uses Gradle-License-Report, which is why the project can publish a dependency licence list, and the README credits Saxon-HE for XSLT processing, TagSoup for HTML parsing, Apache Batik for SVG rendering, and the Ace Editor for the editing surface in the browser. Batik and Ace in particular explain why the tool can render diagrams in the browser at all rather than requiring a separate drawing step.

## Maintenance, licensing and what the project is not

The project is not archived and the last push was on 2026-10-15. The release list shows v2.6 on 2025-12-31, v2.5 on 2025-05-26 and v2.4 on 2025-04-03, so the project ships on an occasional schedule with a major version every year or so.

The licence is Apache 2, with the copyright line reading Copyright (c) 2010-2026 Gunther Rademacher. For an adopter this is about as permissive as it gets: you can vendor the tool into a commercial product, modify it, and redistribute it, and the obligation is to keep the notice. There is no copyleft condition that would reach code you link against it.

Now the honest limits. RR reads W3C-style EBNF and nothing else, so a grammar in BNF, ANTLR notation, PEG, or a parser generator's own input format needs converting first, and the conversion is a separate tool with its own limitations. The batch mode is described in the README with a single example command and no output naming options, so wiring it into a build means working out for yourself where the SVG lands and what to do with it. And the GUI is a Java webapp, which means a Java runtime on whatever machine you serve it from, unless you use the hosted version.

The closest alternative in approach is a general-purpose diagram tool driven by a script. You would write the railroad layout yourself, using a tool that draws arbitrary boxes and lines. The difference is that RR derives the layout from the grammar, so the diagram cannot drift out of sync with the grammar, and it applies the factorization and recursion removal that would otherwise be manual work. What you give up is control over the drawing, since the output style is Batik's SVG and not something you design.

## Conclusion

RR fits a language designer who already has a W3C-style EBNF grammar and needs a readable diagram for a specification or manual page, and who is willing to run a Java webapp. It does not fit a team that wants the diagram generation wired into a documentation build, because there is no documented command line API beyond the batch mode described in the README, and it does not fit grammars written in a notation RR does not read. Check first that your grammar parses as W3C-style EBNF, converting it with ebnf-convert if it does not, and decide whether you want the Apache 2 licensed war file on your own server or the hosted GUI at bottlecaps.de.

## FAQ

### What is RR and what does it generate?

RR is a railroad diagram generator, also known as a syntax diagram generator. It reads a grammar in W3C-style EBNF and produces syntax diagrams as SVG, with example outputs for the Python if_stmt and try_stmt productions included in the repository.

### How do I run RR from the command line?

The distribution zip contains a Java executable war, so you start it with `java -jar rr.war -gui` to serve the browser interface or `java -jar rr.war grammar.ebnf` for batch diagram generation. Running `java -jar rr.war` with no arguments lists the available options.

### Can RR rewrite my grammar as well as draw it?

Yes. Besides generating diagrams, RR can perform grammar transformation, specifically factorization and elimination of direct recursion, which to some extent transforms BNF to EBNF and yields more compact diagrams.

### How do I use RR as a dependency in another Java project?

RR is on Maven Central with groupId de.bottlecaps.rr. The artifactId rr-lib provides rr.jar as a library dependency for other projects, while rr-webapp provides rr.war for deployment in a servlet container such as Tomcat or Jetty.

## Sources

- [GuntherRademacher/rr on GitHub](https://github.com/GuntherRademacher/rr)
- [License: Apache-2.0](https://github.com/GuntherRademacher/rr/blob/master/LICENSE)
- [Project website](https://www.bottlecaps.de/rr/ui)
- [README](https://github.com/GuntherRademacher/rr/blob/master/README.md)
- [Releases](https://github.com/GuntherRademacher/rr/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/guntherrademacher-rr