doc: :h let-heredoc needs another example for Vim9

[lacygoill]

In Vim9 script, we can't use a heredoc when its first line starts with a bar:

vim9script
var l =<< trim END
    |xxx
END

E488: Trailing characters:  |xxx

I think that's because a bar can be used as a line continuation symbol:

vim9script
  echo 'one'
| echo 'two'
| echo 'three'

one
two
three

And the line continuation is used before the heredoc command is parsed. So, in the previous broken snippet, Vim actually executes this:

vim9script
var l =<< trim END |xxx
END

Which is obviously wrong.

The help already gives the solution for the legacy line continuation symbol (i.e. the backslash). But there is no example for the bar continuation symbol (which is Vim9 specific). I think there should be one, for two reasons:

• users might not know that a bar can be used as a line continuation in Vim9
• there is a pitfall when trying to apply the given solution to a command inside a function

Regarding the last bullet point:

vim9script
def Func()
    set cpo+=C
    var l =<< trim END
        |xxx
    END
    set cpo-=C
enddef
defcompile

E488: Trailing characters:  |xxx

I think the issue persists because the concatenation step occurs before the compilation step; while the script is sourced. The solution is to include the C flag outside the function.

vim9script
set cpo+=C
def Func()
    var l =<< trim END
        |xxx
    END
enddef
set cpo-=C
defcompile

Although, this particular pitfall is not specific to Vim9:

fu Func()
    set cpo+=C
    let l =<< trim END
        \xxx
    END
    set cpo-=C
endfu
call Func()

E1145: Missing heredoc end marker: ENDxxx

---

As a suggestion, here is a patch:

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 890943810..053285794 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -12736,7 +12736,22 @@ text...
 					1 2 3 4
 					5 6 7 8
 				DATA
+
+<			In Vim9 script, a bar can be used as a line continuation
+			character: >
+				vim9script
+				set cpo+=C
+				def Func()
+				    var table =<< trim END
+					| some | table |
+					| with | cells |
+				    END
+				enddef
+				set cpo-=C
 <
+			Notice that 'C' must be added to 'cpo' before the
+			function is sourced.
+
 								*E121*
 :let {var-name}	..	List the value of variable {var-name}.  Multiple
 			variable names may be given.  Special names recognized

[brammool]

The simplest is to insert an empty line. If that is not desired, there are other ways then heredoc. It's a corner case, thus I indeed prefer to document the behavior rather than try to fix it (which will be quite complicated).

[lacygoill]

The simplest is to insert an empty line.

Ah yes:

vim9script
def Func()
    var table =<< trim END

	| some | table |
	|------+-------|
	| with | cells |
    END
    table->remove(0)
    echo table->join("\n")
enddef
Func()

| some | table |
|------+-------|
| with | cells |

Compared to tweaking 'cpo', it's simpler, more reliable, and requires less explanation.

It also works in legacy:

fu Func()
    let var =<< trim END

        \ leading backslash
        \ another leading backslash
    END
    eval var->remove(0)
    echo var->join("\n")
endfu
call Func()

\ leading backslash
\ another leading backslash