search

insanum / gcalcli

Google Calendar Command Line Interface
MIT License
3.3k stars 311 forks source link

Docs/examples for agendaupdate to make it more discoverable #776

Open dbarnett opened 1 day ago

dbarnett commented 1 day ago

The agendaupdate command could use more help description and pointers to some examples of how to use it, so it's more discoverable to someone looking to solve the problem it's designed to solve.

Currently none of the help seems to mention that you pair it with agenda --tsv to get a TSV file in the right format to use as input for agendaupdate, and the help on the command is in general pretty terse:

$ gcalcli agendaupdate -h
usage: gcalcli agendaupdate [-h] [--calendar CALENDAR] [file]

Update calendar from agenda TSV file.

positional arguments:
  file

options:
  -h, --help           show this help message and exit
  --calendar CALENDAR  Which calendar to use, in the format "CalendarName" or
                       "CalendarName#color", where the #color suffix is the name of a
                       valid ANSI color (such as "brightblue").

Could use an end-to-end example of how to use it somewhere, maybe in README.md and linked from the --help or something.

dbarnett commented 1 day ago

I actually didn't realize it existed or understand what it was used for before digging through the code and the PR adding it.

FYI I'm not sure all the enhancements we talked about on the original issue will all fit logically under the same agendaupdate command, but OTOH I'll want to be careful about splitting out a bunch of command names for related functionality and am considering tweaking the command naming to make it more self-explanatory and make gcalcli --help more conveniently browseable.