gawk: Comments

1 
1 1.1.5 Comments in 'awk' Programs
1 --------------------------------
1 
1 A "comment" is some text that is included in a program for the sake of
1 human readers; it is not really an executable part of the program.
1 Comments can explain what the program does and how it works.  Nearly all
1 programming languages have provisions for comments, as programs are
1 typically hard to understand without them.
1 
1    In the 'awk' language, a comment starts with the number sign
1 character ('#') and continues to the end of the line.  The '#' does not
1 have to be the first character on the line.  The 'awk' language ignores
1 the rest of a line following a number sign.  For example, we could have
1 put the following into 'advice':
1 
1      # This program prints a nice, friendly message.  It helps
1      # keep novice users from being afraid of the computer.
1      BEGIN    { print "Don't Panic!" }
1 
1    You can put comment lines into keyboard-composed throwaway 'awk'
1 programs, but this usually isn't very useful; the purpose of a comment
1 is to help you or another person understand the program when reading it
1 at a later time.
1 
1      CAUTION: As mentioned in ⇒One-shot, you can enclose short to
1      medium-sized programs in single quotes, in order to keep your shell
1      scripts self-contained.  When doing so, _don't_ put an apostrophe
1      (i.e., a single quote) into a comment (or anywhere else in your
1      program).  The shell interprets the quote as the closing quote for
1      the entire program.  As a result, usually the shell prints a
1      message about mismatched quotes, and if 'awk' actually runs, it
1      will probably print strange messages about syntax errors.  For
1      example, look at the following:
1 
1           $ awk 'BEGIN { print "hello" } # let's be cute'
1           >
1 
1      The shell sees that the first two quotes match, and that a new
1      quoted object begins at the end of the command line.  It therefore
1      prompts with the secondary prompt, waiting for more input.  With
1      Unix 'awk', closing the quoted string produces this result:
1 
1           $ awk '{ print "hello" } # let's be cute'
1           > '
1           error-> awk: can't open file be
1           error->  source line number 1
1 
1      Putting a backslash before the single quote in 'let's' wouldn't
1      help, because backslashes are not special inside single quotes.
1      The next node describes the shell's quoting rules.
1