docs: wrong use of diff highlighting + indentation problem

[bobertlo]

UPDATE: Jump to #1761 (comment)

---

I have opened an issue #1760 to fix the only important example, but I wonder if the rest of the 'diff' formatted code blocks might benefit from this? This PR is the only one that really sticks out but it is also slightly noticeably elsewhere. If there was positive feedback on this I would be happy to find other cases of this.

[jorgeorpinel]

I think we should indeed review all diff code blocks for consistency (some have more or less spaces after + for example) but Idk if we want to fix the indentation manually. Maybe better to report in https://github.com/PrismJS/prism/issues first?

[jorgeorpinel]

UPDATE: So, as pointed out by @efiop in https://github.com/iterative/dvc.org/pull/1760/files#r487469021, our current diff code blocks aren't actually diffs or patches. They intend to use whatever format git diff outputs. So we should probably not use the diff language in markdown.

So we can use dvc or no language. AND we should then probably align the lines manually, with a single space for lines that don't start with +.

[rogermparent]

I checked this out a little on my own when it popped up, and if I were to guess it seems to be an interaction between the indented Markdown list and however the code block is passed to Prism.

Here's all the existing diff blocks in the repo:

content/docs/start/data-access.md
78   ```diff

content/docs/start/data-pipelines.md
95     ```diff
164  ```diff

content/docs/command-reference/import-url.md
174  ```diff

content/docs/start/experiments.md
168  ```diff

The table that was pointed out in data-pipelines is the only one that has the issue, and the others I've looked at appear to be aligned correctly when compared to the source.

[jorgeorpinel]

Thanks for the list, we should look at all of those. And as an update to my previous message:

our current diff code blocks aren't actually diffs or patches

Actually we (and git diff) use patch format, but Prism doesn't seem to support that. Diff format is something else (what Git merge conflicts use).

[jorgeorpinel]

Another UPDATE:

AND we should then probably align the lines manually, with a single space

Unfortunately, using a single space like git diff would output doesn't seem to be displayed correctly by our engine for code blocks that are indented themselves . See #1760 (review)
Like Roger mentioned:

seems to be an interaction between the indented Markdown list and however the code block is passed to Prism

[bobertlo]

What if we changed the way we think about these listing? The core problem seems to be broken formatting in dirtree diff output, which is sort of an artificial concept.

Maybe we could look at this less as a 'look under the hood' and more of a 'verify your progress' and provide (sometimes abridged) outputs of reproducible commands:

1. If a user is to change the params file, provide a command git diff and mock the actual output expected.

2. If changes to multiple files are made, provide the appropriate git status or dvc status with (possibly abridged) expected outputs.

I think this would solve the formatting problem because it doesn't really matter in an actual diff context and as a bonus the sections would be more clear and useful (IMO). Saying 'what happens under the hood' sort of implies internal processes of DVC whereas looking at it from this angle implies more looking at and verifying the output of the processes.

Maybe this is a bit radical, and probably would be a separate issue, but it would close this issue I think.

[jorgeorpinel]

Hmmm sounds like much more effort than addressing this very specific formatting issue. And

2. If changes to multiple files are made, provide the appropriate git status

The output of git status will probably have the same problem. Unless I didn't get you right, of course.

Thanks for the ideas though.

[jorgeorpinel]

UPDATE: The YAML part is also mentioned in #1509. The diff part should be fixed by #2359 (which will close this issue).