== The rules for combining things with Bourne shell 'here documents'

Shell here documents are relatively simple to use on their own, but
it's usually head-scratching to combine them with other things
(redirections, pipelines, or conditionals). To save me having to do
the experimentation and manpage reading the next time, here's the
simple version of the rules: ~~here documents always start at the
next line~~.

So you can write any number of other things on the same line
as the command with a here document:

>  cat <<EOF | ssh host ...
>  foo
>  EOF

But if you need to continue the whole thing on additional lines,
you must write the following commands after the here document:

>  ssh host ... <<EOF ||
>  foo
>  EOF
>  	echo "ssh failed"

However, 'next line' here means the next line as seen by the Bourne
shell *after* backslash-escaped newlines, so you cannot write the last
example with the ssh line ended with a '_\_' and the '_||_' at the
start of the _echo_ line. (This is a pity, as I think it would be more
readable. But frankly, combining here documents and multiple commands
this way is never going to be terribly readable.)

Because of this, other redirections can go anywhere on the command
line with the here document, as can arguments and so on; '_ssh <<EOF
host ... >logfile 2>&1_' is perfectly legal. The maximally perverse
version of this is:

>  <<EOF ssh host ... 
>  foo
>  EOF

My opinion is 'don't do that'; put the here document redirection
last on the line if at all possible, to avoid confusing [[other
people ../sysadmin/ScriptCodeReviews]].

Somewhat to my surprise it's possible to specify multiple here
documents on the same line. If you do this crazy thing, the
shell expects them to be in left to right order, eg:

>  sed 's/^/a: /' <<EOF && cat <<EF2
>  foo
>  EOF
>  bar
>  EF2

But, really, don't do this.