Create initial rough framework for specification

Pull request

Table of contents

Table of contents

• Problem
• Proposal
• Details
  • Conventions
• Alternatives considered
  • Maintain the specification in a different language.

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.md Introduction to the specification
• lang
  • README.md Language specification overview and basics
  • execution.md Execution semantics
  • lex.md Lexical analysis
  • libs.md Libraries and packages
  • names.md Names and name binding / lookup
  • parsing.md Parsing
  • semantics.md Semantic analysis
• lib
  • README.md Library 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.