* along with Jalview. If not, see <http://www.gnu.org/licenses/>.
* The Jalview Authors are detailed in the 'AUTHORS' file.
-->
-<title>Jalview Command Line Arguments: argfiles</title>
+<title>Command Line: argument files</title>
<body>
- <h1>Jalview Command Line Arguments: argfiles</h1>
+ <h1>Command Line: argument files</h1>
<p>
- <a href="clarguments.html">Jalview Command Line Arguments: summary</a>
+ <a href="clarguments.html">Command Line: summary</a>
<br/>
- <a href="clarguments-intro.html">Jalview Command Line Arguments: introduction</a>
+ <a href="clarguments-intro.html">Command Line: introduction</a>
<br/>
- <a href="clarguments-basic.html">Jalview Command Line Arguments: basic usage</a>
+ <a href="clarguments-basic.html">Command Line: basic usage</a>
<br/>
- <a href="clarguments-advanced.html">Jalview Command Line Arguments: advanced usage</a>
+ <a href="clarguments-advanced.html">Command Line: advanced usage</a>
<br/>
- Jalview Command Line Arguments: argfiles
+ Command Line: argument files
</p>
<hr/>
+ <ul>
+ <li><a href="#argumentfiles">Argument files</a></li>
+ <li><a href="#onlyargumentfiles">Only argument files</a></li>
+ <li><a href="#evenmoresubstitutions">Even more substitutions</a></li>
+ </ul>
+ <h2><a name="argumentfiles"></a>Argument files</h2>
+ <p>
+ If you want to save a set of arguments to reuse, you can save them in a text file, say <code>argfile.txt</code>, and read them into Jalview with
+ <pre>
+ jalview --argfile=argfile.txt
+ </pre>
+ </p>
+
+ <p>
+ The argument file has one argument and value per line, still using the double-dash ('--') before the argument name, and separating the argument and value with an equals sign ('=').
+ <br/>
+ Because the argument file is read by the application and not read by the shell, you do not need to escape any values -- all spaces will be read as part of the value until the end of the line.
+ <br/>
+ You can add comments to a line by starting the line with an octothorpe (hash, pound-sign '#').
+ <br/>
+ e.g.
+ <table border="1">
+ <tr>
+ <td>
+ File <code>argfile.txt</code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <pre>
+--nonews
+--nosplash
+--open=[nowrap,colour=gecos-flower,showannotations]examples/plantfdx.fa
+--features=examples/plantfdx.features
+--annotations=examples/plantfdx.annotations
+--image=images/alignment.png
+--scale=2.5
+#--scale=10
+# let's see what's happening
+#--headless</pre>
+ </td>
+ </tr>
+ </table>
+ </p>
+ <p>
+ Because <code>--argfiles</code> takes a filename argument, and multiple <code>--argfiles</code> can be read on the command line, you can also use file globs to specify multiple <code>--argfile</code> values. If you produce an argument file for each set of alignment files that you wish to associate then you can act on all of them with, e.g.
+ <pre>
+ jalview --argfile=*/argfile.txt --headless
+ </pre>
+ </p>
+
+ <p>
+ You can even read argument files from within argument files, e.g.
+ <pre>
+ jalview --argfile=argfile*.txt --headless
+ </pre>
+ <table border="1">
+ <tr><td>File <code>argfile1.txt</code></td></tr>
+ <tr><td><pre>
+--open=file1.fa
+--argfile=myfavouriteformattingargfile.txt
+--argfile=mysecondfavouriteimageargfile.txt</pre></td></tr>
+ <tr><td>File <code>myfavouriteformattingargfile.txt</code></td></tr>
+ <tr><td><pre>
+--wrap
+--showannotations
+--annotations={dirname}/{basename}.annots</pre></td></tr>
+ <tr><td>File <code>mysecondfavouriteimageargfile.txt</code></td></tr>
+ <tr><td><pre>
+--image=images/{basename}.png
+--width=1920
+--height=1080</pre></td></tr>
+ </table>
+ </p>
+
+ <p>
+ If a "loop" of argument files is detected then Jalview will refuse to play (which is a Good Thing).
+ </p>
+ <h2><a name="onlyargumentfiles"></a>Only argument files</h2>
+
+ <p>
+ When you use an <code>--argfile</code> argument, all other non-initialising arguments on the command line <em>will be ignored</em>. Only the initialising arguments and any and all <code>--argfiles</code> arguments on the command line will be used. You can also set initialising arguments in argument files.
+ </p>
+
+
+ <h2><a name="evenmoresubstitutions"></a>Even more substitutions</h2>
+
+ <p>
+ When adding values that can use substitutions within argument files, there are two additional substitutions that are made:
+ <br/>
+ <code>{argfilebasename}</code> - replaced with the base of the filename of the argument file (i.e. without directory path or file extension).
+ <br/>
+ <code>{argfiledirname}</code> - replaced with the path to the filename of the argument file.
+ </p>
+
+ <p>
+ Another amusing substitution you can make in argument files is the <code>{n}</code> substitution, combined with an <code>-npp</code> increment at the start (or end) of the argument file, which gives the potential of having multiple argument files with the exact same content, or even re-using the same argument file multiple times. e.g.
+
+ <table border="1">
+ <tr><td>File <code>alignment.argfile</code></td></tr>
+ <tr><td><pre>
+--open={argfilebasename}-{n}.fa
+--wrap
+--output={basename}.stk
+--close
+--npp</pre></td></tr>
+ </table>
+ <pre>
+ jalview --argfile alignment.argfile --argfile alignment.argfile --headless
+ </pre>
+ would be processed like
+ <pre>
+ jalview --open=alignment-0.fa --wrap --output=alignment-0.stk --close --open=alignment-1.fa --wrap --output=alignment-1.stk --close --headless
+ </pre>
+ </p>
+
<hr/>
- Return to <a href="clarguments.html">Jalview Command Line Arguments: summary</a>.
+ Return to <a href="clarguments.html">Command Line: summary</a>.
</body>
git://source.jalview.org / jalview.git / blobdiff