Chandler CarruthandRichard Smith
94d2c1c6d4
We've talked about adding the title to the filename several times over the years and it seems really valuable. This requires us to compute a "slug" for the title spelling that can be part of the filename. Beyond that, we crossed 7000 recently, and so it seems likely that we will need to add digits sooner rather than later here, so this goes ahead and moves us to 6 digits so we don't have to adjust again for a reasonable length of time. To implement this and ensure we can sustain it going forward this adds a tool to our pre-commit that validates (and corrects if needed) the filename. In order to update everything and keep links working, there are a _lot_ of changes, but the most interesting for direct review are in `proposals/scripts`. 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
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.