search

aserebryakov / filestyle

filestyle is a Vim plugin that highlights unwanted whitespace and characters.
http://www.vim.org/scripts/script.php?script_id=5065
Apache License 2.0
30 stars 5 forks source link

Updated docs, fixed typos, improved order of highlights #26

Closed Markus00000 closed 9 years ago

aserebryakov commented 9 years ago

Hi, can you please fix misspelling in my family name in "contributors" section and update the filestyle.txt file?

Markus00000 commented 9 years ago

I copied your truncated name from my email program... Sorry!

I’ll update filestyle.txt and let you know.

aserebryakov commented 9 years ago

It's ok.

Can you please explain change in order of highlightings?

Markus00000 commented 9 years ago

Sure. The idea is to give the user as much information as possible, or at least the most important.

Assume this order:

call FileStyleExpandtabCheck()
call FileStyleTrailingSpaces()

And assume to have this line:

This is an example.\t\t

\t\t can be both a tab that violates expandtab (red) and trailing whitespace (cyan). So, which color to pick?

Cyan makes those tabs look like trailing spaces. We lose some information, namely, that they are tabs.

Red shows us that there are tabs violating expandtab. In addition, it is obvious that these tabs are trailing as there are not any characters to their right. Therefore, red gives more information than cyan. That is why I changed their order.

Another example. I put FileStyleLongLines after both FileStyleExpandtabCheck and FileStyleTrailingSpaces. Why? Assume to have this line:

This line is longer than textwidth and has trailing spaces

Should these trailing spaces be highlighted cyan or inverse?

Cyan tells us they are trailing spaces. At the same time, we lose the ability to see that they are violating textwidth.

If we highlight them inverse, we see the textwidth violation. In addition, it is obvious that they are trailing whitespace as there are no more characters to their right. (The only bit of information we lose is that they are spaces and not tabs.)

Does this explain why I reordered the checks?

aserebryakov commented 9 years ago

Yes, it is not bad idea to provide to user more information about what he is doing.

Markus00000 commented 9 years ago
  1. Updated filestyle.txt and README.md. One goal was to have as few differences as possible between the files to make future changes easier.
  2. After looking at Vim docs of several other plugins, I adjusted the formatting of filestyle.txt.
  3. I changed the tag line ("highlights whitespace that violates your buffer settings") as filestyle no longer only checks for violations of buffer settings. For example, trailing spaces or control characters do not violate buffer settings. The new tag line is: "Highlights unwanted whitespace and characters."
  4. The filestyle commands are not documented in a way that they show up in the completion after :help. They also cannot be linked in filestyle.txt. What do you think, should this be fixed?

Make sure you are happy with all changes before merging anything. I changed quite a bit and I do not want to hijack your plugin.

aserebryakov commented 9 years ago

I will check all the changes as soon as I will have a free time.

As for commands help, I am not sure that it is necessary to do right now due to the reason that README.md and filestyle.txt are pretty short at the moment.

Markus00000 commented 9 years ago

Take your time.

I have now created links for the commands and options. You will see it in filestyle.txt. This is certainly more convenient for users to quickly find the section they want to read.