@cindex @samp{@@} (response file prefix)
A response file contains names of images or other response filenames.
Introduce response file names with an at-character (@samp{@@}).

@cindex processing order
@cindex order, of processing
Enblend and Enfuse process the list @var{INPUT} strictly from left to
right, expanding response files in depth-first order.  (Multi-layer
files are processed from first layer to the last.) The following
examples only show Enblend, but Enfuse works exactly the same.

@table @asis
@dbtitle{Response File Examples}
@item Solely image filenames.
Example:
@example
enblend image-1.tif image-2.tif image-3.tif
@end example

The ultimate order in which the images are processed is:
@file{image-@/1.tif}, @file{image-@/2.tif}, @file{image-@/3.tif}.

@item Single response file.
Example:
@example
enblend @@list
@end example
where file@tie{}@file{list} contains
@example
img1.exr
img2.exr
img3.exr
img4.exr
@end example

Ultimate order: @file{img1.exr}, @file{img2.exr}, @file{img3.exr},
@file{img4.exr}.

@item Mixed literal names and response files.
Example:
@example
enblend @@master.list image-09.png image-10.png
@end example
where file@tie{}@file{master.list} comprises of
@example
image-01.png
@@first.list
image-04.png
@@second.list
image-08.png
@end example
@file{first.list} is
@example
image-02.png
image-03.png
@end example
and @file{second.list} contains
@example
image-05.png
image-06.png
image-07.png
@end example

Ultimate order: @file{image-@/01.png}, @file{image-@/02.png},
@file{image-@/03.png}, @file{image-@/04.png}, @file{image-@/05.png},
@file{image-@/06.png}, @file{image-@/07.png}, @file{image-@/08.png},
@file{image-@/09.png}, @file{image-@/10.png},
@end table


@c @menu
@c * Response File Format::        Definition of the files' format
@c * Syntactic Comments::          Control interpretation of response files
@c * Globbing Algorithms::         Various ways to glob filenames
@c @end menu

@c @node Response File Format
@subsection Response File Format
@cindex response file, format
@cindex format of response file

@cindex @samp{#} (response file comment)
@cindex response file, comment (@samp{#})
Response files contain one filename per line.  Blank lines or lines
beginning with a sharp sign (@samp{#}) are ignored; the latter can
serve as comments.  Filenames that begin with an at-character
(@samp{@@}) denote other response files.
@ref{Table:response-file-format} states a formal grammar of response
files in @uref{http://@/en.wikipedia.org/@/wiki/@/Ebnf,
@acronym{EBNF}}.

@float Table,Table:response-file-format
@multitable {@var{response-file}} {::=} {abcdefghijklmnopqrstuvwxyzabcdefghijklm}
@item @var{response-file}
@tab ::=
@tab @var{line}*
@item @var{line}
@tab ::=
@tab (@var{comment} | @var{file-spec}) [@samp{\r}] @samp{\n}
@item @var{comment}
@tab ::=
@tab @var{space}* @samp{#} @var{text}
@item @var{file-spec}
@tab ::=
@tab @var{space}* @samp{@@} @var{filename} @var{space}*
@item @var{space}
@tab ::=
@tab @samp{ } | @samp{\t}
@end multitable

@noindent
where @var{text} is an arbitrary string and @var{filename} is any
filename.

@caption{@acronym{EBNF} definition of the grammar of response files.}
@shortcaption{Grammar of response files}

@cindex response file, grammar
@cindex grammar, response file
@end float

In a response file relative filenames are used relative the response
file itself, not relative to the current-working directory of the
application.

@noindent
The above grammar might unpleasantly surprise the user in the
some ways.

@table @asis
@dbtitle{Response File Grammar}
@item Whitespace trimmed at both line ends
For convenience, whitespace at the beginning and at the end of each
line is ignored.  However, this implies that response files cannot
represent filenames that start or end with whitespace, as there is no
quoting syntax.  Filenames with embedded whitespace cause no problems,
though.

@item Only whole-line comments
Comments in response files always occupy a complete line.  There are
no ``line-ending comments''.  Thus, in
@example
# exposure series
img-0.33ev.tif # "middle" EV
img-1.33ev.tif
img+0.67ev.tif
@end example
only the first line contains a comment, whereas the second line
includes none.  Rather, it refers to a file called
@w{@samp{img-@/0.33ev.tif # "middle" EV}}.

@item Image filenames cannot start with @samp{@@}
An at-sign invariably introduces a response file, even if the
filename's extension hints towards an image.
@end table

@cindex response file, force recognition of
If Enblend or Enfuse do not recognize a response file, they will skip
the file and issue a warning.  To force a file being recognized as a
response file add one of the following syntactic comments to the
@emph{first} line of the file.

@example
@group
@scindex response-file
response-file: true
@scindex enblend-response-file
enblend-response-file: true
@scindex enfuse-response-file
enfuse-response-file: true
@end group
@end example

@noindent
Finally, here is an example of a valid response file.
@example
@group
# 4\pi panorama!

# These pictures were taken with the panorama head.
@@round-shots.list

# Freehand sky shot.
zenith.tif

# "Legs, will you go away?" images.
nadir-2.tif
nadir-5.tif
nadir.tif
@end group
@end example


@c @node Syntactic Comments
@subsection Syntactic Comments
@cindex response file, syntactic comment
@cindex syntactic comment, response file

Comments that follow the format described in
@ref{Table:response-file-syntactic-comment} are treated as
instructions how to interpret the rest of the response file.  A
syntactic comment is effective immediately and its effect persists to
the end of the response file, unless another syntactic comment undoes
it.

@float Table,Table:response-file-syntactic-comment
@multitable {@var{syntactic-comment}} {::=} {abcdefghijklmnopqrstuvwxyzabcdefghijklm}
@item @var{syntactic-comment}
@tab ::=
@tab @var{space}* @samp{#} @var{space}* @var{key} @var{space}* @samp{:} @var{space}* @var{value}
@item @var{key}
@tab ::=
@tab (@samp{A} .. @samp{Z} | @samp{a} .. @samp{z} | @samp{-})+
@end multitable

@noindent
where @var{value} is an arbitrary string.

@caption{@acronym{EBNF} definition of the grammar of syntactic
comments in response files.}
@shortcaption{Grammar of syntactic comments}

@cindex syntactic comment, grammar
@cindex grammar, syntactic comment
@end float

Unknown syntactic comments are silently ignored.


@c @node Globbing Algorithms
@subsection Globbing Algorithms
@cindex globbing algorithms
@cindex algorithms, globbing

The three equivalent syntactic keys

@itemize
@item
@scindex glob
@code{glob},
@item
@scindex globbing
@code{globbing}, or
@item
@scindex filename-globbing
@code{filename-globbing}
@end itemize

control the algorithm that Enblend or Enfuse use to glob filenames in
response files.

@cindex globbing algorithm @samp{literal}
@cindex globbing algorithm @samp{wildcard}
All versions of Enblend and Enfuse support at least two algorithms:
@code{literal}, which is the default, and @code{wildcard}.  See
@ref{Table:globbing-algorithms} for a list of all possible globbing
algorithms.  To find out about the algorithms in your version of
Enblend or Enfuse team up the options@tie{}@option{--version} and
@option{--verbose}.

@float Table,Table:globbing-algorithms
@table @code
@dbtitle{Globbing Algorithms}
@item literal
@cindex globbing algorithm @samp{literal}
Do not glob.  Interpret all filenames in response files as literals.
This is the default.

Please keep in mind that whitespace at both ends of a line in a
response file @emph{always} gets discarded.

@item wildcard
@cindex globbing algorithm @samp{wildcard}
@cindex glob(7)
Glob using the wildcard characters@tie{}@samp{?}, @samp{*}, @samp{[},
and @samp{]}.

The @acronym{W*N32} implementation only globs the filename part of a
path, whereas all other implementations perform wildcard expansion in
@emph{all} path components.  Also see
@uref{http://www.kernel.org/@/doc/@/man-pages/@/online/@/pages/@/man7/@/glob.7.html,
glob(7)}.

@item none
@cindex globbing algorithm @samp{none}
Alias for @code{literal}.

@item shell
@cindex globbing algorithm @samp{shell}
The @code{shell} globbing algorithm works as @code{literal} does.  In
addition, it interprets the wildcard characters@tie{}@samp{@{},
@samp{@}}, and @samp{~}.  This makes the expansion process behave more
like common @acronym{UN*X} shells.

@item sh
@cindex globbing algorithm @samp{sh}
Alias for @code{shell}.
@end table

@caption{Globbing algorithms for the use in response files}
@shortcaption{Globbing algorithms}

@cindex globbing algorithms
@cindex algorithms, globbing
@end float

Example:
@example
@group
# Horizontal panorama
# 15 images

# filename-globbing: wildcard

image_000[0-9].tif
image_001[0-4].tif
@end group
@end example


@c @node Default Layer Selection
@subsection Default Layer Selection
@cindex default layer selection
@cindex layer selection, default

The key @code{layer-selector}
@scindex layer-selector
provides the same functionality as does the command-line
option@tie{}@option{--layer-selector}, but on a per response-file
basis.  @xref{Common Options}.

This syntactic comment affects the layer selection of all images
listed after it including those in included response files until
another @code{layer-selector} overrides it.
