\usepackage{ifthen}

\newcommand{\commenter}[1]{\textbf{#1}:}

\ifthenelse{\equal{\showcomments}{true}}{
    \newcommand{\comment}[2]{\footnote{\commenter{#1} #2}}
}{
    \newcommand{\comment}[2]{}
} 

\ifthenelse{\equal{\showresolvedcomments}{true}}{
    \newcommand{\resolvedcomment}[3]{\footnote{\commenter{#1} #2 \\
    \textbf{Resolution:} #3}}
}{
    \newcommand{\resolvedcomment}[3]{}
} 

%-----------------------------------------------------------------------------%

\newcommand{\backsl}{\symbol{92}}
\newcommand{\carat}{\symbol{94}}
\newcommand{\n}{\symbol{95}}

\newcommand{\nl}{\texttt{\backsl{}n}}
\newcommand{\spc}[1]{\texttt{{#1}SP}}

\newenvironment{productions}
    {\begin{tabbing}}
    {\end{tabbing}}
\newcommand{\production}[1]{xxx \= \nt{#1} ::\== \= \kill \> \nt{#1} ::=}
\newcommand{\alt}{\\ \>\>~$\mid$~}  % alternative
\newcommand{\altB}{$\mid$~}         % alternative, doesn't insert newline
\newcommand{\spl}{\\ \>\>\>}        % for splitting a production across a line
\newcommand{\nt}[1]{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}}
\newcommand{\nti}[2]{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle_{#2}}}
%\newcommand{\term}[1]{\underline{\textbf{#1}}}
\newcommand{\term}[1]{\underline{\texttt{#1}}}
\newcommand{\slist}[2]{#1 \term{#2} \ldots} % symbol-separated/terminated list
\newcommand{\commas}[1]{\slist{#1}{,}}      % comma-sep'd/term'd list
\newcommand{\semicolons}[1]{\slist{#1}{;}}  % semi-colon-sep'd/term'd list
\newcommand{\pipes}[1]{\slist{#1}{\bar}}       % pipe-sep'd/term'd list
\newcommand{\maybe}[1]{[ #1 ]}              % optional item
\newcommand{\parens}[1]{\term{(} #1 \term{)}}       % parentheses
\newcommand{\curlies}[1]{\term{\{} #1 \term{\}}}   % curly braces
\newcommand{\squares}[1]{\term{[} #1 \term{]}}      % square brackets
\newcommand{\squaresPipes}[1]{\term{[\bar} #1 \term{\bar]}}  % [| |]
\newcommand{\zeroOrMore}[1]{( #1 )*}        % zero or more items
\newcommand{\oneOrMore}[1]{( #1 )+}         % one or more items
\newcommand{\regexp}[1]{\texttt{#1}}        % regexp-as-production
\newcommand{\dotdotXX}[1]{#1 \term{..} #1}  % X..X
\newcommand{\dotdotXY}[2]{#1 \term{..} #2}  % X..Y

\renewcommand{\bar}{|}

\newcommand{\dontknow}{\texttt{\n{}}}

\newcommand{\Rationale}[1]{\emph{\textbf{Rationale.}  #1}}
\newenvironment{RationaleEnv}{\em\textbf{Rationale.}}{\em}

%-----------------------------------------------------------------------------%
\newcommand{\CommonMiniZincPaperTitleAndAuthors}{\emph{MiniZinc: Towards a
Standard CP Modelling Language}, by Nethercote, Stuckey, Becket, Brand, Duck
and Tack}

%-----------------------------------------------------------------------------%
\newcommand{\CommonTwoConceptualParts}[2]{
Conceptually, a #1 problem specification has two parts.
\begin{enumerate}
\item The \emph{model}: the main part of the problem specification, which
      describes the structure of a particular class of problems.
\item The \emph{data}: the input data for the model, which specifies one
      particular problem within this class of problems.
\end{enumerate}
The pairing of a model with a particular data set is an \emph{model
instance} (sometimes abbreviated to \emph{instance}).

#2
Section~\ref{Model Instance Files} specifies how the model and data can be
structured within files in a model instance.
}

%-----------------------------------------------------------------------------%
\newcommand{\CommonCharacterSetAndComments}[1]{
    %-----------------------------------------------------------------------%
    \subsection{Character Set} 
    %-----------------------------------------------------------------------%
    The input files to #1 must be encoded as UTF-8.

    #1 is case sensitive.  There are no places where upper-case or
    lower-case letters must be used.  

    #1 has no layout restrictions, i.e.~any single piece of whitespace
    (containing spaces, tabs and newlines) is equivalent to any other.

    %-----------------------------------------------------------------------%
    \subsection{Comments} 
    %-----------------------------------------------------------------------%
    A \texttt{\%} indicates that the rest of the line is a comment.  #1
    also has block comments, using symbols \texttt{/*} and \texttt{*/} 
    to mark the beginning and end of a comment.
}

%-----------------------------------------------------------------------------%
\newcommand{\CommonEBNFBasics}[1]{
    \begin{itemize}
    \item Non-terminals are written between angle brackets, e.g.~\nt{item}.
    \item Terminals are written in fixed-width font.  They are usually
          underlined for emphasis, e.g.~\term{constraint},
          although this is not always done if the meaning is clear.
    \item Optional items are written in square brackets,
          e.g.~\maybe{\term{var}}.
    \item Sequences of zero or more items are written with parentheses and a
          star, e.g. \zeroOrMore{\term{,} \nt{ident}}.
    \item Sequences of one or more items are written with parentheses and a
          plus, e.g. \oneOrMore{\nt{msg}}.

% Having '...' mean two slightly different things for the two cases isn't
% nice, but I can't think of a better way to do it that preserves nice EBNF
% notation.
\ifthenelse{\equal{#1}{sep}}{
    \item Non-empty lists are written with an item, a separator
          terminal, and ``\ldots''.  For example, this:
          \begin{quote}
              \commas{\nt{expr}}
          \end{quote}
          is short for this:
          \begin{quote}
              \nt{expr} \zeroOrMore{\term{,} \nt{expr}}
          \end{quote}
}{
    \item Non-empty lists are written with an item, a separator/terminator
          terminal, and ``\ldots''.  For example, this:
          \begin{quote}
              \commas{\nt{expr}}
          \end{quote}
          is short for this:
          \begin{quote}
              \nt{expr} \zeroOrMore{\term{,} \nt{expr}} \maybe{\term{,}}
          \end{quote}
          The final terminal is always optional in non-empty lists.
}
    \item Regular expressions, written in fixed-width font, are used in some
          productions, e.g.~\regexp{[-+]?[0-9]+}.
    \end{itemize}
}

%-----------------------------------------------------------------------------%
\newcommand{\reservedKeywords}{
\texttt{ann}, 
\texttt{annotation}, 
\texttt{any}, 
\texttt{array}, 
\texttt{bool}, 
\texttt{case},
\texttt{constraint}, 
\texttt{diff},
\texttt{div},
\texttt{else},
\texttt{elseif}, 
\texttt{endif}, 
\texttt{enum}, 
\texttt{false}, 
\texttt{float},
\texttt{function},
\texttt{if},
\texttt{in},
\texttt{include},
\texttt{int},
\texttt{intersect},
\texttt{let},
\texttt{list},
\texttt{maximize},
\texttt{minimize},
\texttt{mod},
\texttt{not},
\texttt{of},
\texttt{op},
\texttt{output},
\texttt{par},
\texttt{predicate},
\texttt{record},
\texttt{satisfy},
\texttt{set},
\texttt{solve},
\texttt{string},
\texttt{subset},
\texttt{superset},
\texttt{symdiff},
\texttt{test},
\texttt{then},
\texttt{true},
\texttt{tuple},
\texttt{type},
\texttt{union},
\texttt{var},
\texttt{where},
\texttt{xor}.
}

%-----------------------------------------------------------------------------%
\newcommand{\CommonInstantiationTypeInstDescription}{
    Each type has one or more possible \emph{instantiations}.  The
    instantiation of a variable or value indicates if it is fixed to a known
    value or not.  A pairing of a type and instantiation is called a
    \emph{type-inst}.
}

%-----------------------------------------------------------------------------%
\newcommand{\CommonInstantiationsDescription}[1]{
    When a #1 model is evaluated, the value of each variable may initially
    be unknown.  As it runs, each variable's \emph{domain} (the set of
    values it may take) may be reduced, possibly to a single value.

    An \emph{instantiation} (sometimes abbreviated to \emph{inst}) describes
    how fixed or unfixed a variable is at instance-time.  At the most basic
    level, the instantiation system distinguishes between two kinds of
    variables:  
    \begin{enumerate}
    \item \emph{Parameters}, whose values are fixed at instance-time
          (usually written just as ``fixed'').
    \item \emph{Decision variables} (often abbreviated to \emph{variables}),
          whose values may be completely unfixed at instance-time, but may
          become fixed at run-time (indeed, the fixing of decision variables
          is the whole aim of constraint solving).
    \end{enumerate}
}

%-----------------------------------------------------------------------------%
\newcommand{\CommonTypeInstDescription}{
    Because each variable has both a type and an inst, they are often
    combined into a single \emph{type-inst}.  Type-insts are primarily what
    we deal with when writing models, rather than types.

    A variable's type-inst \emph{never changes}.  This means a decision
    variable whose value becomes fixed during model evaluation still has its
    original type-inst (e.g.~\texttt{var int}), because that was its
    type-inst at instance-time.

    Some type-insts can be automatically coerced to another type-inst.  For
    example, if a \texttt{par int} value is used in a context where a
    \texttt{var int} is expected, it is automatically coerced to a
    \texttt{var int}.  We write this \coerce{\texttt{par int}}{\texttt{var
    int}}.  Also, any type-inst can be considered coercible to itself. 
}

%-----------------------------------------------------------------------------%
\newcommand{\CommonIntegersOverview}{
    Integers represent integral numbers.  Integer representations are
    implementation-defined.  This means that the representable range of
    integers is implementation-defined.  However, an implementation should
    abort at run-time if an integer operation overflows.
}

%-----------------------------------------------------------------------------%
\newcommand{\CommonFloatsOverview}{
    Floats represent real numbers.  Float representations are
    implementation-defined.  This means that the representable range and
    precision of floats is implementation-defined.  However, an
    implementation should abort at run-time on exceptional float operations
    (e.g.~those that produce \texttt{NaN}s, if using IEEE754 floats).
}

%-----------------------------------------------------------------------------%
\newcommand{\CommonStringLiterals}{
    String literals are written as in C:
    \begin{productions}
        \RuleStringLiteral
    \end{productions}
    This includes C-style escape sequences, such as `\texttt{\backsl"}' for
    double quotes, `\texttt{\backsl\backsl}' for backslash, and
    `\texttt{\backsl{}n}' for newline.

    For example: \texttt{"Hello, world!\backsl{}n"}.

    String literals must fit on a single line.  
}

%-----------------------------------------------------------------------------%
\newcommand{\CommonOutputOnSuccessOrFailure}{
    The output is determined by concatenating the individual elements of the
    array.

    Each model can have at most one output item.  If a solution is found and
    an output item is present, it is used to determine the string to be
    printed.   If a solution is found and no output item is present, the
    implementation should print all the global variables and their values
    in a readable format.  If no solution is found, the implementation
    should print ``No solution found'';  it may also print some extra
    information about the cause of the failure, such as which constraints
    were violated.
}

%-----------------------------------------------------------------------------%
\newcommand{\ShowCondDescription}{
    Conditional to-string conversion.  If the first argument is not fixed,
    it aborts;  if it is fixed to \texttt{true}, the second argument is
    converted to a string;  if it is fixed to \texttt{false} the third
    argument is converted to a string.  The exact form of the resulting
    string is implementation-dependent, but same as that produced by
    \texttt{show}.
}

%-----------------------------------------------------------------------------%
\newcommand{\CommonSolveMinMaxExprTypeInst}{
    The expression in a minimize/maximize solve item must have type-inst
    \texttt{int}, \texttt{float}, \texttt{var int} or \texttt{var float}.
    The first two of these are not very useful as they mean that the model
    requires no optimisation.
}
