Document @forward #368
Document @forward #368
Conversation
| [variables](../variables) from another Sass stylesheet available to | ||
| stylesheets that load your stylesheet with the [`@use` rule](use). It makes it | ||
| possible to organize Sass libraries across many files, while allowing their | ||
| users to load a single entrypoint file. |
There was a problem hiding this comment.
Using the word "stylesheet" three times so close together makes the sentence a bit hard to read, but I'm also having a hard time with an alternate wording. I'm thinking something kind of like
The `@forward` rule makes mixins, functions, and variables available for `@use` from a different
stylesheet than the one in which they're declared. A stylesheet using this rule _forwards_ these
symbols from the original location through itself. This allows Sass libraries to surface APIs from
multiple files through a single entry-point.I'm also wondering if it makes sense to add a comparison like "The process of forwarding works similarly to re-exporting symbols in JavaScript, Python, etc."
There was a problem hiding this comment.
Using the word "stylesheet" three times so close together makes the sentence a bit hard to read, but I'm also having a hard time with an alternate wording. I'm thinking something kind of like
The `@forward` rule makes mixins, functions, and variables available for `@use` from a different stylesheet than the one in which they're declared. A stylesheet using this rule _forwards_ these symbols from the original location through itself. This allows Sass libraries to surface APIs from multiple files through a single entry-point.
I don't think I like the "available for use from a different stylesheet than the one in which they're declared", because that could arguably describe @use as well. I've tried rewriting it to make the repetition less awkward; PTAL.
I'm also wondering if it makes sense to add a comparison like "The process of forwarding works similarly to re-exporting symbols in JavaScript, Python, etc."
In my experience, the people who most struggle to understand these docs are those coming to them from a non-programming background. I expect that most people who are familiar with re-exporting symbols will grok this pretty easily regardless.
| --- | ||
|
|
||
| It's written `@forward "<url>"`. It loads the module at the given URL just like |
There was a problem hiding this comment.
"It's written" -> "The rule uses the syntax"
("It" here could be ambiguous, plus a more active voice, though it is longer)
There was a problem hiding this comment.
Changed to "The rule is written". I want to keep the word "written" because it's consistently used as a signal word for "here comes the general syntax".
Closes #362