Add step-by-step tutorial for getting started

[matthewelmer]

Howdy,

I'm probably just stupid, but I cannot figure out how to get vale-vscode working.

1. Install Vale;

Check.

matt@matt-Precision-5560:~
$ vale --version
vale version 2.29.2

2. install vale-vscode (this extension) via the Marketplace;

Check.

3. Restart VS Code (recommended).

Check. (I'm sure you can take my word for it.)

But I'm getting zero suggestions in the report.tex file that I have open in VS Code.

What am I missing, and should we add "getting started" instructions?

[beklapko]

I'm having issues with this as well. This is my third time setting up Vale (in the last ~6 years or so) and I can't figure out what I'm doing wrong this time.

[ccoVeille]

Let me guess, you need to have a valid .vale.ini file.

So I would say, you need to create it.

Install vale

Run vale ls-dirs

You will see the folder where you need to create your global/default .vale.ini file

More information here

https://vale.sh/docs/topics/config/

Then you have to configure Vale with packages

The best would be to use this

https://vale.sh/generator/

Then use vale sync to install and set up everything

[ccoVeille]

@beklapko @matthewelmer did you have s chance to follow the steps I described. I'm curious if it can solve your problems

[matthewelmer]

@beklapko @matthewelmer did you have s chance to follow the steps I described. I'm curious if it can solve your problems

Yes! I'm almost done setting up. Where can I read about setting up vale/native/vale-native? I see a red X next to it when I run vale ls-dirs, but I can't find any documentation on why it's needed or what it's used for.

[matthewelmer]

Update: vale/native/vale-native doesn't seem to be necessary. Dunno what it does, and since my vale is working now, I don't care!

I'll recount my installation procedure below as a first draft towards a "getting started" guide. Perhaps most of this procedure belongs in the README.md for vale itself, but that's a separate issue.

1. Install vale.
   • On Fedora Linux 40, I found it easiest to copy the precompiled binary from vale's GitHub releases page into my /home/$USER/bin directory.
2. Find out where your config file lives by running vale ls-dirs. Create the .vale.ini file if it isn't found.
   • It may also say that /path/to/vale-native wasn't found, but I didn't end up needing that file. I don't know what it does, but nor do I care since vale seems to work without it!
3. Generate a config file and copy the contents into your .vale.ini.
   • I went with the Microsoft style guide.
   • I tried the Readability supplementary style, but I found it to be unhelpful for my highly technical writing use case.
   • I used [*.{tex,md}] instead of [*], since I'm only interested in suggestions for my writing.
4. Run vale sync.
5. Install the Vale VSCode extension.
6. Restart VS Code.
7. Create a test document and see if everything is working. I've written a passage below along with the suggestions that I got for it.
   • If you see no squiggles in VS Code, something is wrong. Try running vale <test document> to see if you can get suggestions from the command line. If you can't, then something is broken with vale itself. If you can, then something might be broken with the Vale VSCode extension.

Passage:

There is a serene tranquility to the quiet hours of the early morning.
A secret world, all to myself. An otherwise ordinary commute instead offers the
rhythmic cycling of chain against sprocket; the gentle hum of an electric motor;
the glistening elegance of morning dew on sleepy grass. Fog that highlights
beams of light completes the transformation into a wondrous adventure.

I make this journey free of the noisy commotion that is otherwise inescapable in
a town with so many people.

vale <test document> output:

 1:178  suggestion  Verify your use of 'against'    Microsoft.Vocab        
                    with the A-Z word list.                                
 1:194  suggestion  Try to simplify this sentence.  Microsoft.Semicolon    
 1:231  suggestion  Try to simplify this sentence.  Microsoft.Semicolon    
 3:1    warning     Use first person (such as 'I')  Microsoft.FirstPerson  
                    sparingly.                                             
 3:49   error       Use 'that's' instead of 'that   Microsoft.Contractions 
                    is'.     

[ccoVeille]

Can you provide a screenshot maybe?

[matthewelmer]

Can you provide a screenshot maybe?

[ccoVeille]

I confirm I don't have vale-native and vale work perfectly

[ccoVeille]

Update: vale/native/vale-native doesn't seem to be necessary. Dunno what it does, and since my vale is working now, I don't care!

I'll recount my installation procedure below as a first draft towards a "getting started" guide. Perhaps most of this procedure belongs in the README.md for vale itself, but that's a separate issue.

1. Install vale.
   • On Fedora Linux 40, I found it easiest to copy the precompiled binary from vale's GitHub releases page into my /home/$USER/bin directory.
2. Find out where your config file lives by running vale ls-dirs. Create the .vale.ini file if it isn't found.
   • It may also say that /path/to/vale-native wasn't found, but I didn't end up needing that file. I don't know what it does, but nor do I care since vale seems to work without it!
3. Generate a config file and copy the contents into your .vale.ini.
   • I went with the Microsoft style guide.
   • I tried the Readability supplementary style, but I found it to be unhelpful for my highly technical writing use case.
   • I used [*.{tex,md}] instead of [*], since I'm only interested in suggestions for my writing.
4. Run vale sync.
5. Install the Vale VSCode extension.
6. Restart VS Code.
7. Create a test document and see if everything is working. I've written a passage below along with the suggestions that I got for it.
   • If you see no squiggles in VS Code, something is wrong. Try running vale <test document> to see if you can get suggestions from the command line. If you can't, then something is broken with vale itself. If you can, then something might be broken with the Vale VSCode extension.

Passage:

There is a serene tranquility to the quiet hours of the early morning.
A secret world, all to myself. An otherwise ordinary commute instead offers the
rhythmic cycling of chain against sprocket; the gentle hum of an electric motor;
the glistening elegance of morning dew on sleepy grass. Fog that highlights
beams of light completes the transformation into a wondrous adventure.

I make this journey free of the noisy commotion that is otherwise inescapable in
a town with so many people.

vale <test document> output:

 1:178  suggestion  Verify your use of 'against'    Microsoft.Vocab        
                    with the A-Z word list.                                
 1:194  suggestion  Try to simplify this sentence.  Microsoft.Semicolon    
 1:231  suggestion  Try to simplify this sentence.  Microsoft.Semicolon    
 3:1    warning     Use first person (such as 'I')  Microsoft.FirstPerson  
                    sparingly.                                             
 3:49   error       Use 'that's' instead of 'that   Microsoft.Contractions 
                    is'.     

Sounds like a great guide.

Maybe you could add a step between 4 and 5 to validate vale works (outside VScode extension consideration)

Something like, launch vale . in a code folder, (not ~)

It should produce results like the one you describe at the end, then you can proceed to VScode extension setup

[matthewelmer]

Sounds like a great guide.

Maybe you could add a step between 4 and 5 to validate vale works (outside VScode extension consideration)

Something like, launch vale . in a code folder, (not ~)

It should produce results like the one you describe at the end, then you can proceed to VScode extension setup

Good suggestions. I may get back to this later, but for now I had better get to work on the document I set up vale for!