Structure the usage section.
a simple pattern language as a filter, but we may in the future extend it to be
similar to graphy. The initial implementation also ignores reification.
-`kgtk filter` reads a single input file. It will write one or more output files and/or a reject file.
-When there are multiple output files, each output file must have its own filter.
-Output files and filters are paired by order. We recommend listing each filter
-and output file as a pair on the command line, as shown in one of the examples, below.
-Input edges that do not match any filter may be written to a reject file
-(`--reject-file REJECT_FILE).
-
-When there are multiple output files, `--first-match-only` determines whether
-input edges are copied to the first matching output file (when `True`) or to
-all matching output files (when `False`, the default). When `True`, it can also trigger
-the use of an optimized code path, which may produce substantial savings when the
-total number of alternatives is large.
+### Filters and Patterns
Filters are specified using patterns of the form
@@ -35,6 +24,8 @@ nonempty pattern matches. The `--invert` option may be used to invert the
sense of the filter, causing matching input edges to be written to the
reject file, and non-matching edges to be written to the output file.
+### Regular Expression Patterns
+
When using regular expressions as patterns, `--match-type MATCH_TYPE` determines the type of
regular expression match that takes place.
@@ -44,6 +35,23 @@ fullmatch | The full field must match the regular expression. It is not necess
match | The regular expression must match the beginning of the field. It is not necessary for it to match the entire field. It is not necessary to start the regular expression with `^`.
search | The regular expression must match somewhere in the field.
+### Multiple Filters
+
+`kgtk filter` reads a single input file. It will write one or more output files and/or a reject file.
+When there are multiple output files, each output file must have its own filter.
+Output files and filters are paired by order. We recommend listing each filter
+and output file as a pair on the command line, as shown in one of the examples, below.
+Input edges that do not match any filter may be written to a reject file
+(`--reject-file REJECT_FILE).
+
+When there are multiple output files, `--first-match-only` determines whether
+input edges are copied to the first matching output file (when `True`) or to
+all matching output files (when `False`, the default). When `True`, it can also trigger
+the use of an optimized code path, which may produce substantial savings when the
+total number of alternatives is large.
+
+### Caveats
+
> NOTE: At the present time, semicolon (`;`) is used to separate the patterns of a filter and cannot appear within a pattern.
> NOTE: At the present time, comma (`,`) is used to separate alternatives in a non-regex pattern and cannot appear within a non-regex pattern.
