From 79a798676859e1d82dbd947a0fd767bba9711c2d Mon Sep 17 00:00:00 2001 From: Ben Soares Date: Tue, 16 May 2023 23:58:32 +0100 Subject: [PATCH] JAL-629 Finished documentation for new command lines. --- help/help/help.jhm | 4 + help/help/helpTOC.xml | 10 +- help/help/html/features/clarguments-advanced.html | 106 +++++++++++++---- help/help/html/features/clarguments-argfiles.html | 132 +++++++++++++++++++-- help/help/html/features/clarguments-basic.html | 24 ++-- help/help/html/features/clarguments-intro.html | 18 +-- help/help/html/features/clarguments.html | 14 +-- 7 files changed, 244 insertions(+), 64 deletions(-) diff --git a/help/help/help.jhm b/help/help/help.jhm index cd415ea..8e609a6 100755 --- a/help/help/help.jhm +++ b/help/help/help.jhm @@ -65,6 +65,10 @@ + + + + diff --git a/help/help/helpTOC.xml b/help/help/helpTOC.xml index 11e61be..1cdf4d3 100755 --- a/help/help/helpTOC.xml +++ b/help/help/helpTOC.xml @@ -169,11 +169,11 @@ - - - - - + + + + + diff --git a/help/help/html/features/clarguments-advanced.html b/help/help/html/features/clarguments-advanced.html index 2583b8d..db818d8 100644 --- a/help/help/html/features/clarguments-advanced.html +++ b/help/help/html/features/clarguments-advanced.html @@ -19,81 +19,95 @@ * along with Jalview. If not, see . * The Jalview Authors are detailed in the 'AUTHORS' file. --> -Jalview Command Line Arguments: advanced usage +Command Line: advanced usage -

Jalview Command Line Arguments: advanced usage

+

Command Line: advanced usage

- Jalview Command Line Arguments: summary + Command Line: summary
- Jalview Command Line Arguments: introduction + Command Line: introduction
- Jalview Command Line Arguments: basic usage + Command Line: basic usage
- Jalview Command Line Arguments: advanced usage + Command Line: advanced usage
- Jalview Command Line Arguments: argfiles + Command Line: argument files

Alignment linked IDs

- Jalview's alignment related arguments are linked together using a linked ID. In all of the basic usage examples this linked ID is assigned using a default formula of JALVIEW:n where n starts at 0 and increments every time there is an --opened file (or a first use of --append) or the --newargument is used. + Jalview's alignment related arguments are linked together using a linked ID. In all of the basic usage examples this linked ID is assigned using a default formula of JALVIEW:n where n starts at 0 and increments every time there is an --opened file (or a first use of --append) or the --new argument is used.

- When another alignment related argument is used, it is assigned the same linked ID. When the --all argument is used, following alignment related arguments are applied to all linked IDs (made so far). + When another alignment related argument is used (without a specified linked ID), it is assigned this default linked ID. When the --all argument is used, following alignment related arguments are applied to all of the linked IDs (made so far).

- You can assign your own linked IDs to alignments that are opened from the command-line. To do this put the linked ID in square brackets ('[', ']') immediately following the argument (i.e. before any space or equals sign) like this: + You can assign your own linked IDs to alignments that are opened from the command-line. To do this put the linked ID in square brackets ('[', ']') immediately following the argument (i.e. before any space or equals sign) like this: 

   jalview --open[myId1] file1.fa --open[myId2] file2.fa --open[myId3] file3.fa --colour[myId1] gecos-flower --colour[myId2] gecos-blossom --colour[myId3] zappo --image "*.png" --headless
+ +

+ As you can see, if you specify your own linked IDs, the arguments for one alignment do not need to be adjacent as they are when using the default assigned linked ID.

- As you can see the arguments for one alignment do not need to be adjacent as they are when using the default assigned linked ID. + A specified linked ID will also take precedence over a wildcard or --all set linked ID. e.g. + 

+  jalview --open[myID] examples/uniref50.fa --all --colour taylor --colour[myID] gecos-blossom
+
+ will open the alignment using the gecos-blossom colour scheme (thank goodness).

-

More substitutions

+

More substitutions ({n}, {++n}, [*])

- In the basic usage document we have a list of special strings that get replaced in output filename values with parts of input filename values. + In the basic usage document we have a list of special strings that get replaced in output filename values with parts of input filename values.

- There is also an incrementor integer value {n} that can be put into both linked IDs and filenames and works across different linked IDs. Whenever you use {n} in a linked ID or filename value it is replaced with the current value of n. The initial value is 0, and it can be incremented by using the argument --npp or --n++, or using a another substitution {++n} in either a linked ID or filename value which increments the value and is replaced with the new incremented value of n. + There is also an incrementor integer value {n} that can be put into both linked IDs and filenames and works across different linked IDs. Whenever you use {n} in a linked ID or filename value it is replaced with the current value of n. The initial value is 0, and it can be incremented by using the argument --npp or --n++, or using a another special substitution {++n} in either a linked ID or filename value which increments the value and is replaced with the new incremented value of n.

- In the same way that the --all argument enables (some) following arguments to apply to all opened alignments so far, the special linked ID {*} will also apply an individual argument to all opened linked IDs. + In the same way that the --all argument enables (some) following arguments to apply to all opened alignments so far, the special linked ID * will also apply an individual argument to all opened linked IDs (in fact when you use the --all argument it simply changes the default linked ID to *). 

-  jalview --open[myId1] fileA.fa --open[myId2] fileB.fa --open[myId3] fileC.fa --colour[{*}] taylor --all --image tmp/image-{++n}.png --headless
+  jalview --open[myId1] fileA.fa --open[myId2] fileB.fa --open[myId3] fileC.fa --colour[*] taylor --all --image tmp/image-{++n}.png --headless
The above will produce an image image-0.png for the alignment in fileA.fa, an image image-1.png for the alignment in fileB.fa, etc. + If you suddenly decide to colour the last alignment differently you could add to the command: + 
+  jalview --open[myId1] fileA.fa --open[myId2] fileB.fa --open[myId3] fileC.fa --colour[*] taylor --all --image tmp/image-{++n}.png --headless --colour[myId3] gecos-blossom
+
+ because all of the command line arguments are read and sorted into their linked IDs before starting to be processed, and the [myId3] specified linked ID takes precedence over the [*] wildcard linked ID. +

-

Equals separator and file globs

+

Equals separator and Java file globs

- When a Jalview command-line argument requires one (or more) values, you can use the usual space separation, which allows the shell to expand any filename "globs" (or wildcards representing multiple files). To Jalview this appears like a list of filenames supplied to the argument. + When a Command-line argument requires one (or more) values, you can use the usual space separation, which allows the shell to expand any file "globs" (that is, filenames with wildcard characters allowing it to represent multiple files). The shell "expands" this file glob and to Jalview it appears like a list of filenames supplied to the argument.

- There is a limitation to shell expansion of file globs, as the length of a single command is limited (to different amounts depending on your shell and its configuration). + There is a limitation to shell expansion of file globs, as the length of a single command, or number of files the shell is willing to expand a file glob to, is limited (to different amounts depending on your shell and its configuration).

@@ -108,15 +122,61 @@

- Another benefit is that the input filename + A bigger benefit is that the input filename is not expanded by the shell but can instead be expanded by Jalview. There is no limit to the number of files that this kind of file glob can match since it is expanded by Jalview, not the shell. +

+ +

+ Jalview uses the Java PathMatcher "glob" scheme to match filenames, which is quite similar, though in some ways more powerful, to most shell glob rules. The usual '*' and '?' characters act the same, but other combinations can be used too. For the full rules see java.nio.file.PathMatcher.getPathMatcher javadocs at https://devdocs.io/openjdk~11/java.base/java/nio/file/filesystem#getPathMatcher(java.lang.String). +

+ +

+ One such PathMatcher addition to shell file globs is the use of ** to match any number of directories and sub-directories (matching across file separator). So to convert every Fasta file under the current working directory to BLC format you can do: + 

+  jalview --open=./**/*.fa --output=*.blc --close --headless
+
+ or to find every Stockholm and Pfam file under /tmp and convert to Fasta and save in your own folder, do + 
+  jalview --open=/tmp/**/*.{stk,pfam} --all --output=~/rescued/{basenamedir}.fa --close --headless
+
+

+ +

Sub-value modifiers

+

+ Sub-value modifiers are given in square brackets ('[', ']') immediately before the value (i.e. after any space or equals sign, and with no space between it and the value) like this: + 

+  jalview --open=examples/uniref50.fa --image=[scale=1.414]picture.png
+
+

+ +

+ Some arguments (such as --scale=n) are used to modify the behaviour of other "primary" arguments (such as --image=filename). These arguments can alternatively be specifed as sub-value modifiers of the values given to the primary argument. If specified as a sub-value modifier, this modifier takes precedence over any following linked argument if given. e.g + 

+  jalview --open=[colour=zappo]examples/*.fa
+
+ Notice also that if a sub-value modifier is used for a value that is expanded by the application (i.e. using an equals sign ('=') to separate argument and value) then that modifier is applied to all of the values. +

+ +

+ For shell expanded globs this is more problematic since the presence of a sub-value modifier will almost certainly prevent the shell from recognising the file glob, so + 

+  jalview --open [colour=zappo]examples/*.fa
+
+ will NOT work the same as above. If you need to use sub-value modifiers on a file glob you should use an equals sign ('=') to separate it from the argument. +

+ +

+ You can specify multiple sub-value modifiers separating them with a comma (','). If you wish to specify a "boolean" argument, such as --wrap or --nowrap then simply use the argument name without a value, like this: + 

+  jalview --open=[colour=gecos-flower,wrap,noannotations,features=examples/plantfdx.features]examples/plantfdx.fa
+

- Continue to Jalview Command Line Arguments: argfiles. + Continue to Command Line: argument files.
- Return to Jalview Command Line Arguments: summary. + Return to Command Line: summary. diff --git a/help/help/html/features/clarguments-argfiles.html b/help/help/html/features/clarguments-argfiles.html index a527c21..f4741ee 100644 --- a/help/help/html/features/clarguments-argfiles.html +++ b/help/help/html/features/clarguments-argfiles.html @@ -19,33 +19,149 @@ * along with Jalview. If not, see . * The Jalview Authors are detailed in the 'AUTHORS' file. --> -Jalview Command Line Arguments: argfiles +Command Line: argument files -

Jalview Command Line Arguments: argfiles

+

Command Line: argument files

- Jalview Command Line Arguments: summary + Command Line: summary
- Jalview Command Line Arguments: introduction + Command Line: introduction
- Jalview Command Line Arguments: basic usage + Command Line: basic usage
- Jalview Command Line Arguments: advanced usage + Command Line: advanced usage
- Jalview Command Line Arguments: argfiles + Command Line: argument files

+ +

Argument files

+

+ If you want to save a set of arguments to reuse, you can save them in a text file, say argfile.txt, and read them into Jalview with + 

+  jalview --argfile=argfile.txt
+
+

+ +

+ 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 ('='). +
+ 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. +
+ You can add comments to a line by starting the line with an octothorpe (hash, pound-sign '#'). +
+ e.g. + + + + + + + +
+ File argfile.txt +
+ 
+--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
+
+

+

+ Because --argfiles takes a filename argument, and multiple --argfiles can be read on the command line, you can also use file globs to specify multiple --argfile 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. + 

+  jalview --argfile=*/argfile.txt --headless
+
+

+ +

+ You can even read argument files from within argument files, e.g. + 

+  jalview --argfile=argfile*.txt --headless
+
+ + + + + + + +
File argfile1.txt
+--open=file1.fa
+--argfile=myfavouriteformattingargfile.txt
+--argfile=mysecondfavouriteimageargfile.txt
File myfavouriteformattingargfile.txt
+--wrap
+--showannotations
+--annotations={dirname}/{basename}.annots
File mysecondfavouriteimageargfile.txt
+--image=images/{basename}.png
+--width=1920
+--height=1080
+

+ +

+ If a "loop" of argument files is detected then Jalview will refuse to play (which is a Good Thing). +

+

Only argument files

+ +

+ When you use an --argfile argument, all other non-initialising arguments on the command line will be ignored. Only the initialising arguments and any and all --argfiles arguments on the command line will be used. You can also set initialising arguments in argument files. +

+ + +

Even more substitutions

+ +

+ When adding values that can use substitutions within argument files, there are two additional substitutions that are made: +
+ {argfilebasename} - replaced with the base of the filename of the argument file (i.e. without directory path or file extension). +
+ {argfiledirname} - replaced with the path to the filename of the argument file. +

+ +

+ Another amusing substitution you can make in argument files is the {n} substitution, combined with an -npp 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. + + + + +
File alignment.argfile
+--open={argfilebasename}-{n}.fa
+--wrap
+--output={basename}.stk
+--close
+--npp
+ 

+  jalview --argfile alignment.argfile --argfile alignment.argfile --headless
+
+ would be processed like + 
+  jalview --open=alignment-0.fa --wrap --output=alignment-0.stk --close --open=alignment-1.fa --wrap --output=alignment-1.stk --close --headless
+
+

+
- Return to Jalview Command Line Arguments: summary. + Return to Command Line: summary. diff --git a/help/help/html/features/clarguments-basic.html b/help/help/html/features/clarguments-basic.html index b557f4f..edee480 100644 --- a/help/help/html/features/clarguments-basic.html +++ b/help/help/html/features/clarguments-basic.html @@ -19,21 +19,21 @@ * along with Jalview. If not, see . * The Jalview Authors are detailed in the 'AUTHORS' file. --> -Jalview Command Line Arguments: basic usage +Command Line: basic usage -

Jalview Command Line Arguments: basic usage

+

Command Line: basic usage

- Jalview Command Line Arguments: summary + Command Line: summary
- Jalview Command Line Arguments: introduction + Command Line: introduction
- Jalview Command Line Arguments: basic usage + Command Line: basic usage
- Jalview Command Line Arguments: advanced usage + Command Line: advanced usage
- Jalview Command Line Arguments: argfiles + Command Line: argument files

@@ -557,7 +557,7 @@

--all / -noall

- When using the --all argument, following arguments will apply to all of the previously opened alignment windows. You can turn this behaviour off for following arguments using the --noall argument. The arguments that can apply to all previously opened alignments are: + When using the --all argument, following arguments will apply to all of the previously opened alignment windows. You can turn this behaviour off again for following arguments using the --noall argument. The arguments that can apply to all previously opened alignments are:
--colour
@@ -627,7 +627,7 @@

The all output wildcard: --output "*.ext", --image "*.ext"

- Purely as an intuitive syntactic sweetener, you can use the --output wildcard * at the beginning of the output filename as shorthand for --all --output {dirname}/{basename} followed by whatever you put after the *. For example, to achieve the same as the thumbnails example above, you could use + Purely as an intuitive syntactic sweetener, you can use the --output wildcard * at the beginning of the output filename as shorthand for --all --output {dirname}/{basename} followed by whatever you put after the '*'. For example, to achieve the same as the thumbnails example above, you could use 

   jalview --open */*.fa --image "*.png" --colour gecos-flower --width 256 --height 256 --close --headless
@@ -642,7 +642,7 @@

- Important! Please note that using a bareword *.ext (i.e. without an escape or quotation marks) in a shell command line will potentially be expanded by the shell to a list of all the files in the current directory ending with .ext before this value is passed to Jalview. This will result in the first of these files being overwritten (multiple times)! If you shell-escape the * (usually with a backslash '\') or enclose the value in quotation marks ('"*.ext"') then the shell will not expand the wildcard. + Important! Please note that using a bareword *.ext (i.e. without an escape or quotation marks) in a shell command line will potentially be expanded by the shell to a list of all the files in the current directory ending with .ext before this value is passed to Jalview. This will result in the first of these files being overwritten (multiple times)! If you shell-escape the * (usually with a backslash '\') or enclose the value in quotation marks ("*.ext" - that's including the quotation marks) then the shell will not expand the wildcard.

@@ -653,9 +653,9 @@

- Continue to Jalview Command Line Arguments: advanced usage. + Continue to Command Line: advanced usage.
- Return to Jalview Command Line Arguments: summary. + Return to Command Line: summary. diff --git a/help/help/html/features/clarguments-intro.html b/help/help/html/features/clarguments-intro.html index c3cc918..6fddf0c 100644 --- a/help/help/html/features/clarguments-intro.html +++ b/help/help/html/features/clarguments-intro.html @@ -19,21 +19,21 @@ * along with Jalview. If not, see . * The Jalview Authors are detailed in the 'AUTHORS' file. --> -Jalview Command Line Arguments: introduction +Command Line: introduction -

Jalview Command Line Arguments: introduction

+

Command Line: introduction

- Jalview Command Line Arguments: summary + Command Line: summary
- Jalview Command Line Arguments: introduction + Command Line: introduction
- Jalview Command Line Arguments: basic usage + Command Line: basic usage
- Jalview Command Line Arguments: advanced usage + Command Line: advanced usage
- Jalview Command Line Arguments: argfiles + Command Line: argument files

@@ -79,9 +79,9 @@

- Continue to Jalview Command Line Arguments: basic usage. + Continue to Command Line: basic usage.
- Return to Jalview Command Line Arguments: summary. + Return to Command Line: summary. diff --git a/help/help/html/features/clarguments.html b/help/help/html/features/clarguments.html index 20c8619..437392f 100644 --- a/help/help/html/features/clarguments.html +++ b/help/help/html/features/clarguments.html @@ -9,21 +9,21 @@ * along with Jalview. If not, see . * The Jalview Authors are detailed in the 'AUTHORS' file. --> -Jalview Command Line Arguments: summary +Command Line: summary -

Jalview Command Line Arguments: summary

+

Command Line: summary

- Jalview Command Line Arguments: summary + Command Line: summary
- Jalview Command Line Arguments: introduction + Command Line: introduction
- Jalview Command Line Arguments: basic usage + Command Line: basic usage
- Jalview Command Line Arguments: advanced usage + Command Line: advanced usage
- Jalview Command Line Arguments: argfiles + Command Line: argument files

-- 1.7.10.2