Tweak documentation style in vim9.txt

[h-east]

Fix over 80 columns.

---

• There are other lines that exceed 80 columns, but they have little impact and are numerous, so they are not included in this PR.
  But I think it should actually be fixed.

• Also, it's not common in Vim documentation to indent lines containing "Note:" to the character following "Note:". Above all, it doesn't contribute to readability. I'd appreciate it if we could fix it.

(Cc: @kennypete, @dkearns)

[dkearns]

The rule for textwidth was decided to be a rendered (i.e. with concealed text) 78 and that's what we, or at least I've, been using recently. So following that, these tag lines are fine.

I have a patch for checking the rendered line length to go with #18599 but I didn't add it yet as I planned to fix as much as practical first. I'll sort that PR out in the next day or so, sorry for stalling on it.

I also noted the hanging indent issue with notes and was going to raise it. I assume you mean examples like the following?

vim/runtime/doc/vim9.txt

Lines 26 to 32 in 4fcbc70

	NOTE: In this vim9.txt help file, the Vim9 script code blocks beginning
	with `vim9script` (and individual lines starting with `vim9cmd`) are
	Vim9 script syntax highlighted. Also, they are sourceable, meaning
	you can run them to see what they output. To source them, use
	`:'<,'>source` (see |:source-range|), which is done by visually
	selecting the line(s) with |V| and typing `:so`. For example, try it
	on the following Vim9 script: >vim9

I agree that that's inconsistent with the way they are handled throughout the rest of the documentation and I don't think it offers any improvement in readability either. Having "NOTE" highlighted is good enough and we can't really afford to lose all that space when we're restricted to 78 characters...like it's 1978.

[h-east]

These tag lines are fine.

Does this mean that my edits are correct?
(Even if we don't display Conceal, the text will still wrap once it exceeds 80 columns, right?)

I assume you mean examples like the following?

Yes.

[chrisbra]

Thanks, I think reformatting the tag lines are fine.

[dkearns]

Does this mean that my edits are correct? (Even if we don't display Conceal, the text will still wrap once it exceeds 80 columns, right?)

No, I meant the current formatting is fine and your change is not needed. 80 columns isn't a relevant number, as the text width is 78, and in some cases these lines will exceed 80 columns. This obviously happens when there are are many concealed items on a line. This is, I believe, a reflection of the status quo although there's lots of historical inconsistencies as you know.

In simple terms the rule I've been working to is to set 'colorcolumn' to 78 and ensure that no concealed lines exceed that boundary with the exception of examples.

[dkearns]

@chrisbra, I think we need hard rules. Formatting the help based on individual committer taste is why the formatting is currently so inconsistent.

If I hadn't noticed this change I'd probably undo it the next time I came across it based on #18599 (comment).

[chrisbra]

Then let's make it a hard rule: "Formatting should be done to 78 chars with concealing on. " I have also been using the 'colorcolumn' trick, is this good?

diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt
index c014e558c..f19c7dd86 100644
--- a/runtime/doc/helphelp.txt
+++ b/runtime/doc/helphelp.txt
@@ -418,8 +418,9 @@ STYLE
 If your Vim has 'modeline' enabled, Vim should follow the preferred style
 automatically when editing built-in help files.

-Vim help files should be formatted for a 'textwidth' of 78 characters, so they
-look good in a typical 80 x 24 terminal window.
+Vim help files should be formatted for a 'textwidth' of 78 characters (with
+'conceal' enabled), so they look good in a typical 80 x 24 terminal window;
+use `:set colorcolumn=+0` as a visual guide.

 Use two spaces between the final dot of a sentence of the first letter of the
 next sentence.  Like this.

[dkearns]

Yes, but I guess the real question that @h-east is getting at is what is the rule for when syn-conceal is disabled? As so many examples run well over even 80 characters I haven't considered there to be any limit.

Personally, I think the use of concealed chars in the help is a bit of a mistake. Aside from the, sometimes, significant differences in line length it makes :helpgrep searching difficult.

[chrisbra]

Do we need a strict rule when syn-concealed is disabled? I'd think we should concentrate on the default help page rendering, e.g. when concealing is enabled. If people disable it intentionally (or in a tiny build?) I'd excuse that this looks slightly off. Same for help examples, trying to restrict those to 78 chars will limit us too much and probably also hurt readability, so that would be an acceptable exception I think.

Personally, I think the use of concealed chars in the help is a bit of a mistake. Aside from the, sometimes, significant differences in line length it makes :helpgrep searching difficult.

I haven't notice the helpgrep issue yet, but I think it makes sense to hide some of those noisy atoms and it does gives a much more pleasant reading experience.

[kennypete]

Then let's make it a hard rule: "Formatting should be done to 78 chars with concealing on. "

I presumed that was what the rule was already, so all good.

There may be many concealed characters when either several hot-links or tags appear on a line. Some lines with hot-links, especially, would look oddly short if their | were counted in the 78 limit. When really pushed for space, though, does occasionally going to 79 hurt?

... I have also been using the 'colorcolumn' trick, is this good?

Good? Yes. Everyone writing help should use 'colorcolumn' because it assists greatly in keeping within the display limit.

Incidental: I don't think there is any builtin function or combination that will provide the number of the display width of a line excluding concealed characters? I'd love to know if there is one: col() and virtcol() don't, and when diving into string length/width measurement one day, writing String measurement in Vim, did not find it in other builtin functions.

[h-east]

I wrote “80 columns,” but in reality I’m just running {Visual}gq (see :h v_gq) with tw=78 set in the modeline. So the correct value is “78 columns.” My apologies for the mistake.

[dkearns]

Do we need a strict rule when syn-concealed is disabled? I'd think we should concentrate on the default help page rendering, e.g. when concealing is enabled. If people disable it intentionally (or in a tiny build?) I'd excuse that this looks slightly off. Same for help examples, trying to restrict those to 78 chars will limit us too much and probably also hurt readability, so that would be an acceptable exception I think.

Ignoring the non-concealed length can be a strict rule. It just simplifies editing and particularly automation and prevents multiple editors unintentionally bouncing back and forth around the edge cases. It doesn't bother too much what the rules actually are.

Personally, I think the use of concealed chars in the help is a bit of a mistake. Aside from the, sometimes, significant differences in line length it makes :helpgrep searching difficult.

I haven't notice the helpgrep issue yet, but I think it makes sense to hide some of those noisy atoms and it does gives a much more pleasant reading experience.

I'm not really proposing that we change it but I often grep for phrases in the help and have to take into account the formatting options if the phrase includes something likely to be marked up. Much of it is just a limitation of the conceal feature as implemented. Ideally there'd be an ability to optionally treat the rendered text as first class.

[dkearns]

Incidental: I don't think there is any builtin function or combination that will provide the number of the display width of a line excluding concealed characters? I'd love to know if there is one: col() and virtcol() don't, and when diving into string length/width measurement one day, writing String measurement in Vim, did not find it in other builtin functions.

I have a Vim script function to check the concealed length. I was going to add it to #18599 but it was a bit slow and, of course, there were many failures if it was going to be enabled by default.

[h-east]

I often use :helpgrep, but I have never felt sorry for it. I would like to know specifically what situations you feel are unfortunate.

[dkearns]

I often use :helpgrep, but I have never felt sorry for it. I would like to know specifically what situations you feel are unfortunate.

Any string of text potentially contains markup and it's not feasible to replace word boundaries in searches with even likely markup patterns.

For a very simple example, and ignoring for demonstration purposes that most of these should probably be normalised to "Return a |List|", the following return different results.

:helpgrep \creturn a list
vs
:helpgrep \creturn a |list|

The normal user just wants the combined results, using only the first command.

[kennypete]

Also, it's not common in Vim documentation to indent lines containing "Note:" to the character following "Note:". Above all, it doesn't contribute to readability. I'd appreciate it if we could fix it.

Sure, will do. Although I disagree with the readability point, notes are almost universally not indented. [Amusingly, from a quick look, the only other instance I could find is in indent.txt.] So, for consistency, and the compelling space saving argument, I'll standardise all the Note(s) to no indent with my next vim9.txt PR, which is not far away.

[h-east]

What I'm pointing out is that you should align the second and subsequent lines of Note: with the beginning of Note: , as most other documentation suggests.

If you run :helpgrep ^\s*Note: and then use :copen you will see many examples.

Good example (:help -c):

		Note: You can use up to 10 "+" or "-c" arguments in a Vim
		command.  They are executed in the order given.  A "-S"
		argument counts as a "-c" argument as well.

Bad example 1:

		  Note: You can use up to 10 "+" or "-c" arguments in a Vim
				command.  They are executed in the order given.  A "-S"
				argument counts as a "-c" argument as well.

Bad example 2:

		Note: You can use up to 10 "+" or "-c" arguments in a Vim
			  command.  They are executed in the order given.  A "-S"
			  argument counts as a "-c" argument as well.

[kennypete]

What I'm pointing out is that you should align the second and subsequent lines of Note: with the beginning of Note: , as most other documentation suggests.

If you run :helpgrep ^\s*Note: and then use :copen you will see many examples.

Yes, already understood, hence my previous response saying I'd standardise it to no indent. I have done that already (and it will be in the next PR, which is a few days away).

I'd already :helpgrep-ed it to see what was elsewhere and, aside from the one instance in indent.txt, below, all others I looked at have no indent:

[kennypete]

I have a Vim script function to check the concealed length. I was going to add it to #18599 but it was a bit slow and, of course, there were many failures if it was going to be enabled by default.

I now have a Vim9 script for that check too. It seems to be giving correct textwidth minus concealed results to the location list. Here's output showing three >78 lines reported in vi_diff.txt, which raises the specific question ... URIs are an exception?

[h-east]

I'd already :helpgrep-ed it to see what was elsewhere and, aside from the one instance in indent.txt, below, all others I looked at have no indent:

Here's a bit more information: I was able to find a few more instances using the following command. In reality, there may be even more occurrences, since I suspect there are cases where the whitespace differs between the first and second lines.

:cd /path-to-your-vim/runtime/doc
:vimgrep "^\(\s*\)Note:.*$\n\1\s\+\a" *.txt
:copen

Also, the search pattern \%>v is handy (:h \%>v). If you open a document and search for /\%>79v, it will match any characters past column 79.

:set hlsearch
/\%>79v

Sorry if you were already aware 😄

[dkearns]

I now have a Vim9 script for that check too. It seems to be giving correct textwidth minus concealed results to the location list. Here's output showing three >78 lines reported in vi_diff.txt, which raises the specific question ... URIs are an exception?

I was treating them as an exception, yes.