5

I'd like to print a man style usage message to describe a shell function like this output man find:

NAME
       find - search for files in a directory hierarchy

SYNOPSIS
       find [-H] [-L] [-P] [-D debugopts] [-Olevel] [starting-point...] [expression]

DESCRIPTION
       This  manual  page  documents the GNU version of find.  GNU find searches the directory tree rooted at each
       given starting-point by evaluating the given expression from left to  right,  according  to  the  rules  of
       precedence  (see section OPERATORS), until the outcome is known (the left hand side is false for and opera‐
       tions, true for or), at which point find moves on to the next file name.  If no  starting-point  is  speci‐
       fied, `.' is assumed.

OPTIONS

I am facing an error message on the ` character.
Following simple script shows the error:

~$ cat <<EOF
`.'
EOF

bash: bad substitution: no closing "`" in `.'

I though heredoc was a cool way to echo strings by pasting them without having to escape its content such a quotes, etc... I assume I was wrong :/

Can someone explain this behavior please? Can heredoc accept ` character?

Edit 2: I accepted the answer of quoted here-document <<'END_HELP', but I finally won't use it for this kind of complete manual output as kusalananda does suggests

Edit 1: (For future reads) the limit with using quoted here-document is that is prevents to use tput in the here-document.
To do so, I did the following:

  1. unquoted here-document, for tput commands to be executed
  2. prevent the "bad substitution" error by escaping the backtick instead
  3. use tput within the here-document

Example:

normal=$( tput sgr0 ) ;
bold=$(tput bold) ;

cat <<END_HELP # here-document not quoted
${bold}NAME${normal}
       find - search for files in a directory hierarchy

${bold}SYNOPSIS${normal}
       find [-H] [-L] [-P] [-D debugopts] [-Olevel] [starting-point...] [expression]

${bold}DESCRIPTION${normal}
       This  manual  page  documents the GNU version of find.  GNU find searches the directory tree rooted at each
       given starting-point by evaluating the given expression from left to  right,  according  to  the  rules  of
       precedence  (see section OPERATORS), until the outcome is known (the left hand side is false for and opera‐
       tions, true for or), at which point find moves on to the next file name.  If no  starting-point  is  speci‐
       fied, \`.' is assumed.
END_HELP

unset normal ;
unset bold ;

Here, note the escaped backtick that was source of error:

\`.'
  • 3
    It's normal behaviour (the error message even explains the cause...) Quote EOF and it'll work. – don_crissti Feb 11 '18 at 15:22
8

The backtick introduces a command substitution. Since the here-document is not quoted, this will be interpreted by the shell. The shell complains since the command substitution has no ending backtick.

To quote a here-document, use

cat <<'END_HELP'
something something help
END_HELP

or

cat <<\END_HELP
something something help
END_HELP

Regarding your comments on the resolution of this issue:

Utilities seldom output a complete manual by themselves but may offer a synopsis or basic usage information. This is seldom, if ever, colorized (since its output may not be directed to a terminal or pager like less). The real manual is often typesetted using groff or a dedicated man-page formatter like mandoc and is handled completely separate from the code.

  • Thank you for the help, I did not know this escape form of EOF. – el-teedee Feb 11 '18 at 15:45
  • I edited my answer to finally use another way, let heredoc unquoted, quote the problematic backtick, so that I can also use tput colors, bold, etc... – el-teedee Feb 11 '18 at 16:29
  • 2
    @el-teedee Utilities seldom output a complete manual by themselves but may offer a synopsis or basic usage information. This is seldom, if ever, colorized (since its output may not be directed to a terminal). The real manual is often typesetted using groff and handled completely separate from the code. – Kusalananda Feb 11 '18 at 17:19
  • thank for precision, I will keep a simple usage message. – el-teedee Feb 11 '18 at 22:30
4

You want to specifically use a backtick/grave accent with the single quote/apostrophe to quote something? Please don't, the combination looks awful. In most fonts, the backtick is slanted, and the (ASCII) apostrophe is straight. This is how my browser shows the last line of your man page snippet:

enter image description here

If you want to use quotes that are fancier than the vertical ASCII quotes, you should probably use something like U+2018 and U+2019.

The output would of course depend on your fonts, but I think ‘this’ looks better than `this'.

  • No, I don't want specifically to use the backtip, I did just copy/paste the output of man find output to give a try. – el-teedee Feb 11 '18 at 16:11

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.