docs: Language reference reorganization, part 1 #10984
Conversation
| - [Built-in Constants](language/builtin-constants.md) | ||
| - [Built-in Functions](language/builtins.md) | ||
| - [Operators](language/operators.md) | ||
| - [Initial Environment](language/initial-environment.md) |
There was a problem hiding this comment.
"Environment" is one of those vague terms, unfortunately. "Initial Scope" could work, but sounds like project planning. I'm leaning towards
| - [Initial Environment](language/initial-environment.md) | |
| - [Built-ins](language/builtins.md) |
I don't like that it's a bit Nix jargon, but I don't think it's much harder to understand for newcomers, while it is much easier to understand for those who've seen builtins.
There was a problem hiding this comment.
Hm. language/builtins.md is currently the name of the ‘Built-in Functions’ section, which I was planning on keeping more or less as-is (seemed like there was intention behind the choice to split that and builtin-constants.md into different files). My intent with this ‘Initial Environment’ section was to list the identifiers bound in the, uh, initial environment, and link to the appropriate anchor in builtins.md or builtin-constants.md for reference documentation on each of them.
What would you think of ‘Top-Level Scope’?
There was a problem hiding this comment.
builtins.md and builtins-constants.md should be combined. There is no user-facing difference between them (because a constant like builtins.derivation can also be a function), just internal implementation details which we should not leak.
So given that they should be combined, I think @roberth's suggestion is a good one --- we don't need a 3rd page linking to one of these 2 pages, we just need one page that documents builtins and points out which ones are also available in the top-level scope.
There was a problem hiding this comment.
builtins.mdandbuiltins-constants.mdshould be combined.
Well if that's the case then I'm happy to oblige—that makes the most sense to me as well.
Should I perhaps create a new PR to do that? I think it'll touch rather different things from this one, and might be more digestible as its own unit.
| @@ -1,5 +1,372 @@ | |||
| # Language Constructs | |||
|
|
|||
| ## Basic Literals | |||
There was a problem hiding this comment.
I feel like this is unnecessary categorization.
A general introductory statement would be nice though.
| ## Basic Literals | |
| The purpose of literals in a language is to turn expressions into new [values](./values.md) in a straightforward way. | |
| <!-- The measure of straightforwardness may differ per syntactic construct, but that's just how the terminology works for programming languages. --> |
I think one sentence is enough, but I've left a comment for contributors.
There was a problem hiding this comment.
This is going to get reworked; @fricklerhandwerk asked me to keep the PRs small, so this one is mostly about getting language/values.md set up and moving the content that was previously there to roughly the right place before editing it. (This header was previously ‘Primitives’ when this content lived in values.md; I changed it to align with the basic values/compound values/functions/externals taxonomy that I'm establishing there now.)
| @@ -1,5 +1,372 @@ | |||
| # Language Constructs | |||
|
|
|||
| ## Basic Literals | |||
|
|
|||
| ### String {#string-literal} | |||
There was a problem hiding this comment.
I like headers over a; they have a better UX when linking. 👍
I was going to suggest to preserve the anchor id, but type-string would be really bad.
Could you add redirects though?
There was a problem hiding this comment.
#type-string is alive and well and living in values.md, and any of this content relevant to strings as a data type may migrate back over there. It's a bit unfortunate that web links pointing to values.md#type-string will point to different content now, but there's a link to constructs.md#string-literal over there so readers don't get lost.
| ### String {#string-literal} | ||
|
|
||
| *Strings* can be written in three ways. | ||
|
|
There was a problem hiding this comment.
The content below was moved from values.md, with anchors changed to headers.
Did I miss any other changes?
There was a problem hiding this comment.
I added some TODOs and I may have updated a link or two around here, but the intent was that this step would be a mostly-pure move with the editing to come later.
There was a problem hiding this comment.
Thought (no action needed):
This file is almost completely about syntactic constructs, with a tiny surprise at the end.
It could be split into syntax.md and scope.md.
The latter could use some elaboration, so its size won't be a "problem".
There was a problem hiding this comment.
In future parts I hope to give a more rigorous presentation of evaluation semantics, which will naturally include some discussion of environments/scopes. I'm undecided on how exactly that should be split up; I don't want to completely divorce the syntax from the semantics, though I know that's how many language references are written. But yeah, scope might need some discussion that's separated from any forms that manipulate it.
|
Closing in favor of #11013, though I will carry the remaining bits from here and the feedback received forward to the next one. |
#10970
Moving the existing content of values.md into constructs.md and sketching out the bones of what should be there instead.
Ping @fricklerhandwerk
Priorities and Process
Add 👍 to pull requests you find important.
The Nix maintainer team uses a GitHub project board to schedule and track reviews.