"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}
    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.
   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}.
   17 Two sorts of comments are supported by \app{gretl}.  The simpler one
   18 is this:
   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}
   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.
   29 The second sort of comment is patterned after the C programming language:
   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}
   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.
   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:
   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}
   54 This means that each sort of comment can be masked by the other.  
   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}
   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.
   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 %