Removed $ symbol from code blocks in the Docs

[Santosh1176]

Signed-off-by: Santosh Kaluskar [email protected]

Removed all the $ symbol from the code blocks in the docs, eliminating the possibility of copying the $ to the clipboard using the copy button.

This PR resolves Issue #375

[netlify]

✅ Deploy Preview for osm-docs ready!

Name	Link
🔨 Latest commit	3fae73b
🔍 Latest deploy log	https://app.netlify.com/sites/osm-docs/deploys/62d5930cd3e2d10008550e1b
😎 Deploy Preview	https://deploy-preview-392--osm-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[shashankram]

For snippets where the output is displayed along with the command, having the $ symbol distinguishes the command from its output, otherwise, it can be hard to know whether these are multiple commands or if it's the output of a single command. For console blocks, I feel having the $ symbol helps.

[phillipgibson]

I agree with @shashankram that the '$' does represent the command. We could put output in it's own block <``> if that makes it clearer, but not sure that is necessary.

[Santosh1176]

For snippets where the output is displayed along with the command, having the $ symbol distinguishes the command from its output, otherwise, it can be hard to know whether these are multiple commands or if it's the output of a single command. For console blocks, I feel having the $ symbol helps.

I agree, that this is a matter to be deliberated upon. As many code blocks do have a command and an output combined in a block. That would surely confuse the users in distinguishing the command to operate and the output to expect from it.

I tried a solution to omit the $ sign while copying but, couldn't find one.

My suggestion for that kind of code block would be to separate the input and output codes. And, to display the output in a separate indented code block or add an # symbol for output to differentiate, maybe?

views appreciated!

[shashankram]

For snippets where the output is displayed along with the command, having the $ symbol distinguishes the command from its output, otherwise, it can be hard to know whether these are multiple commands or if it's the output of a single command. For console blocks, I feel having the $ symbol helps.

I agree, that this is a matter to be deliberated upon. As many code blocks do have a command and an output combined in a block. That would surely confuse the users in distinguishing the command to operate and the output to expect from it.

I tried a solution to omit the $ sign while copying but, couldn't find one.

My suggestion for that kind of code block would be to separate the input and output codes. And, to display the output in a separate indented code block or add an # symbol for output to differentiate, maybe?

views appreciated!

It seems like a better solution would be to remove the selection of the dollar sign in code block selection. I am not familiar with the internals of how this can be achieved with Hugo, but you might find theme-next/hexo-theme-next#448 (comment) useful.

[Santosh1176]

Thanks for the link @shashankram, I went into the rabbit hole. But, could not get hold of the implementation process. I also found an option to escape the $ while the copy button is clicked, not sure how to implement it on all the docs.

How do you propose we move on from here?

[zr-msft]

I'd recommend separating the command into one code fence without the $ and the output in a different code fence. The second code fence can contain only the output or both the command (with the $) and the output. For example:
https://docs.microsoft.com/en-us/azure/aks/open-service-mesh-deploy-addon-az-cli#verify-that-the-osm-mesh-is-running-on-your-cluster

[Santosh1176]

I'd recommend separating the command into one code fence without the $ and the output in a different code fence. The second code fence can contain only the output or both the command (with the $) and the output. For example: https://docs.microsoft.com/en-us/azure/aks/open-service-mesh-deploy-addon-az-cli#verify-that-the-osm-mesh-is-running-on-your-cluster

Thanks for the suggestion. I hope you are suggesting this format:

[shashankram]

Thanks for the link @shashankram, I went into the rabbit hole. But, could not get hold of the implementation process. I also found an option to escape the $ while the copy button is clicked, not sure how to implement it on all the docs.

How do you propose we move on from here?

I am not very familiar with Hugo and CSS, but there should be a way to achieve this.
I am also not in favor of breaking up the command and output into 2 separate blocks if there is a way to avoid the selection of the $ sign. Let's explore whether we can disable the selection of $ before refactoring all the code blocks.

[shashankram]

Thanks for the link @shashankram, I went into the rabbit hole. But, could not get hold of the implementation process. I also found an option to escape the $ while the copy button is clicked, not sure how to implement it on all the docs.
How do you propose we move on from here?

I am not very familiar with Hugo and CSS, but there should be a way to achieve this. I am also not in favor of breaking up the command and output into 2 separate blocks if there is a way to avoid the selection of the $ sign. Let's explore whether we can disable the selection of $ before refactoring all the code blocks.

Based on my research, this should be possible using Hugo shortcodes. You would need to:

1. Add a new layout for code blocks that defines the shortcodes
2. Update the code blocks to leverage the defined shortcode as a template

[shashankram]

Thanks for the link @shashankram, I went into the rabbit hole. But, could not get hold of the implementation process. I also found an option to escape the $ while the copy button is clicked, not sure how to implement it on all the docs.
How do you propose we move on from here?

I am not very familiar with Hugo and CSS, but there should be a way to achieve this. I am also not in favor of breaking up the command and output into 2 separate blocks if there is a way to avoid the selection of the $ sign. Let's explore whether we can disable the selection of $ before refactoring all the code blocks.

Based on my research, this should be possible using Hugo shortcodes. You would need to:

1. Add a new layout for code blocks that defines the shortcodes
2. Update the code blocks to leverage the defined shortcode as a template

@Santosh1176 I spent time researching the options, and it seems like we would need to use a combination of Hugo shortcodes and embedded format blocks, and then disable $ selection at the start of the line for specific command blocks. I am afraid testing this across all the docs is not going to be easily feasible, so unless we are 100% certain this works, it may not be a good idea as I initially thought.

Simplest would be to do the following for console blocks:

1. Change console to bash, and only specify the command without the $ sign
2. Break the command and output into separate blocks with additional details.

E.g.

kubectl get service

The output is similar to:

NAME         TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP   2d

[Santosh1176]

@shashankram Thanks for the reply, I am trying to wrap my head around Hugo Shortcodes but, I feel it's a bit hard to implement it on all of the osm docs. I agree with your suggestion of initially separating the commands without the $ sign and expected output in separate code blocks. And, also changing the bash to console. Should I start working on this? or should I wait for more input on this?

[shashankram]

@shashankram Thanks for the reply, I am trying to wrap my head around Hugo Shortcodes but, I feel it's a bit hard to implement it on all of the osm docs. I agree with your suggestion of initially separating the commands without the $ sign and expected output in separate code blocks. And, also changing the bash to console. Should I start working on this? or should I wait for more input on this?

That seems good to me. I'll let other maintainers on the project comment on it if they have any hesitation with this approach. Since I have looked into using shortcodes + preformatted blocks, I think I can confidently say the approach to split the console blocks into 2 bash blocks as suggested in #392 (comment) would work best.

Also don't forget to update/rebase your tree as it is out of sync with main.

[shalier]

Looks like this PR will also resolve #374

[Santosh1176]

Hi, I've modified the code blocks to show the command and the output in separate code blocks. I've only made changes to the DEMO section of the docs. Could someone please review the changes? Also, I've updated the tree by pulling the latest history. I am getting some merge conflicts can someone please help me with that.

[phillipgibson]

I'm fine moving from using bash to console in the docs. We can update this as the primary method of showing commands in a terminal.

[zr-msft]

thanks @Santosh1176

you'll need to pull in the latest changes to resolve the conflicts. I'd also like to see all the docs updated for consistency, but i understand its a lot of work. If you don't have the bandwidth to include updating the rest of the docs in this PR, please add a comment and we'll find a way to work around it.

[Santosh1176]

Thanks @zr-msft for reviewing the PR. Let me resolve the issues along with latest changes. Then I'll start with the updating the remaining docs.

[phillipgibson]

@zr-msft is this good to merge? I'm trying to close out all relevant PRs for the project. Thanks.

[zr-msft]

@phillipgibson no, see the below conflicts that would need to be resolved before merging

[phillipgibson]

@Santosh1176 are you looking to fix the outstanding issues to have this get merged? If not we'll close this out by the end of the week. It's been idle since Sept '22.