Writing a good spec is an art in itself. You must be very precise while using natural language, which by its nature is imprecise. Have a look at other parts of the F# spec, or better at the C# spec, which was created with much more effort by many more people.
The source for the spec is the collection of markdown files in the spec folder.
We aim to use CommonMark markdown, plus the section links and tables of github-flavored markdown.
We use ATX headings without closing # characters.
In the sources, the headings are not numbered. Numbering is added during the build process.
Intra-spec links are made like this: [§](inference-procedures.md#constraint-solving).
As such, the links work directly in the spec sources (like on github or in VS Code preview).
They are converted during the build process to include the section number.
All fenced code blocks should carry one of the following info strings.
fsharpfor F# code samplescsharpfor C# code samplesfsgrammarfor F# grammarfsotherfor other code (like pseudo code in a few places)
Show defined terms in italics.
For inline code (including e.g. file and type names) use code spans.
In most cases, checking your edits in a markdown viewer should be sufficient. But you can also view the final output by proceeding as follows.
- Make your changes in the local clone of your forked repo in a branch called
dev. - Push your changes. This will automatically create a branch gh-pages in your repo.
- When you have done the above for the first time, go to github settings of your forked repo and enable github pages (Settings -> Pages -> Branch gh-pages -> Save).
- You can view the spec with your changes at
http://<yourAccountName>.github.io/fslang-spec.