"Fossies" - the Fresh Open Source Software Archive

Member "gretl-2019c/doc/tex/comments.tex" (2 Oct 2015, 3214 Bytes) of package /linux/misc/gretl-2019c.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 \chapter{Comments in scripts}
    2 \label{chap:comments}
    3 
    4 When a script does anything non-obvious, it's a good idea to add
    5 comments explaining what's going on.  This is particularly useful if
    6 you plan to share the script with others, but it's also useful as a
    7 reminder to yourself --- when you revisit a script some months later
    8 and wonder what it was supposed to be doing.
    9 
   10 The comment mechanism can also be helpful when you're developing a
   11 script.  There may come a point where you want to execute a script,
   12 but bypass execution of some portion of it.  Obviously you could
   13 delete the portion you wish to bypass, but rather than lose that
   14 section you can ``comment it out'' so that it is ignored by
   15 \app{gretl}.
   16 
   17 Two sorts of comments are supported by \app{gretl}.  The simpler one
   18 is this:
   19 
   20 \begin{itemize}
   21 \item If a hash mark, \texttt{\#}, is encountered in a \app{gretl} script, 
   22   everything from that point to the end of the current line is treated as a 
   23   comment, and ignored.
   24 \end{itemize}
   25 
   26 If you wish to ``comment out'' several lines using this mode, you'll
   27 have to place a hash mark at the start of each line.
   28 
   29 The second sort of comment is patterned after the C programming language:
   30 
   31 \begin{itemize}
   32 \item If the sequence \texttt{/*} is encountered in a script, all the
   33   following input is treated as a comment until the sequence \texttt{*/}
   34   is found.
   35 \end{itemize}
   36 
   37 Comments of this sort can extend over several lines.  Using this mode
   38 it is easy to add lengthy explanatory text, or to get \app{gretl} to
   39 ignore substantial blocks of commands.  As in C, comments of this
   40 type cannot be nested.
   41 
   42 How do these two comment modes interact?  You can think of
   43 \app{gretl} as starting at the top of a script and trying to decide at
   44 each point whether it should or should not be in ``ignore mode''.  In
   45 doing so it follows these rules:
   46 
   47 \begin{itemize}
   48 \item If we're not in ignore mode, then \texttt{\#} puts us into ignore
   49   mode till the end of the current line.
   50 \item If we're not in ignore mode, then \texttt{/*} puts us into ignore
   51   mode until \texttt{*/} is found.
   52 \end{itemize}
   53 
   54 This means that each sort of comment can be masked by the other.  
   55 
   56 \begin{itemize}
   57 \item If \texttt{/*} follows \texttt{\#} on a given line which does
   58   not already start in ignore mode, then there's nothing special about
   59   \texttt{/*}, it's just part of a \texttt{\#}-style comment.
   60 \item If \texttt{\#} occurs when we're already in ignore mode, it is
   61   just part of a comment.
   62 \end{itemize}
   63 
   64 A few examples follow.
   65 %
   66 \begin{code}
   67 /* multi-line comment
   68    # hello
   69    # hello */
   70 \end{code}
   71 %
   72 In the above example the hash marks are not special; in particular
   73 the hash mark on the third line does not prevent the multi-line
   74 comment from terminating at \texttt{*/}.
   75 %
   76 \begin{code}
   77 # single-line comment /* hello
   78 \end{code}
   79 %
   80 Assuming we were not in ignore mode before the line shown above, it is
   81 just a single-line comment: the \texttt{/*} is masked, and does not
   82 open a multi-line comment.
   83 
   84 You can append a comment to a command:
   85 %
   86 \begin{code}
   87 ols 1 0 2 3 # estimate the baseline model
   88 \end{code}
   89 %
   90 Example of ``commenting out'':
   91 %
   92 \begin{code}
   93 /*
   94 # let's skip this for now
   95 ols 1 0 2 3 4
   96 omit 3 4
   97 */
   98 \end{code}
   99 %
  100 
  101 
  102 
  103 
  104 
  105