md: support displaying command snippets with Windows/OS/Linux tabs to select

[dashohoxha]

Extracted from #698 (comment) +

It would be nice to display command snippets with tabs "Linux/Mac" and "Windows", if they are different (similar to this example: https://dagshub.com/docs/pipeline/#featurization-or-pre-processing).

This page has some ideas about how it can be done: https://stackoverflow.com/questions/37606292/how-to-create-tabbed-code-blocks-in-mkdocs-or-sphinx
This one also has an example (class="codetabs"): https://raw.githubusercontent.com/apache/spark/master/docs/quick-start.md

We might try a syntax like this:

````dvc
```Linux/Mac
$ cat .gitignore
```
```Windows
$ type .gitignore
```
````

There are 4 backticks for the enclosing dvc block. It is a valid markdown syntax and normally it would render like this:

```Linux/Mac
$ cat .gitignore
```
```Windows
$ type .gitignore
```

The engine should render it with tabs, but even with normal markdown rendering it would appear somewhat acceptable.

[dashohoxha]

I am not sure how many users are using DVC on Windows, but it seems that there is a workaround by using a POSIX-like command line shell: https://dvc.org/doc/user-guide/running-dvc-on-windows#posix-like-command-line-shell
So, I would say that the priority of this issue is nice-to-have.

[jorgeorpinel]

at least one Windows user recently reported confusion that would be cleared with this improvement. See https://discordapp.com/channels/485586884165107732/485596304961962003/647534970272743424

[jorgeorpinel]

In order to move away from the research phase here, what do we need to decide? I think these are the questions:

1. What platforms/tabs will we support?
   I agree that 2 suffice: Linux/Mac terminal, and Windows cmd.
2. What format will we use in Markdon files to provide the different command samples?
   Here I think we just need to use new highlight formats like the ones suggested above. I'd go for POSIX and cmd though. I don't think we need to nest them in dvc blocks though, we can just add them one after the other and show only the one corresponding to the user's platform. (Not hiding lonely blocks)
3. How do we determine the user's platform?
   Obviously there should be a tab system so it can be chosen manually, but it could also be detected automatically via browser (defaulting to POSIX).

Thoughts @dashohoxha @shcheklein @leehanchung?

[jorgeorpinel]

I don't think we need to nest them in dvc blocks though, we can just add them one after the other and show only the one corresponding to the user's platform.

BTW that's basically the syntax for the tool mentioned in #698 (comment): Superfences (for MkDocs). It's open source code is also Python so maybe we can use it as base for our own functionality. See facelessuser/pymdown-extensions/.../pymdownx/superfences.py file (probably class SuperFencesTabPostProcessor).

[iesahin]

My 2c

Instead of updating the code sections manually, the engine can convert

$ dvc add path/to/file \
            path/to/another-file

to

$ dvc add path\to\file ^
                    path\to\another-file

for the Windows tab.

All command revisions I can think of are regular changes, / to \ in paths and \ to ^ in split commands. Once it's possible to have multiple tabs in code blocks, we can fill the Windows tab without modifying the markdown document.

Also, I don't think sniffing the browser to set the tabs is a good idea. People may use WSL or some other kind of shell, or connect to Linux boxes, etc. The default should be POSIX and if the user wants to see the Windows tab, it should stay that way by setting cookies.

What's the percentage of Windows users? @shcheklein

@jorgeorpinel

[jorgeorpinel]

Automatic conversion from Linux to Win would be nice as a fall back but some Windows blocks will be totally different i.e. the commands themselves are different.

[jorgeorpinel]

Hi @julieg18 ! Could iterative/cml.dev#70 / iterative/cml.dev#113 be ported over here to close this issue too? Cc @rogermparent Thanks

[rogermparent]

I'm pretty sure the mechanism can be ported, the cml docs engine is meant to be as close to the dvc.org one as possible.

[jorgeorpinel]

Thanks for #2914 @julieg18 ! Can you quickly summarize how to use the feature? Special format or HTML tags perhaps?

[jorgeorpinel]

Feel free to put the info under Usage in the description of #2939 actually @julieg18 (or here). Thanks