Document Open Access Logo

Automatic Layout of Railroad Diagrams

Authors Shardul Chiplunkar , Clément Pit-Claudel

PDF

File

Thumbnail PDF
PDF
LIPIcs.ECOOP.2026.2.pdf
  • Filesize: 2.92 MB
  • 31 pages

Document Identifiers

Subject Classification

ACM Subject Classification
  • Human-centered computing → Visualization
  • Software and its engineering → Software notations and tools
Keywords
  • syntax diagram
  • graph layout
  • line wrapping
  • pretty-printing

Metrics

Abstract

Railroad diagrams (also called "syntax diagrams") are a common, intuitive visualization of grammars, but limited tooling and a lack of formal attention to their layout mostly confines them to hand-drawn documentation. We present the first formal treatment of railroad diagram layout along with a principled, practical implementation. We characterize the problem as compiling a diagram language (specifying conceptual components and how they connect and compose) to a layout language (specifying basic graphical shapes and their sizes and positions). We then implement a compiler that performs line wrapping to meet a target width, as well as vertical alignment and horizontal justification per user-specified policies. We frame line wrapping as optimization, where we describe principled dimensions of optimality and implement corresponding heuristics. For front-end evaluation, we show that our diagram language is well-suited for common applications by describing how regular expressions and Backus-Naur form can be compiled to it. For back-end evaluation, we argue that our compiler is practical by comparing its output to diagrams laid out by hand and by other tools.

Cite As Get BibTex

Shardul Chiplunkar and Clément Pit-Claudel. Automatic Layout of Railroad Diagrams. In 40th European Conference on Object-Oriented Programming (ECOOP 2026). Leibniz International Proceedings in Informatics (LIPIcs), Volume 372, pp. 2:1-2:31, Schloss Dagstuhl – Leibniz-Zentrum für Informatik (2026) https://doi.org/10.4230/LIPIcs.ECOOP.2026.2

Author Details

Shardul Chiplunkar
  • School of Computer and Communication Sciences, EPFL, Lausanne, Switzerland
Clément Pit-Claudel
  • School of Computer and Communication Sciences, EPFL, Lausanne, Switzerland

Funding

This work was funded in part by the Swiss National Science Foundation (SNSF) under grant no. 10003649. This material is based upon work supported by the Air Force Research Laboratory (AFRL) and Defense Advanced Research Projects Agencies (DARPA) under Contract No. FA8750-24-C-B044. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the AFRL and DARPA.

Acknowledgements

The authors thank Viktor Kunčak, Emir Demirović, and Hugo Herbelin for many insightful discussions, and the anonymous peer reviewers for their helpful feedback. Both authors are members of the EPFL-Inria REMPAR associate team.

Supplementary Materials

References

  1. Daniel Abrecht. Railroad CSS, February 2023. URL: https://daniel-abrecht.github.io/railroad-css/.
  2. Rajeev Alur, Caleb Stanford, and Christopher Watson. A Robust Theory of Series Parallel Graphs. Proceedings of the ACM on Programming Languages, 7(POPL):1058-1088, January 2023. URL: https://doi.org/10.1145/3571230.
  3. Robert D. Anderson and Deborah Pickett. svg-syntaxdiagrams. IBM, October 2019. URL: https://github.com/robander/svg-syntaxdiagrams.
  4. Tab Atkins, Jr. Railroad-diagram generator, January 2024. URL: https://github.com/tabatkins/railroad-diagrams/.
  5. atp-mipt. JSyntrax, May 2024. URL: https://github.com/atp-mipt/jsyntrax.
  6. Jeff Avallone. Regexper, September 2020. URL: https://regexper.com.
  7. Michael J. Bannister, David A. Brown, and David Eppstein. Confluent Orthogonal Drawings of Syntax Diagrams. In Emilio Di Giacomo and Anna Lubiw, editors, Graph Drawing and Network Visualization, volume 9411 of Lecture Notes in Computer Science, pages 260-271, Cham, 2015. Springer International Publishing. URL: https://doi.org/10.1007/978-3-319-27261-0_22.
  8. Klaus Georg Barthelmann and Luc Rooijakkers. rail, May 1998. URL: https://www.ctan.org/pkg/rail.
  9. Stoughton Bell and Edgar J. Gilbert. Learning recursion with syntax diagrams. SIGCSE Bulletin, 6(3):44-45, September 1974. URL: https://doi.org/10.1145/988881.988890.
  10. Jean-Philippe Bernardy. A pretty but not greedy printer (functional pearl). Proceedings of the ACM on Programming Languages, 1(ICFP):6:1-6:21, August 2017. URL: https://doi.org/10.1145/3110250.
  11. Richard S. Bird. Transformational programming and the paragraph problem. Science of Computer Programming, 6:159-189, January 1986. URL: https://doi.org/10.1016/0167-6423(86)90023-7.
  12. Richard Bonichon and Pierre Weis. Format unraveled. In Journées Francophones Des Langages Applicatifs: JFLA 2017, Gourette, France, January 2017. URL: https://hal.science/hal-01503081.
  13. Michael Bostock, Vadim Ogievetsky, and Jeffrey Heer. D3: Data-driven documents. IEEE Transactions on Visualization & Computer Graphics, 17(12):2301-2309, November 2011. URL: https://doi.org/10.1109/TVCG.2011.185.
  14. Andreas Brandstädt, Van Bang Le, and Jeremy P. Spinrad. Algebraic compositions and recursive definitions. In Graph Classes: A Survey, Discrete Mathematics and Applications, pages 167-185. Society for Industrial and Applied Mathematics, Philadelphia, PA, USA, 1999. URL: https://doi.org/10.1137/1.9780898719796.ch11.
  15. Lisa M. Braz. Visual syntax diagrams for programming language statements. SIGDOC Asterisk Journal of Computer Documentation, 14(4):23-27, September 1990. URL: https://doi.org/10.1145/97435.97987.
  16. James Paul Brisson. Methods and system for converting a text-based grammar to a compressed syntax diagram. U.S. Patent 5,678,052 A, assigned to IBM Corporation, October 1997. Google Scholar
  17. Michael Burch, Michael Raschke, and Daniel Weiskopf. Indented pixel tree plots. In George Bebis, Richard Boyle, Bahram Parvin, Darko Koracin, Ronald Chung, Riad Hammoud, Muhammad Hussain, Tan Kar-Han, Roger Crawfis, Daniel Thalmann, David Kao, and Lisa Avila, editors, Advances in Visual Computing, volume 6453 of Lecture Notes in Computer Science, pages 338-349, Berlin, Heidelberg, 2010. Springer. URL: https://doi.org/10.1007/978-3-642-17289-2_33.
  18. Luyu Cheng and Lionel Parreaux. A simple recipe for writing decent recursive descent parsers (pearl). In 40th European Conference on Object-Oriented Programming (ECOOP 2026), volume 372 of Leibniz International Proceedings in Informatics (LIPIcs), Dagstuhl, Germany, 2026. Schloss Dagstuhl - Leibniz-Zentrum für Informatik. URL: https://doi.org/10.4230/LIPIcs.ECOOP.2026.31.
  19. chevrotain contributors. chevrotain, March 2026. URL: https://github.com/Chevrotain/chevrotain.
  20. Shardul Chiplunkar and Clément Pit-Claudel. LibRRD. Software, version ecoop2026-artifact. (visited on 2026-05-05). URL: https://github.com/epfl-systemf/librrd/releases/tag/ecoop2026-artifact
    full metadata available at: https://doi.org/10.4230/artifacts.25789
  21. Shardul Chiplunkar and Clément Pit-Claudel. Diagrammatic notations for interactive theorem proving. In 4th International Workshop on Human Aspects of Types and Reasoning Assistants (HATRA 2023), October 2023. URL: https://doi.org/10.5075/epfl-SYSTEMF-305144.
  22. Paolo Ciancarini, Angelo Di Iorio, Luca Furini, and Fabio Vitali. High-quality pagination for publishing. Software: Practice and Experience, 42(6):733-751, July 2011. URL: https://doi.org/10.1002/spe.1096.
  23. Douglas Crockford. JSON object syntax, 2001. URL: https://www.json.org/json-en.html.
  24. Quint Daenen. Railroad, April 2024. URL: https://github.com/0x51-dev/railroad.
  25. Oege de Moor and Jeremy Gibbons. Bridging the algorithm gap: A linear-time functional program for paragraph formatting. Science of Computer Programming, 35(1):3-27, September 1999. URL: https://doi.org/10.1016/S0167-6423(99)00005-2.
  26. Christopher Deckers. RRDiagram, January 2024. URL: https://github.com/Chrriis/RRDiagram.
  27. Sabin Devkota. Visualizing Control Flow Graphs. PhD thesis, The University of Arizona, Tucson, Arizona, USA, 2021. URL: https://repository.arizona.edu/handle/10150/661593.
  28. Markus Dopler and Stefan Schörgenhumer. EBNF visualizer, 2005. URL: http://dotnet.jku.at/applications/Visualizer/.
  29. Jakub Dundalek. GrammKit, April 2023. URL: https://dundalek.com/GrammKit/.
  30. Harald Dyckhoff. A typology of cutting and packing problems. European Journal of Operational Research, 44(2):145-159, January 1990. URL: https://doi.org/10.1016/0377-2217(90)90350-K.
  31. Kristen James Eberlein and Robert D. Anderson. Darwin Information Typing Architecture (DITA), June 2018. URL: http://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part3-all-inclusive.html.
  32. Ecma. The JSON Data Interchange Syntax, 2017. URL: https://ecma-international.org/publications-and-standards/standards/ecma-404/.
  33. Chengsu Feng and Xizhi Wang. Lantingji Xu scroll (Shenlong version). Courtesy user Aoser on Wikimedia Commons, 650. URL: https://commons.wikimedia.org/wiki/File:%E7%A5%9E%E9%BE%8D%E8%98%AD%E4%BA%AD%E5%BA%8F%E5%85%A8.JPG.
  34. Katherine Flavel. KGT: Kate’s Grammar Tool, April 2025. URL: https://github.com/katef/kgt.
  35. Emden R. Gansner and Stephen C. North. An open graph visualization system and its applications to software engineering. Software: Practice and Experience, 30(11):1203-1233, August 2000. URL: https://doi.org/10.1002/1097-024X(200009)30:11<1203::AID-SPE338>3.0.CO;2-N.
  36. Matthijs Groen. Utf-railroad, October 2020. URL: https://github.com/matthijsgroen/utf-railroad.
  37. Philip J. Guo. Online Python Tutor: Embeddable web-based program visualization for CS education. In Proceedings of the 44th ACM Technical Symposium on Computer Science Education, SIGCSE 2013, pages 579-584, New York, NY, USA, March 2013. Association for Computing Machinery. URL: https://doi.org/10.1145/2445196.2445368.
  38. Jeffrey Heer and Michael Bostock. Declarative language design for interactive visualization. IEEE Transactions on Visualization and Computer Graphics, 16(6):1149-1156, November 2010. URL: https://doi.org/10.1109/TVCG.2010.144.
  39. Robert G. Herriot. Structured syntax diagrams. Computer Languages, 2(1):9-19, January 1976. URL: https://doi.org/10.1016/0096-0551(76)90009-6.
  40. Ralf Hinze. Self-certifying railroad diagrams. In Graham Hutton, editor, Mathematics of Program Construction, volume 11825 of Lecture Notes in Computer Science, pages 103-137, Cham, 2019. Springer International Publishing. URL: https://doi.org/10.1007/978-3-030-33636-3_5.
  41. Matthijs Hollemans. Railroad-Diagrams-Swift, May 2019. URL: https://github.com/hollance/Railroad-Diagrams-Swift.
  42. John Hughes. The design of a pretty-printing library. In Johan Jeuring and Erik Meijer, editors, Advanced Functional Programming, volume 925 of Lecture Notes in Computer Science, pages 53-96, Båstad, Sweden, May 1995. Springer-Verlag. URL: https://doi.org/10.1007/3-540-59451-5_3.
  43. John D. Hunter. Matplotlib: A 2D graphics environment. Computing in Science & Engineering, 9(3):90-95, 2007. URL: https://doi.org/10.1109/MCSE.2007.55.
  44. Julian Hyde. Clapham, May 2009. URL: http://clapham.hydromatic.net/.
  45. IBM Corporation. IBM MQ 9.4 Reference. Technical report, IBM Corporation, January 2025. URL: https://www.ibm.com/docs/en/ibm-mq/9.4?topic=mq-reference.
  46. Charles Jacobs, Wilmot Li, Evan Schrier, David Bargeron, and David Salesin. Adaptive grid-based document layout. ACM Transactions on Graphics, 22(3):838-847, July 2003. URL: https://doi.org/10.1145/882262.882353.
  47. Vincent Jacques. DrawGrammar, November 2018. URL: https://jacquev6.github.io/DrawGrammar/.
  48. Ramesh Johari, Joe Marks, Ali Partovi, and Stuart Shieber. Automatic Yellow-Pages pagination and layout. Journal of Heuristics, 2(4):321-342, March 1997. URL: https://doi.org/10.1007/BF00132503.
  49. Tom Kamifuji and Jef Raskin. Apple Pascal syntax chart. Courtesy Dana Sibera "NanoRaptor", 1979. URL: http://www.danamania.com/print/Apple%20Pascal%20Poster/PascalPosterV3%20A1.pdf.
  50. Eric A. Kenninga. Optimal line break determination. U.S. Patent 6,510,441 B1, assigned to Adobe Systems, Inc., January 2003. Google Scholar
  51. Brian W Kernighan. PIC - A graphics language for typesetting user manual. Technical Report 116, AT&T Bell Laboratories, Murray Hill, NJ 07974, May 1991. URL: https://pikchr.org/home/uv/pic.pdf.
  52. Stanislav Kirpichenko. VirtDiagramsDSL, 2022. URL: https://github.com/Stasychbr/VirtDiagramsDSL.
  53. Oleg Kiselyov, Simon Peyton-Jones, and Amr Sabry. Lazy v. Yield: Incremental, linear pretty-printing. In Ranjit Jhala and Atsushi Igarashi, editors, Programming Languages and Systems, Lecture Notes in Computer Science, pages 190-206, Berlin, Heidelberg, 2012. Springer. URL: https://doi.org/10.1007/978-3-642-35182-2_14.
  54. Aleks Kissinger. TikZiT, August 2020. URL: https://tikzit.github.io/.
  55. Jens Klöcker. syngen, November 1996. URL: https://www.ctan.org/pkg/syngen.
  56. Donald E. Knuth and Michael F. Plass. Breaking paragraphs into lines. Software: Practice and Experience, 11(11):1119-1184, November 1981. URL: https://doi.org/10.1002/spe.4380111102.
  57. Dexter Kozen. Kleene algebra with tests. ACM Transactions on Programming Languages and Systems, 19(3):427-443, May 1997. URL: https://doi.org/10.1145/256167.256195.
  58. Philip Krauss. RRD-ANTLR4, June 2021. URL: https://github.com/flashpixx/RRD-ANTLR4.
  59. Usha Krishnamurthy. SQL Language Reference 23ai. Technical Report F47038-21, Oracle Corporation, February 2025. URL: https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/index.html.
  60. Mike Lischke. VSCode-ANTLR4, August 2024. URL: https://github.com/mike-lischke/vscode-antlr4.
  61. Rafael Lopez. PyRailroad, October 2024. URL: https://github.com/Epithumia/pyrailroad.
  62. Lukas Lueg. Railroad, July 2024. URL: https://github.com/lukaslueg/railroad.
  63. Mermaid contributors. Mermaid | Diagramming and charting tool. URL: https://mermaid.js.org/.
  64. Wojciech Nawrocki, Edward W Ayers, and Gabriel Ebner. An extensible user interface for Lean 4. In 14th International Conference on Interactive Theorem Proving (ITP 2023), Leibniz International Proceedings in Informatics (LIPIcs), pages 24:1-24:20, Dagstuhl, Germany, 2023. Schloss Dagstuhl - Leibniz-Zentrum für Informatik. URL: https://doi.org/10.4230/LIPIcs.ITP.2023.24.
  65. Derek C. Oppen. Prettyprinting. ACM Transactions on Programming Languages and Systems, 2(4):465-483, October 1980. URL: https://doi.org/10.1145/357114.357115.
  66. Pavel Panchekha, Michael D. Ernst, Zachary Tatlock, and Shoaib Kamil. Modular verification of web page layout. Proceedings of the ACM on Programming Languages, 3(OOPSLA):151:1-151:26, October 2019. URL: https://doi.org/10.1145/3360577.
  67. Pavel Panchekha and Emina Torlak. Automated reasoning for web page layout. In Proceedings of the 2016 ACM SIGPLAN International Conference on Object-Oriented Programming, Systems, Languages, and Applications, OOPSLA 2016, pages 181-194, Amsterdam, Netherlands, October 2016. ACM. URL: https://doi.org/10.1145/2983990.2984010.
  68. Arno J. H. Peels, Norbert J. M. Janssen, and Wop Nawijn. Document architecture and text formatting. ACM Transactions on Information Systems, 3(4):347-369, October 1985. URL: https://doi.org/10.1145/4656.4657.
  69. Robin Piedeleu and Fabio Zanasi. A finite axiomatisation of finite-state automata using string diagrams. Logical Methods in Computer Science, 19(1):13:1-13:38, February 2023. URL: https://doi.org/10.46298/lmcs-19(1:13)2023.
  70. Johannes Pieper, André Hilbig, Johannes Kuhaupt, Daniel Spittank, Ludger Humbert, and Adrian Salamon. syntaxdi, October 2020. URL: https://www.ctan.org/pkg/syntaxdi.
  71. Pikchr contributors. How Pikchr generates the SQLite syntax diagrams, February 2024. URL: https://pikchr.org/home/doc/trunk/doc/sqlitesyntax.md.
  72. Clément Pit-Claudel. Untangling mechanized proofs. In Proceedings of the 13th ACM SIGPLAN International Conference on Software Language Engineering, SLE 2020, pages 155-174, Virtual, November 2020. ACM. URL: https://doi.org/10.1145/3426425.3426940.
  73. Josh Pollock, Catherine Mei, Grace Huang, Elliot Evans, Daniel Jackson, and Arvind Satyanarayan. Bluefish: Composing Diagrams with Declarative Relations. In Proceedings of the 37th Annual ACM Symposium on User Interface Software and Technology, pages 1-21, Pittsburgh, PA, USA, October 2024. ACM. URL: https://doi.org/10.1145/3654777.3676465.
  74. Sorawee Porncharoenwase, Justin Pombrio, and Emina Torlak. A pretty expressive printer. Proceedings of the ACM on Programming Languages, 7(OOPSLA2):261:1122-261:1149, October 2023. URL: https://doi.org/10.1145/3622837.
  75. William W. Pugh and Steven J. Sinofsky. A new language-independent prettyprinting algorithm. Technical Report TR 87-808, Cornell University, January 1987. URL: https://www.cs.tufts.edu/~nr/cs257/archive/steven-sinofsky/prettyprinting-87-808.pdf.
  76. Larry D. Pyeatt. Ebnf2tikz, December 2023. URL: https://github.com/pyeatt/ebnf2tikz/.
  77. Gunther Rademacher. rr, February 2025. URL: https://github.com/GuntherRademacher/rr/.
  78. Ulf Rüegg and Reinhard von Hanxleden. Wrapping layered graphs. In Peter Chapman, Gem Stapleton, Amirouche Moktefi, Sarah Perez-Kriz, and Francesco Bellucci, editors, Diagrammatic Representation and Inference, volume 10871 of Lecture Notes in Computer Science, pages 743-747, Cham, June 2018. Springer International Publishing. URL: https://doi.org/10.1007/978-3-319-91376-6_72.
  79. Arvind Satyanarayan, Dominik Moritz, Kanit Wongsuphasawat, and Jeffrey Heer. Vega-Lite: A grammar of interactive graphics. IEEE Transactions on Visualization and Computer Graphics, 23(1):341-350, January 2017. URL: https://doi.org/10.1109/TVCG.2016.2599030.
  80. Lei Shi, Chen Wang, Zhen Wen, Huamin Qu, Chuang Lin, and Qi Liao. 1.5D egocentric dynamic network visualization. IEEE Transactions on Visualization and Computer Graphics, 21(5):624-637, May 2015. URL: https://doi.org/10.1109/TVCG.2014.2383380.
  81. Robin M. Snyder. Specifying textual to graphical conversion. Journal of Systems and Software, 16(1):17-28, September 1991. URL: https://doi.org/10.1016/0164-1212(91)90028-5.
  82. SQLite contributors. Syntax diagrams for SQLite, 2024. URL: https://www.sqlite.org/syntaxdiagrams.html.
  83. Guy Lewis Steele, Jr. It’s time for a new old language, April 2017. URL: https://groups.csail.mit.edu/mac/users/gjs/6.945/readings/Steele-MIT-April-2017.pdf.
  84. S. Doaitse Swierstra and Olaf Chitil. Linear, bounded, functional pretty-printing. Journal of Functional Programming, 19(1):1-16, January 2009. URL: https://doi.org/10.1017/S0956796808006990.
  85. Yudai Takada. Railroad diagrams, February 2025. URL: https://github.com/ydah/railroad_diagrams.
  86. Roberto Tamassia, editor. Handbook of Graph Drawing and Visualization. Chapman & Hall/CRC, New York, NY, USA, 1st edition, 2013. URL: https://cs.brown.edu/people/rtamassi/gdhandbook/.
  87. Till Tantau. The TikZ and PGF Packages, May 2023. URL: www.ctan.org/pkg/pgf.
  88. Kevin Thibedeau. Syntrax, February 2019. URL: https://github.com/kevinpt/syntrax.
  89. Peter Thiemann. Ebnf2ps: Peter’s syntax diagram drawing tool, June 2010. URL: http://www2.informatik.uni-freiburg.de/~thiemann/haskell/ebnf2ps/.
  90. Alexander Voglsperger. EBNF railroad visualizer, December 2024. URL: https://github.com/MrMinemeet/ebnf_railroad_visualizer.
  91. W3C. Scalable Vector Graphics (SVG) 1.1 (Second Edition), August 2011. URL: https://www.w3.org/TR/SVG11/.
  92. W3C. CSS Flexible Box Layout Module Level 1. Candidate Recommendation, W3C, November 2018. URL: https://www.w3.org/TR/css-flexbox-1/.
  93. W3C. CSS Box Alignment Module Level 3. Working Draft, W3C, March 2025. URL: https://www.w3.org/TR/css-align-3/.
  94. Philip Wadler. A prettier printer. In Jeremy Gibbons and Oege de Moor, editors, The Fun of Programming, pages 223-243. Macmillan Education UK, London, 2003. URL: https://doi.org/10.1007/978-1-349-91518-7_11.
  95. Hadley Wickham. ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag, New York, NY, USA, 2016. URL: https://ggplot2.tidyverse.org.
  96. Leland Wilkinson. The Grammar of Graphics. Statistics and Computing. Springer-Verlag, New York, NY, USA, 2nd edition, 2005. URL: https://doi.org/10.1007/0-387-28695-0.
  97. Niklaus Wirth. The programming language Pascal. Report, ETH Zürich, Zürich, Switzerland, 1970. URL: https://doi.org/10.3929/ethz-a-004150844.
  98. Mark Wooding. syntax-mdw, May 1996. URL: https://ctan.org/pkg/syntax-mdw.
  99. Katherine Ye, Wode Ni, Max Krieger, Dor Ma'ayan, Jenna Wise, Jonathan Aldrich, Joshua Sunshine, and Keenan Crane. Penrose: From mathematical notation to beautiful diagrams. ACM Transactions on Graphics, 39(4), August 2020. URL: https://doi.org/10.1145/3386569.3392375.
  100. yWorks. yFiles for HTML. yWorks, February 2025. URL: https://www.yworks.com/yfiles-overview.
  101. Andreas Zeller and Dorothea Lütkehaus. DDD - a free graphical front-end for UNIX debuggers. ACM SIGPLAN Notices, 31(1):22-27, January 1996. URL: https://doi.org/10.1145/249094.249108.
Any Issues?
X

Feedback on the Current Page

CAPTCHA

Thanks for your feedback!

Feedback submitted to Dagstuhl Publishing

Could not send message

Please try again later or send an E-mail
© 2023-2026 Schloss Dagstuhl – LZI GmbH Schloss Dagstuhl – LZI GmbH About DROPS Imprint Privacy Contact