Improve the dates and time documentation

[a10dix]

Feature request

*** Clearly state the use case.

• What were you doing?
  The date management is a huge feature and I needed to know more. I was searching how to fully use dates and time… I googled and found the 4 pages but only checked the first one: https://taskwarrior.org/docs/dates.html, at first.

• What did you expect to happen?
  Find the information I needed.

• What actually happened?
  It was hard to find it because the date and time information is split on many pages (which is fine) but they are:
  — not (all) cross referenced (and the first one I checked was not, but I finally noticed on the google page results that there were many);
  — and not well explained (this one explains this, that one that, if you don't want this but that, see that other page).
  Note. The pages I found:
  — using_dates.html: the main page, which is about the different date types, the date meanings;
  — dates.html, mainly about the numerical date and time format;
  — named_dates.html, about the alphabetical and calculated date and time format, it develop the huge work you made with dates;
  — calc.html completes the calculated date paragraph even if examples like eg due:"today + 2 days" or scheduled:"november + 1 month" are not given;
  — examples.html is quite useful too.

*** Clearly describe the feature.

• What do you suggest?
  [Ordered list]

1. Add links on each of the pages to the others, eg:
   — either at the end in a “See also” section;
   — or better at the beginning or in the margin below the table of contents.
   (And give, not only links, but also a very small description of the pages eg main or types, num_format, named_format).
2. The dates.html page, because of its name, seems to be the main page but is not (and comes first in Google). Rename it may be more messy than useful, so at best, suggest to read first using_dates.html, or at least give using_dates.html as the first link with the “(main page)” description.
3. Add a few examples at the end of the named_dates.html, in the Calculated dates paragraph, eg due:"today + 2 days", due:today+1d, scheduled:"november + 1 month", scheduled:november+1m, until:"now + 2 hours", until:now+2h, and next to this paragraph in the margin, suggest to “see also” the Dates paragraph of the calc.html page.
4. Maybe move the Synonyms paragraph of dates.html onto named_dates.html for consistency; that would make in my opinion the named_dates.html the second useful page for dates after using_dates.html; this proposition is not really important but I insist, the named_dates.html is really useful and explains the huge work you made with dates, their names, their calculations.

Finally, as a side comment, I use taskwarrior to manage my appointments. The scheduled date is the beginning and the due date is the end. I add a (sometimes yet empty) location: field to know that this is an appointment and not a “real” task. If this is a recurrent feature request, you may add this workaround somewhere.

[pbeckingham]

Well thought out, thank you.

[a10dix]

https://taskwarrior.org/support/faq.html#q9 may be linked too, at the end of the named_dates.html, in the Calculated dates paragraph.

Side note: the FAQ was hidden in the Getting help page of the documentation. I missed it. There may be a direct link from the documentation page https://taskwarrior.org/docs/.

[AdrienLemaire]

It also looks like dates.html documentation is incorrect.
I learnt from this comment that date format Y-M-DTH:N is always recognized, but reading the doc makes it sound like only Y-M-D is default and we need rc.dateformat to specify the time.

This examples uses the default rc.dateformat, which is Y-M-D, to read the date from the command line.

Using rc.dateformat you can specify a date with or without elements that include time

$ task add Open the store due:2015-01-01T08:30:00 rc.dateformat:Y-M-DTH:N:S

I'd also like to know if there is a shortcut to set a time for a task that is today. Was hoping that todayT16:30 would work, but it doesn't. Always writing 2019-05-07T16:30 is cumbersome. Is it possible?
Edit: figured it out with calc documentation: task 9 modify due:today+18h+30min. Not really a win on the character count though...

[pbeckingham]

Try today+16h.

[ahillio]

In regards to dates and times... time-tracking, the integration with Timewarrior, could be better documented.... for example the question "How do I see all the time I've spent on a project?" is a very basic and important report to see, but exactly how does one see this information? This question has been asked by others https://stackoverflow.com/questions/58157555/taskwarrior-is-it-possible-to-report-on-the-time-spent-on-tasks/60168765 and remains unanswered.

[corbolais]

That's one of the reasons why I'm using watson for time tracking now.

Edit: your question gets answered by aggregate:

watson aggregate