Chandler CarruthandRichard Smith
cfd1ed8484
Rumdl already appears to have _significantly_ fewer bugs than prettier, and a solid LSP for editor integration. The tool is: https://github.com/rvben/rumdl/ I've separated out the change across three commits for easier review. The configuration tries to match the existing formatting, the changes to the all the files are to correct issues found by the new tool. Assisted-by: Antigravity with Gemini --------- Co-authored-by: Richard Smith <richard@metafoo.co.uk>
2.8 KiB
Create initial rough framework for specification
Table of contents
Problem
We need a rough layout for our specification so that we can start adding details to it once they're decided.
Proposal
Split the specification into a language and a library section. In the language section, use one file per broad area of functionality. Divide the language up based on the intended layering of the language design.
For now, maintain the specification sources in Markdown.
Details
Proposed top-level structure of the spec/ directory as of this pull request:
README.mdIntroduction to the specificationlangREADME.mdLanguage specification overview and basicsexecution.mdExecution semanticslex.mdLexical analysislibs.mdLibraries and packagesnames.mdNames and name binding / lookupparsing.mdParsingsemantics.mdSemantic analysis
libREADME.mdLibrary specification overview and basics
This is only a starting point; the structure should be expected to change and grow as the specification is filled out. Most of the proposed files are empty or nearly-empty placeholders.
Conventions
All paragraphs within the specification are numbered so that they can be referenced more easily.
Defined terms are introduced in italics.
Hyperlinks between sections of the specification are used liberally.
Alternatives considered
Maintain the specification in a different language
Advantages:
- An alternative language may provide better support for custom typesetting, representing grammars, linking to definitions, and so on.
Disadvantages:
- Using a different language would add complexity and inconsistency to our documentation.
- There is unlikely to be any existing documentation language that is well-suited to our needs without significant customization.
- Conversion from a more sophisticated language is likely to be more complex than converting from Markdown.
Conversion of Markdown to another language at a later point (either manually or using a tool like Sphinx) is expected to remain a relatively low-cost option, due to the relative simplicity of Markdown-formatted documents.