[vim/vim] Tweak documentation style in vim9.txt (PR #19250)
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)
You can view, comment on, or merge this pull request online at:
https://github.com/vim/vim/pull/19250
Commit Summary
- 43e8e72 Tweak documentation style in vim9.txt
File Changes
(1 file)
- M runtime/doc/vim9.txt (11)
Patch Links:
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
dkearns
dkearns left a comment (vim/vim#19250)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?
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.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
h_east
h-east left a comment (vim/vim#19250)These tag lines are fine.
Does this mean that my edits are correct?
(Even if you don't display Conceal, the text will still wrap once it exceeds 80 columns, right?)
I assume you mean examples like the following?
Yes.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
chrisbra left a comment (vim/vim#19250)Thanks, I think reformatting the tag lines are fine.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
dkearns
dkearns left a comment (vim/vim#19250)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.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
dkearns
dkearns left a comment (vim/vim#19250)@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).
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
chrisbra left a comment (vim/vim#19250)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.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.