Ubuntu on WSL: improve consistency of paths used in terminal prompts in the docs

[edibotopic]

As the Ubuntu on WSL documentation refers to both terminal environments on Ubuntu (Bash) and Windows (PowerShell), we use terminal prompts ($, >) to distinguish between them.

In addition, we sometimes use paths within the prompts (~/a/path/to/some/dir) to signal where commands are being run or where files are being moved between.

We accept a degree of complexity here because it relates to the user experience of switching contexts between Ubuntu and Windows when using WSL.

However, we should not introduce additional complexity where it is not helpful. A problem that we have is inconsistency in how we refer to user and host names on a machine.

Consider these examples:

• username@pc:/mnt/c/Users/username$ (https://documentation.ubuntu.com/wsl/latest/howto/install-ubuntu-wsl2/)
• PS C:\Users\me> mkdir backup (https://documentation.ubuntu.com/wsl/latest/howto/backup-and-restore/)
• $ mv /mnt/c/Users/<yourusername>/Downloads/ubuntu-24.04.2-wsl-amd64.wsl ./ubuntu-24.04.2-wsl-amd64.tar (https://documentation.ubuntu.com/wsl/latest/howto/custom-ubuntu-distro/)
• C:\Users\<YOUR_WINDOWS_USER_NAME>\landscape_server.pem (https://documentation.ubuntu.com/wsl/latest/howto/set-up-landscape-client/

In these examples alone, we have username, me, <yourusername> and <YOUR_WINDOWS_USER_NAME> being used for the username. We should really only have one way of doing this.

If you are assigned this issue, you should seek to adopt a simple and consistent approach to prompt paths in the documentation, preferably with a single placeholder <placeholder> names used across the documentation for hostnames and usernames.

Note

You need to focus specifically on the username and hostname in the prompts.
Subtleties about the choice of prompts for PowerShell and Bash are outside the scope of this issue.

Tip

There may be cases where your preferred choice is not appropriate.
For example, the use of the placeholder <username> is common and should probably be used here.

However, in the tutorial we explain what a PowerShell prompt looks like with the example PS C:\Users\username>.
It makes less sense to substitute the placeholder here because we are not asking the user to run any command, so they won't be replaceing "username".
In addition, the result PS C:\Users\<username>> could be confusing because of the multiple angle brackets.

---

Please let me know if you are interested.

You will make your contribution directly to the Ubuntu Pro for WSL repo.

The Canonical CLA needs to be signed for your submission to be finalised.

[KrownWealth]

Hi @edibotopic if I understand the issue here very well, this means searhing the documentation for all instances of the examples you mentioned above, then replace with single consistent placeholder name, e.g or anyone of these two you would recommend.

Did my understand align well?

[edibotopic]

Hi @KrownWealth .

Yes, but this would involve not only searching the documentation for the examples I have given. It requires finding any prompt that includes a path related to Ubuntu or Windows.

In general, it should be possible to introduce more consistency. For example, there is no need to use username, user and your-username to refer to the same thing.

However, you need to be careful. For example, there is a directory called Users on Windows that is fixed, and is unrelated to this problem. There may be screenshots that use the prompt that you are replacing in the text. Additionally, as I mention above, there may be cases where we exclude the < and > around a placeholder because we are not asking the user to replace it.

So we need more consistency, but we need to proceed carefully, considering the context in which the prompt appears in the documentation.

[KrownWealth]

Thanks for the clarification!

From my understanding, the task involves going through the documentation and finding all terminal prompts that include a username or hostname, then replacing them with a consistent placeholder format.

As an example, when switching between Ubuntu and Windows in WSL, my own prompt looks like this:

deoladev@deoladev:/mnt/c/Users/HP/Desktop/Open Source/ubuntu-pro-for-wsl$

Which in the generalized placeholder form would be:

@:/mnt/c/Users//Desktop/Open Source/ubuntu-pro-for-wsl$

Applying this same consistency to the samples you mentioned above might look like this:

@:/mnt/c/Users/$

PS C:\Users<username>> mkdir backup

$ mv /mnt/c/Users//Downloads/ubuntu-24.04.2-wsl-amd64.wsl

C:\Users<username>\landscape_server.pem

This way, is used consistently across prompts, while still respecting the context (e.g., keeping C:\Users\ as a fixed Windows directory).

Do I get understand this correctly?

[edibotopic]

I would love to cite an example as a user switching contexts between Ubuntu and Windows when using WSL.

Could you expand on what you mean?

On my own Windows WSL machine, my prompt looks like this:

I think you forgot to include the prompt?

[KrownWealth]

I would love to cite an example as a user switching contexts between Ubuntu and Windows when using WSL.

Could you expand on what you mean?

On my own Windows WSL machine, my prompt looks like this:

I think you forgot to include the prompt?

I edited the response with the prompt

[edibotopic]

Do I get understand this correctly?

Yes. That sounds about right.

Of course, we can tweak things during review if necessary.

[KrownWealth]

Great, I would take the issue up. You can assign it to me.

[edibotopic]

Assigned. Thanks for the discussion 😃 .

Let me know if you have further questions.

[edibotopic]

Thanks for the PR @KrownWealth

I'll be on holidays from this Friday for a few days, so won't get to this for a little while.

[KrownWealth]

Acknowledge.