--- a/obisort.xml	Mon May 10 19:34:04 2021 +0000
+++ b/obisort.xml	Wed Mar 20 13:15:59 2024 +0000
@@ -1,62 +1,91 @@
-<tool id="obi_sort" name="obisort" version="@TOOL_VERSION@" profile="@PROFILE@">
-    <description>sorts sequence records according to the value of a given attribute</description>
-    <macros>
-        <import>macros.xml</import>
-    </macros>
-    <expand macro="requirements"/>
-    <expand macro="stdio"/>
-
-    <command><![CDATA[
-        @GUNZIP_INPUT@
-        obisort
-        --without-progress-bar
-        -k '$key'
-        ${reverse}
-        @INPUT_FORMAT@
-        @OUT_FORMAT@
-        input
-        @GZIP_OUTPUT@
-        > '$output'
-        @GENERATE_GALAXY_JSON@
-    ]]></command>
-    <inputs>
-        <param name="input" type="data" format="@INPUT_FORMATS@,txt,tabular" label="Input sequences file" />
-        <param name="key" type="text" label="key"/>
-        <param name="reverse" type="boolean" checked="false" truevalue="-r" falsevalue="" label="sorts in reverse order?" />
-        <expand macro="input_format_options_macro"/>
-        <expand macro="out_format_macro"/>
-    </inputs>
-    <outputs>
-        <data format="auto" name="output"/>
-    </outputs>
-    <tests>
-        <test>
-            <param name="input" value="output_obiclean_advanced.fasta" />
-            <param name="key" value="count"/>
-            <param name="reverse" value="False"/>
-            <param name="out_format" value="fasta"/>
-            <output name="output" file="output_obisort.fasta" ftype="fasta"/>
-        </test>
-        <test>
-            <param name="input" value="output_obiclean_advanced.fasta" />
-            <param name="key" value="count"/>
-            <param name="reverse" value="True"/>
-            <param name="out_format" value="fastq"/>
-            <output name="output" file="output_obisort.fastq" ftype="fastqsanger"/>
-        </test>
-    </tests>
-    <help><![CDATA[
-
-.. class:: infomark
-
-**What it does**
-
-obisort sorts sequence records according to the value of a given attribute, which can be either numeric or alphanumeric.
-
-@OBITOOLS_LINK@
-
-        ]]>
-
-    </help>
-    <expand macro="citation" />
-</tool>
+<tool id="obi_sort" name="obisort" version="@TOOL_VERSION@" profile="@PROFILE@">
+    <description>sorts sequence records according to the value of a given attribute</description>
+    <macros>
+        <import>macros.xml</import>
+    </macros>
+    <expand macro="bio_tools"/>
+    <expand macro="requirements"/>
+    <expand macro="stdio"/>
+
+    <command><![CDATA[
+        @GUNZIP_INPUT@
+        obisort
+        --without-progress-bar
+        #if $key:
+        -k '$key'
+        #end if
+        ${reverse}
+        @INPUT_FORMAT@
+        @OUT_FORMAT@
+        input
+        @GZIP_OUTPUT@
+        > '$output'
+        @GENERATE_GALAXY_JSON@
+    ]]></command>
+    <inputs>
+        <param name="input" type="data" format="@INPUT_FORMATS@,txt,tabular" label="Input sequences file"/>
+        <param
+            name="key"
+            type="text"
+            label="Key"
+            help="This key must be encoded in your FASTA/FASTQ headers as key=value. See help (below) for more information."
+            optional="false"/>
+        <param name="reverse" type="boolean" checked="false" truevalue="-r" falsevalue="" label="Sort in reverse order?" />
+        <expand macro="input_format_options_macro"/>
+        <expand macro="out_format_macro"/>
+    </inputs>
+    <outputs>
+        <data format="auto" name="output"/>
+    </outputs>
+    <tests>
+        <test expect_num_outputs="1">
+            <param name="input" value="output_obiclean_advanced.fasta" />
+            <param name="key" value="count"/>
+            <param name="reverse" value="False"/>
+            <param name="out_format" value="fasta"/>
+            <output name="output" file="output_obisort.fasta" ftype="fasta"/>
+        </test>
+        <test expect_num_outputs="1">
+            <param name="input" value="output_obiclean_advanced.fasta" />
+            <param name="key" value="count"/>
+            <param name="reverse" value="True"/>
+            <param name="out_format" value="fastq"/>
+            <output name="output" file="output_obisort.fastq" ftype="fastqsanger"/>
+        </test>
+    </tests>
+    <help><![CDATA[
+
+.. class:: infomark
+
+**What it does**
+
+obisort sorts sequence records according to the value of a given attribute, which can be either numeric or alphanumeric.
+
+@OBITOOLS_LINK@
+
+**Inputs:**
+
+For sorting by key, the input file must be in the
+`OBITools FASTA/FASTQ format <https://pythonhosted.org/OBITools/attributes.html>`_.
+If your file is an OBITools output, it should already be formatted correctly.
+
+For FASTA files, your headers should look like this::
+
+    >my_sequence taxid=3456; direct=True; sample=A354; this is my pretty sequence
+    ACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGT
+    GTGCTGACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTGTTT
+    AACGACGTTGCAGTACGTTGCAGT
+
+Where ``taxid``, ``direct``, and ``sample`` are keys that can be used for sorting.
+
+If your sequences don't have title, you can format the headers with a trailing semicolon like so::
+
+    >my_sequence key1=value1;
+
+For sorting OBITools output files, a list of OBITools sequence attributes are documented
+`here <https://pythonhosted.org/OBITools/attributes.html#names-reserved-for-attributes>`_.
+
+]]>
+    </help>
+    <expand macro="citation" />
+</tool>