From 8e4d0d9f722a85541ae59b84cf7e2587f19b971b Mon Sep 17 00:00:00 2001
From: Richard Harris <richard.harris@nanoporetech.com>
Date: Tue, 7 Nov 2023 12:56:59 +0000
Subject: [PATCH] added warning about positional arguments and --columns

---
 CHANGELOG.md          |  1 +
 docs/docs/tools.rst   | 14 +++++++++++++-
 python/pod5/README.md | 11 +++++++++++
 3 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index edadf71..d5256dd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Transfers dataframes used in subsetting / filter use categorical fields to reduce memory consumption
 - Polars version increased to `~=0.19`
+- Documentation regarding positional arguments
 - Renamed deprecated `polars.groupby` to `polars.group_by`
 
 ### Fixed
diff --git a/docs/docs/tools.rst b/docs/docs/tools.rst
index 50c5be7..65c5a3c 100644
--- a/docs/docs/tools.rst
+++ b/docs/docs/tools.rst
@@ -239,7 +239,7 @@ then ``pod5 filter`` might be a more appropriate tool as the only input is a lis
     $ pod5 subset example_1.pod5 --csv mapping.csv
 
     # Subset input(s) using a dynamic mapping created at runtime
-    $ pod5 subset example_1.pod5 --table table.txt --columns barcode
+    $ pod5 subset example_1.pod5 --columns barcode --table table.txt
 
 .. important::
 
@@ -248,6 +248,18 @@ then ``pod5 filter`` might be a more appropriate tool as the only input is a lis
     will be raised unless the ``--duplicate-ok`` argument is set. If ``--duplicate-ok`` is
     set then both reads will be written to the output, although this is not recommended.
 
+.. warning::
+
+    The ``--columns`` argument will greedily consume values and as such, care should be taken
+    with the placement of any positional arguments. The following line will result in an error
+    as the input pod5 file is consumed by ``--columns`` resulting in no input file being set.
+
+    .. code-block:: console
+
+        # Invalid placement of positional argument example.pod5
+        $ pod5 subset --table table.txt --columns barcode example.pod5
+
+
 Creating a Subset Mapping
 ------------------------------
 
diff --git a/python/pod5/README.md b/python/pod5/README.md
index 7f221a7..aec5c88 100644
--- a/python/pod5/README.md
+++ b/python/pod5/README.md
@@ -340,6 +340,17 @@ then ``pod5 filter`` might be a more appropriate tool as the only input is a lis
 > will be raised unless the ``--duplicate-ok`` argument is set. If ``--duplicate-ok`` is
 > set then both reads will be written to the output, although this is not recommended.
 
+#### Note on positional arguments
+
+> The ``--columns`` argument will greedily consume values and as such, care should be taken
+> with the placement of any positional arguments. The following line will result in an error
+> as the input pod5 file is consumed by ``--columns`` resulting in no input file being set.
+
+```bash
+# Invalid placement of positional argument example.pod5
+$ pod5 subset --table table.txt --columns barcode example.pod5
+```
+
 #### Creating a Subset Mapping
 
 ##### Target Mapping (.csv)