Linux inside WSL installation docs need more detail

[elliot-100]

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

What would you like to see changed/added?

Just tried installing oh-my-posh for the first time on Ubuntu 24.04 LTS within WSL, and I feel that the docs could be improved.

1. I read the Windows install docs:

   CAUTION When using oh-my-posh inside the WSL, make sure to follow the [Linux] (https://ohmyposh.dev/docs/installation/linux) installation guide.

   So went there and tried to use this manual command:

   Install the latest version for your system by running the following command: curl -s https://ohmyposh.dev/install.sh | bash -s

   But this gave me:

   'Cannot write to /usr/local/bin. Please check write permissions or set a different directory and try again: curl -s https://ohmyposh.dev/install.sh | bash -s -- -d {directory}'

   so I needed to use:

   curl -s https://ohmyposh.dev/install.sh | sudo bash -s

   I feel this scenario should be covered.

2. Font installation docs don't cover the WSL case. I suggest there should be a simple warning e.g.:

   CAUTION When using oh-my-posh inside WSL, you can only use fonts installed on the Windows host. You could install oh-my-posh on Windows as well to achieve this.

3. In the Customize docs, the first two code snippets appear to contain a Powershell command (?) - It doesn't seem to be documented what the Linux e.g. bash equivalent would be:

   oh-my-posh init pwsh --config 'C:/Users/Posh/jandedobbeleer.omp.json' | Invoke-Expression

   oh-my-posh init pwsh --config 'https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/jandedobbeleer.omp.json' | Invoke-Expression

[JanDeDobbeleer]

I feel this scenario should be covered.

@elliot-100 this is covered in the following text on the docs:

By default the script will install to /usr/local/bin or the existing Oh My Posh executable's installation folder. If you want to install to a different location you can specify it using the -d flag

You decided to go down the sudo route, which I wouldn't advice, which is also why this isn't mentioned in the docs.

Font installation docs don't cover the WSL case.

Fonts are always a host system setting, it's the application that loads font, in this case Windows Terminal. I probably incorrectly assumed that this is common knowledge. Same goes for containers.

the first two code snippets appear to contain a Powershell command (?)

I purposefully added that first sample as an explanation as the syntax per shell is described below. Might have to swap that.

[elliot-100]

I appreciate your responses @JanDeDobbeleer and please note I'm readng the docs with very basic Linux knowledge - just enough to be able to set up a development environment for Python within WSL.

So I'm aware I may not be the target audience, and please read everything I say within that context.

Having said that, "CAUTION When using oh-my-posh inside the WSL, make sure to follow the Linux installation guide." gave me a big signpost that (1) the docs were intended for those with a very basic level of knowledge, and (2) covers the WSL case, and that's why I went ahead with the rest.

@elliot-100 this is covered in the following text on the docs:

By default the script will install to /usr/local/bin or the existing Oh My Posh executable's installation folder. If you want to install to a different location you can specify it using the -d flag

This does not cover my actual case of hitting an error with the install command. Which was my experience with a fresh install of Ubuntu 24.04 LTS which is one of the WSL built-in options. So quite likely to be a common issue.

You decided to go down the sudo route, which I wouldn't advice, which is also why this isn't mentioned in the docs.

That is fair, perhaps I should have raised an issue at this point.

Font installation docs don't cover the WSL case.

Fonts are always a host system setting, it's the application that loads font, in this case Windows Terminal. I probably incorrectly assumed that this is common knowledge. Same goes for containers.

I agree this is basic knowledge, and in fact even I didn't mess this up, but again "When using oh-my-posh inside the WSL, make sure to follow the Linux installation guide" sets a very low barrier, and I feel that adding a note would help.

the first two code snippets appear to contain a Powershell command (?)

I purposefully added that first sample as an explanation as the syntax per shell is described below. Might have to swap that.

Yes, I worked that out and used an amended version of eval "$(oh-my-posh init bash --config ~/jandedobbeleer.omp.json)" from later on the page. But when reading:

To set a new config/theme you need to change the --config option of the oh-my-posh init line in your profile or .rc script (see prompt) and point it to the location of a predefined theme or custom configuration. There are two possible values the --config flag can handle

One would expect examples of file-based config to follow, as that is lowest-common-denominator behaviour, not a config command, which is a shortcut.

[JanDeDobbeleer]

@elliot-100 I'll see what I can do to make this more clear without adding a lot more warning boxes. There's a balance to be kept here.

[elliot-100]

One other source of my confusion is that the installation pages for all platforms have a 'Next' section with

(optional) configure a theme or custom prompt configuration

I think 'custom prompt configuration' is supposed to link to https://ohmyposh.dev/docs/installation/prompt instead. Perhaps 'configure a theme' is supoosed to link to https://ohmyposh.dev/docs/installation/customize?

[elliot-100]

@elliot-100 I'll see what I can do to make this more clear without adding a lot more warning boxes. There's a balance to be kept here.

Thanks @JanDeDobbeleer - comments crossed over on patchy connection. And thanks for the tool, of course!!!