Improve README and Other Markdown Files #58
Conversation
INSTALLATION.md
Outdated
| @@ -16,7 +16,7 @@ ext install "Slice" | |||
| To build and package the extension, you must have [`vsce`](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#vsce) installed: | |||
There was a problem hiding this comment.
Why don't we just make @vscode/vsce a dev dependency? Do we need it for the build or just for the packaging?
There was a problem hiding this comment.
It's purely for packaging; after everything has been built, it just zips the files together into a .vsix package. That's all.
The language server is built to be general purpose.
So, in the future we might support other editors, which would have their own packaging tools.
There was a problem hiding this comment.
In that case it doesn't need this install step. You can just run with npx
There was a problem hiding this comment.
Oh! I didn't know that cool.
Fixed.
There was a problem hiding this comment.
Whoops, I forgot to push my changes ._.
README.md
Outdated
| - Error detection & reporting | ||
| - 'Go to Definition' jumping |
There was a problem hiding this comment.
These two are .slice only however.
There was a problem hiding this comment.
I mention that in their sub-section later on:
... and is only available for '.slice' files.
If you prefer it, I can find a way to add it to the main list, but I wanted to keep the bullet points short.
Co-authored-by: Joe George <joe@externl.com>
README.md
Outdated
| - Syntax highlighting | ||
| - Syntax validation | ||
| - Error detection & reporting | ||
| - 'Go to Definition' jumping |
There was a problem hiding this comment.
I would just write:
- Go to Definition
No jumping, no quotes.
There was a problem hiding this comment.
I think it would be clearer to explain in this top section that most features only apply to .slice files.
| These types are commonly used in applications utilizing Slice. | ||
| Defaults to `true`. | ||
|
|
||
| If you do not specify any configuration sets, the extension will default to using the project's root directory for `paths`. |
There was a problem hiding this comment.
I would use the present everywhere. No 'will'.
The extension defaults to ...
The language server only works with .slice files and ignores any ...
There was a problem hiding this comment.
I fixed the 2nd sentence, but left the 1st sentence as is.
In it, the will feels necessary, because the sentence is talking about a condition being met in the future:
If you do not specify any configuration sets, the extension will default to ...
For example:
If you write bad code, the compiler will give an error vs
If you write bad code, the compiler gives an error.
The 2nd one sounds wrong to me, especially compared to the 1st one.
README.md
Outdated
| "addWellKnownTypes": false, | ||
| "paths": [ | ||
| "path/to/specific/file.slice", | ||
| "/absolute/path/to/other/slice/files", |
There was a problem hiding this comment.
I prefer directory over files for a sample directory name.
README.md
Outdated
| Additionally, this extension provides a Slice Language Server, for `.slice` files only. | ||
| ### Error Detection and Reporting | ||
|
|
||
| Error checking is triggered every time a Slice file is saved or opened, |
There was a problem hiding this comment.
Why is this line so short?
There was a problem hiding this comment.
I don't know, but I put it all on one line.
This PR updates the wording of our main README, in accordance with #45,
and tweaks some minor wording/commands in our other markdown files.
The only point that I didn't address in #45 was mentioning the location of the
settings.jsonfile.This went unaddressed because it can have multiple locations. There are per-user, per-workspace, and even per-folder variants of this file, so there's no simple way to tell the user where to find it.
A cursory google search should point them in the right direction though, so I'm not too worried about it.