Usage documentation needs more `list` examples

[amandabee]

I read through the usage documentation for khal list and was slightly stumped / frustrated and left to really puzzle it out for myself. I would have found a few examples helpful.

Something like this:

khal list -d example will display events in list form from every calendar except "example." khal list -a example today 30d will show a full month of entries from the "example" calendar.

I actually tried all of these, none of which successfully showed me 30 days worth of events, before I finally gave up and went to irc to ask for help:

  khal list -a example 30 
  khal list -a example 30d 
  khal list -a example DELTA 30d
  khal list -a example DELTA 30days
  khal list -a example DELTA 30 days
  khal list -a example 30 days
  khal list -a example "30 days"

(What I wanted was khal list -a example today 30d)

[amandabee]

Note: if anyone wants to throw me a few more examples of ways you actually use khal list I'm super happy to flesh those out in comments and create a pull request to add a few examples to the documentation.

[untitaker]

I wonder how/if the documentation given by khal list --help could be clearer. At least the argument order seems clear to me through the first output line. Perhaps we can add examples there?

[amandabee]

Examples would definitely help, but also, the documentation in the manual didn't clue me into the fact that khal list --help was an option.

On May 5, 2018 9:08:36 AM PDT, Markus Unterwaditzer [email protected] wrote:

I wonder how/if the documentation given by khal list --help could be clearer. At least the argument order seems clear to me through the first output line. Perhaps we can add examples there?

-- You are receiving this because you authored the thread. Reply to this email directly or view it on GitHub: https://github.com/pimutils/khal/issues/776#issuecomment-386816052

-- Sent from my Android device with K-9 Mail. Please excuse my brevity.

[lsrdg]

Any news on this issue? I have read twice the documentation and the manual (just to be sure), and still unsure how to get khal list to show events for December and/or January... In ikhal I get a list of days on the right... where only 2 of them actually have events and I see no reason to have such a pulluted list:

   Mo Tu We Th Fr Sa Su   Today (Friday, 11/29/2019)
    18 19 20 21 22 23 24     Kuracisto
Dec  25 26 27 28 29 30  1
     2  3  4  5  6  7  8   Tomorrow (Saturday, 11/30/2019)
     9 10 11 12 13 14 15   Sunday, 12/01/2019 (2 days from now)
    16 17 18 19 20 21 22   Monday, 12/02/2019 (3 days from now)
    23 24 25 26 27 28 29    13:00-14:00 Alia kuracistvizito.
Jan  30 31  1  2  3  4  5
     6  7  8  9 10 11 12   Tuesday, 12/03/2019 (4 days from now)
    13 14 15 16 17 18 19   Wednesday, 12/04/2019 (5 days from now)

This issue is not related to ikhal, but still.. it took me many hours to find out that I wanted ikhal to look like khal calendar (the list clean list on the right pane), but in my head this functionality would be achieved by khal list ('cause I don't need it to be interactive), but khal list is not intuitive since it doesn't 'list' and it has a default that I haven't found a way to change it yet.

Don't take me wrong, Khal is a great software and as soon as I learn how to interpret the manual I will be glad to contribute with PR specially on the documentation side. Let me know how I can help, since I've just started using it a couple of weeks ago, the docs are being literally read. (:

[d7415]

still unsure how to get khal list to show events for December and/or January...

khal list 2019-12-01 31d should work - starts on 1st Dec for 31d

but khal list is not intuitive since it doesn't 'list' and it has a default that I haven't found a way to change it yet.

'list' is exactly what it does...

[lsrdg]

khal list 2019-12-01 31d should work - starts on 1st Dec for 31d

Thanks, @d7415 , it works indeed.

'list' is exactly what it does...

Indeed, however:

$ khal list --help Usage: khal list [OPTIONS] [DATETIME [DATETIME | RANGE]]

List all events between a start (default: today) and (optional) end datetime.

Since the start has a default, my first try was: $ khal list 1y, followed by 1d and 1w. That's my fault. But your example has made Khal totally usable for me. There are no bugs, only features, and that's why examples can be so useful. Thanks again, @d7415 .

[d7415]

Ah, I see. From the brackets, the range requires a start to be set, so that if you set an end time it can tell the difference between the start and end. I suppose this isn't necessarily required for a range, but that could lead to more confusion down the line.

FWIW, RANGE has a configuration option timedelta you can use to set a default (it seems to be using mine, anyway).

Glad I could help :)

[lsrdg]

From the brackets, the range requires a start to be set, so that if you set an end time it can tell the difference between the start and end. I suppose this isn't necessarily required for a range, but that could lead to more confusion down the line.

Exactly.

FWIW, RANGE has a configuration option timedelta you can use to set a default (it seems to be using mine, anyway).

Thanks again... I've read the docs about timedelta several times and that made no sense at all... now, it does. Sometimes, it is not that there is something wrong with documentation, but just the fact that it helps to read the same thing written/explained with other words.

If there is interest, I would be glad to draft a Getting started, Introduction or First steps doc section (whatever fits better). It should be moved to another issue, but it would cover examples of khal list and hopefully this issue.

Glad I could help :)

You definitely did! (:

[amandabee]

The wiki is a good place to work on those, so we can get them to a place where it makes sense to propose additions to the official documentation. I'm also happy to help build out the documentation I wanted when I was getting started!

[lsrdg]

I like the idea of using the wiki, @amandabee ; as far as I can tell the official documentation is at least concise enough. The Examples: list page on the wiki has been updated (including an example with the use of range), I'll see what else could be added (and how could it be added) to the wiki later; new users could benefit of the use of more descriptive explanations.

However, are we getting outside of the scope of this issue?