Open ehuss opened 5 years ago
reference vs a spec
Interesting, I always thought those are the same thing. For example, ARM Architecture Reference Manual is a specification.
I always thought those are the same thing.
I'm not aware of any well-defined distinction, and they are sometimes used interchangeably. I've noticed a trend that "spec" is decidedly formal, whereas "reference" can mean anything.
I think having two documents would be a lot of unnecessary duplicated work.
I think it would be useful to be explicit about who the reference is for and in what style it should be. There seems to be some uncertainty about being a reference vs a spec or if it should be both. I was confused when I first started, but I've gleaned the following along the way:
introduction.md says it is "not normative", "not a spec", but a "spec is intended in the future".
CONTRIBUTING.md: "too teachy for people" and "too shallow for a reference".
Over chat (some disagreement):
Rust All Hands 2019: https://paper.dropbox.com/doc/Topic-Spec--AZn5mRiLBp9zayEPAqu4RkjnAg-BB1tcOKwvpWUdzgQO4zgu
I think it would be good to write down:
I like the general style things have gone so far, in that it is mostly readable for a typical Rust programmer, with illustrative examples. My personal preference would be: continue along the current trajectory of having a non-normative, semi-formal (i.e. not a guide, not a formal spec) reference which strives for complete coverage while remaining semi-neutral to the details of the reference implementation (i.e. doesn't usually delve into usage, bugs, implementation-specific things, etc.). A formal, standards-quality spec is a non-goal at this time, though it is desirable to have such a document in the future (possibly separate or combined?).
Some example specs and references:
Interesting little paper comparing different ways languages are specified: http://www.knosof.co.uk/vulnerabilities/langconform.pdf How Modula-2 uses both English and VDM-SL to formally define the semantics (and some notes on the spec process in general): https://freepages.modula2.org/downloads/process2.pdf