Document jCal conversion workflow

docs/examples.md

@@ -234,3 +234,43 @@ cat calendar1.ics calendar2.ics | ics-query at 2024-08 - -
 ```shell
 wget -qO- 'https://example.com/calendar.ics' | ics-query at 2024-08 - -
 ```
+
+## Working with jCal
+
+`ics-query` reads and writes iCalendar data in the RFC 5545 `.ics` format.
+If your workflow uses jCal JSON, convert between `.ics` and jCal with
+[`ical2jcal`](https://pypi.org/project/ical2jcal/). jCal is the JSON
+representation of iCalendar defined by
+[RFC 7265](https://www.rfc-editor.org/rfc/rfc7265).
+
+Install the converter:
+
+```shell
+python -m pip install ical2jcal
+```
+
+Convert an `.ics` file to jCal:
+
+```shell
+ical2jcal calendar.ics calendar.jcal
+```
+
+Convert jCal back to `.ics` before querying it:
+
+```shell
+jcal2ical calendar.jcal calendar.ics
+ics-query at 2024-08 calendar.ics -
+```
+
+You can also pipe the conversion into `ics-query`:
+
+```shell
+jcal2ical calendar.jcal - | ics-query between 2024-08-01 +7d - -
+```
+
+After querying, convert valid calendar output back to jCal:
+
+```shell
+ics-query at --as-calendar 2024-08 calendar.ics result.ics
+ical2jcal result.ics result.jcal
+```

docs/overview.md

@@ -39,6 +39,7 @@ Start is inclusive. End is exclusive.
 
 - [icalendar-events-cli](https://github.com/waldbaer/icalendar-events-cli#readme) — another command line implementation of `recurring-ical-events`
 - [icalBuddy](https://hasseg.org/icalBuddy/)
+- [ical2jcal](https://pypi.org/project/ical2jcal/) — convert between iCalendar `.ics` files and RFC 7265 jCal JSON
 - [Blog Post](https://opencollective.com/open-web-calendar/updates/calendar-calculation-on-the-command-line-ics-query)
 - [#icsquery on mastodon](https://toot.wales/tags/icsquery)
 - [Homebrew tap for ics-query](https://github.com/niccokunzmann/homebrew-tap)

docs/reference.md

@@ -18,6 +18,20 @@ These options apply to all commands.
 | `--available-timezones` | List all available timezone names and exit. |
 | `--license` | Show the license and exit. |
 
+## jCal conversion
+
+`ics-query` accepts RFC 5545 iCalendar input. To use RFC 7265 jCal JSON,
+convert the file with [`ical2jcal`](https://pypi.org/project/ical2jcal/)
+before or after running `ics-query`.
+
+```shell
+ical2jcal calendar.ics calendar.jcal
+jcal2ical calendar.jcal calendar.ics
+```
+
+See the [ical2jcal documentation](https://pycalendar.github.io/ical2jcal/)
+for the full command reference.
+
 ## ics-query at
 
 ```

ics_query/cli.py

@@ -421,6 +421,17 @@ def cli():
     (4) Do not mix `-c VEVENT` and others with `-c VALARM` or you might not know if the
     alarm or the component is inside the time span.
 
+    \b
+    jCal
+    ----
+
+    ics-query reads and writes RFC 5545 iCalendar data. To use RFC 7265 jCal JSON,
+    convert files with the ical2jcal package:
+
+    \b
+        https://pypi.org/project/ical2jcal/
+        https://pycalendar.github.io/ical2jcal/
+
     """  # noqa: D301