Prevent the CLI to canonicalize the binary

For one, it is not necessary: the first argument on the command line is not used any
further when executing the command line. Also, if there is an extension that starts
with the same string as the binary, the binary gets also marked as an extension.
This in turn prohibits the detection of any other Timewarrior command such that e.g.
the command 'summary' in 'timew summary' is treated as an external report, which is
not present and thus makes the call fail.

Closes #677

Signed-off-by: Thomas Lauf <thomas.lauf@tngtech.com>

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  # Enable version updates for GitHub actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/docker-image.yaml

@@ -0,0 +1,57 @@
+name: Timewarrior Docker image
+
+on:
+  workflow_dispatch:
+  workflow_run:
+    workflows: [tests]
+    branches:
+      - develop
+      - stable
+    types:
+      - completed
+
+env:
+  REGISTRY: "ghcr.io"
+
+jobs:
+  build-and-push-docker-image:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') }}
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+
+    steps:
+      - name: Create lowercase repository name
+        run: |
+          GHCR_REPOSITORY="${{ github.repository_owner }}"
+          echo "REPOSITORY=${GHCR_REPOSITORY,,}" >> ${GITHUB_ENV}
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: "recursive"
+
+      - name: Install cosign
+        uses: sigstore/cosign-installer@v3.9.1
+
+      - name: Log into registry ${{ env.REGISTRY }}
+        uses: docker/login-action@v3.4.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push Timewarrior Docker image
+        id: build-and-push
+        uses: docker/build-push-action@v6.18.0
+        with:
+          context: .
+          file: "./docker/timew.dockerfile"
+          push: true
+          tags: ${{ env.REGISTRY }}/${{ env.REPOSITORY }}/timew:${{ github.ref_name }}
+
+      - name: Sign the published Docker image
+        env:
+          COSIGN_EXPERIMENTAL: "true"
+        run: cosign sign ${{ env.REGISTRY }}/${{ env.REPOSITORY }}/timew@${{ steps.build-and-push.outputs.digest }}

.github/workflows/tests.yaml

@@ -0,0 +1,70 @@
+name: tests
+on: [push, pull_request, workflow_dispatch]
+jobs:
+  tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: "Alpine Edge"
+            runner: ubuntu-latest
+            container: alpine-edge
+          - name: "Alpine Latest"
+            runner: ubuntu-latest
+            container: alpine-latest
+          - name: "Archlinux Base"
+            runner: ubuntu-latest
+            container: archlinux
+          - name: "Centos Stream9"
+            runner: ubuntu-latest
+            container: centos-stream9
+          - name: "Debian Stable"
+            runner: ubuntu-latest
+            container: debianstable
+          - name: "Debian Testing"
+            runner: ubuntu-latest
+            container: debiantesting
+          - name: "Fedora 41"
+            runner: ubuntu-latest
+            container: fedora41
+          - name: "Fedora 42"
+            runner: ubuntu-latest
+            container: fedora42
+          - name: "OpenSUSE Leap"
+            runner: ubuntu-latest
+            container: opensuseleap
+          - name: "OpenSUSE Tumbleweed"
+            runner: ubuntu-latest
+            container: opensusetumbleweed
+          - name: "Ubuntu 22.04"
+            runner: ubuntu-latest
+            container: ubuntu2204
+          - name: "Ubuntu 24.04"
+            runner: ubuntu-latest
+            container: ubuntu2204
+          - name: "macOS 13"
+            runner: macos-13
+            container: osx-13
+          - name: "macOS 14"
+            runner: macos-14
+            container: osx-14
+          - name: "macOS 15"
+            runner: macos-15
+            container: osx-15
+    runs-on: ${{ matrix.runner }}
+    continue-on-error: ${{ matrix.continue-on-error == true }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build ${{ matrix.name }}
+        env:
+          DOCKER_REGISTRY: docker.pkg.github.com
+          DOCKER_CACHE_IMAGE: docker.pkg.github.com/${{ github.repository }}/timewarrior_cache
+          GITHUB_USER: ${{ github.actor }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONTAINER: ${{ matrix.container }}
+        run: if [[ !( "${CONTAINER}" =~ osx-* ) ]] ; then docker compose build "test-${CONTAINER}" ; fi
+      - name: Test ${{ matrix.name }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONTAINER: ${{ matrix.container }}
+        run: if [[ !( "${CONTAINER}" =~ osx-* ) ]]; then docker compose run "test-${CONTAINER}" ; else bash test/scripts/test_osx.sh ; fi

.github/workflows/update-docs.yml

@@ -0,0 +1,41 @@
+name: Update docs on ti.net
+on:
+  workflow_dispatch:
+  release:
+    types:
+      - published
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+      - name: Trigger remote workflow to update docs
+        run: |
+          repo_owner="GothenburgBitFactory"
+          repo_name="ti.net"
+          event_type="update-docs"
+          version="${{ github.event.release.tag_name }}"
+
+          # Collect .adoc documentation files
+          doc_filenames=$(find doc/man1 -name '*.adoc' -type f; find doc/man7 -name '*.adoc' -type f)
+
+          # Format doc_filenames with double quotes and commas
+          formatted_doc_filenames="[ $(echo ${doc_filenames} | sed 's/\S\+/\"&\",/g; s/,$//') ]"
+
+          base64_encoded_files=()
+          while IFS= read -r filename; do
+              base64_encoded_file=$(base64 "${filename}" | tr -d '\n')
+              base64_encoded_files+=("\"${base64_encoded_file}\"")
+          done <<< "${doc_filenames}"
+
+          # Format encoded_file_contents with quotes and commas
+          formatted_encoded_file_contents="[ $(IFS=,; echo "${base64_encoded_files[*]}") ]"
+
+          curl -L \
+              -X POST \
+              -H "Accept: application/vnd.github+json" \
+              -H "Authorization: Bearer ${{ secrets.UPDATE_DOCS }}" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
+              https://api.github.com/repos/${repo_owner}/${repo_name}/dispatches \
+              -d "{\"event_type\": \"$event_type\", \"client_payload\": {\"version\": \"${version}\", \"doc_filenames\": ${formatted_doc_filenames}, \"encoded_file_contents\": ${formatted_encoded_file_contents} }}"

.pre-commit-config.yaml

@@ -0,0 +1 @@
+repos: []

.travis.yml

@@ -1,54 +0,0 @@
-sudo: required
-language: generic
-matrix:
-  include:
-    - name: "Gentoo (latest)"
-      os: linux
-      env: CONTAINER=gentoo
-      services: docker
-    - name: "Fedora 28"
-      os: linux
-      env: CONTAINER=fedora28
-      services: docker
-    - name: "Fedora 29"
-      os: linux
-      env: CONTAINER=fedora29
-      services: docker
-    - name: "Debian Stable"
-      os: linux
-      env: CONTAINER=debianstable
-      services: docker
-    - name: "Debian Testing"
-      os: linux
-      env: CONTAINER=debiantesting
-      services: docker
-    - name: "Ubuntu 16.04"
-      os: linux
-      env: CONTAINER=ubuntu1604
-      services: docker
-    - name: "Ubuntu 18.04"
-      os: linux
-      env: CONTAINER=ubuntu1804
-      services: docker
-    - name: "OpenSUSE 15.0"
-      os: linux
-      env: CONTAINER=opensuse1500
-      services: docker
-    - name: "Archlinux"
-      os: linux
-      env: CONTAINER=archlinux
-      services: docker
-    - name: "macOS 10.13"
-      os: osx
-      osx_image: xcode9.4
-      env: CONTAINER=osx
-    - name: "macOS 10.14"
-      os: osx
-      osx_image: xcode10.3
-      env: CONTAINER=osx
-install:
-  # Build the docker container
-  - pushd $TRAVIS_BUILD_DIR
-  - if [[ $CONTAINER != "osx" ]]; then docker-compose build test-$CONTAINER ; fi
-script:
-  - if [[ $CONTAINER != "osx" ]]; then docker-compose run test-$CONTAINER; else bash test/scripts/test_osx.sh ; fi

AUTHORS

@@ -34,6 +34,19 @@ The following submitted code, packages or analysis, and deserve special thanks:
   Dennis Schridde
   quazgar
   Johannes Hertenstein
+  Christian Rösch
+  silent-at-gh
+  Lim Ding Wen
+  Stanisław Wysocki
+  Scott Mcdermott
+  Daniel Hornung
+  Maxim Beder
+  Ankur Sinha
+  Povl Filip Sonne-Frederiksen
+  Benedikt Fein
+  Tadeas Uhlir
+  Iúri Archer
+  Ian Kenney
 
 Thanks to the following, who submitted detailed bug reports and excellent suggestions:
 
@@ -69,7 +82,6 @@ Thanks to the following, who submitted detailed bug reports and excellent sugges
   chronitis
   rudis
   bognolo
-  lumbric
   Antanas B.
   towo
   sclo
@@ -88,3 +100,33 @@ Thanks to the following, who submitted detailed bug reports and excellent sugges
   Saulius Krasuckas
   Tom Dörr
   Joerg Kastning
+  George Buckingham
+  Maximilian Merz
+  choppy812
+  kbcb
+  sclee15
+  varac
+  xeruf
+  Rafael Oliveira
+  agentcoffee
+  eq0cdk
+  squirrellyDave
+  Edd Salkield
+  Oivvio Polite
+  Davide Crucitti
+  Christian Kohlstedde
+  apkawel
+  Leon Grünewald
+  Ivo Forlin
+  aMOPel
+  Per Møldrup-Dalum
+  Beshoy Girgis
+  Sergey Zhuravlevich
+  catexis
+  Aniket Meshram
+  Joachim Meyer
+  arxel-sc
+  Eugene Morozov
+  Stefan Herold
+  Sebastian Carlos
+  ftambara

CMakeLists.txt

@@ -1,12 +1,13 @@
-cmake_minimum_required (VERSION 2.8)
-set (CMAKE_LEGACY_CYGWIN_WIN32 0) # Remove when CMake >= 2.8.4 is required
+cmake_minimum_required (VERSION 3.10)
+set (CMAKE_CXX_STANDARD 17)
 set (CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake")
 set (HAVE_CMAKE true)
 
 project (timew)
 include (CXXSniffer)
+include (FindAsciidoctor)
 
-set (PROJECT_VERSION "1.3.0")
+set (PROJECT_VERSION "1.8.0-dev")
 
 string(TOUPPER "${CMAKE_BUILD_TYPE}" uppercase_CMAKE_BUILD_TYPE)
 
@@ -16,7 +17,7 @@ if (EXISTS ${CMAKE_SOURCE_DIR}/.git/index)
   execute_process (COMMAND git log -1 --pretty=format:%h
                    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
                    OUTPUT_VARIABLE COMMIT)
-  configure_file ( ${CMAKE_SOURCE_DIR}/commit.h.in
+  configure_file (${CMAKE_SOURCE_DIR}/commit.h.in
                   ${CMAKE_SOURCE_DIR}/commit.h)
   message ("-- Found SHA1 reference: ${COMMIT}")
 endif (EXISTS ${CMAKE_SOURCE_DIR}/.git/index)
@@ -31,19 +32,21 @@ set (PACKAGE_STRING "${PACKAGE} ${VERSION}")
 string (TIMESTAMP PACKAGE_DATE "%Y-%m-%d")
 
 if (FREEBSD OR DRAGONFLY)
-SET (TIMEW_MAN1DIR man/man1 CACHE STRING "Installation directory for man pages, section 1")
-SET (TIMEW_MAN5DIR man/man5 CACHE STRING "Installation directory for man pages, section 5")
-SET (TIMEW_MAN7DIR man/man7 CACHE STRING "Installation directory for man pages, section 7")
+  set (TIMEW_MANDIR  man                  CACHE STRING "Installation directory for man pages")
+  set (TIMEW_MAN1DIR ${TIMEW_MANDIR}/man1 CACHE STRING "Installation directory for man pages, section 1")
+  set (TIMEW_MAN5DIR ${TIMEW_MANDIR}/man5 CACHE STRING "Installation directory for man pages, section 5")
+  set (TIMEW_MAN7DIR ${TIMEW_MANDIR}/man7 CACHE STRING "Installation directory for man pages, section 7")
 else (FREEBSD OR DRAGONFLY)
-SET (TIMEW_MAN1DIR share/man/man1 CACHE STRING "Installation directory for man pages, section 1")
-SET (TIMEW_MAN5DIR share/man/man5 CACHE STRING "Installation directory for man pages, section 5")
-SET (TIMEW_MAN7DIR share/man/man7 CACHE STRING "Installation directory for man pages, section 7")
+  set (TIMEW_MANDIR  share/man            CACHE STRING "Installation directory for man pages")
+  set (TIMEW_MAN1DIR ${TIMEW_MANDIR}/man1 CACHE STRING "Installation directory for man pages, section 1")
+  set (TIMEW_MAN5DIR ${TIMEW_MANDIR}/man5 CACHE STRING "Installation directory for man pages, section 5")
+  set (TIMEW_MAN7DIR ${TIMEW_MANDIR}/man7 CACHE STRING "Installation directory for man pages, section 7")
 endif (FREEBSD OR DRAGONFLY)
-SET (TIMEW_DOCDIR  share/doc/timew CACHE STRING "Installation directory for doc files")
+set (TIMEW_DOCDIR share/doc/timew CACHE STRING "Installation directory for doc files")
+set (TIMEW_BINDIR bin             CACHE STRING "Installation directory for Timewarrior executable")
 
 message ("-- Configuring cmake.h")
-configure_file (
-  ${CMAKE_SOURCE_DIR}/cmake.h.in
+configure_file (${CMAKE_SOURCE_DIR}/cmake.h.in
                 ${CMAKE_SOURCE_DIR}/cmake.h)
 
 add_subdirectory (src)
@@ -54,7 +57,7 @@ if (EXISTS ${CMAKE_SOURCE_DIR}/test)
   add_subdirectory (test EXCLUDE_FROM_ALL)
 endif (EXISTS ${CMAKE_SOURCE_DIR}/test)
 
-set (doc_FILES NEWS ChangeLog README.md INSTALL AUTHORS COPYING LICENSE)
+set (doc_FILES ChangeLog README.md INSTALL AUTHORS LICENSE)
 foreach (doc_FILE ${doc_FILES})
   install (FILES ${doc_FILE} DESTINATION ${TIMEW_DOCDIR})
 endforeach (doc_FILE)
@@ -63,9 +66,22 @@ endforeach (doc_FILE)
 
 set (CPACK_SOURCE_GENERATOR "TGZ")
 set (CPACK_SOURCE_PACKAGE_FILE_NAME ${PACKAGE_NAME}-${PACKAGE_VERSION})
-set (CPACK_SOURCE_IGNORE_FILES  "CMakeCache" "CMakeFiles" "CPackConfig" "CPackSourceConfig"
-                                "_CPack_Packages" "cmake_install" "install_manifest" "Makefile$"
-                                "test" "package-config" "src/timew$" "src/libtimew.a"
-                                "src/commands/libcommands.a" "src/lex$" "src/liblibshared.a"
-                                "/\\\\.gitignore" "/\\\\.git/" "swp$")
+set (CPACK_SOURCE_IGNORE_FILES  "CMakeCache"
+                                "CMakeFiles"
+                                "CPackConfig"
+                                "CPackSourceConfig"
+                                "_CPack_Packages"
+                                "cmake_install"
+                                "install_manifest"
+                                "Makefile$"
+                                "test"
+                                "package-config"
+                                "src/timew$"
+                                "src/libtimew.a"
+                                "src/commands/libcommands.a"
+                                "src/lex$"
+                                "src/liblibshared.a"
+                                "/\\\\.gitignore"
+                                "/\\\\.git/"
+                                "swp$")
 include (CPack)

CONTRIBUTING.md

@@ -8,13 +8,13 @@ Anyone can contribute, and everyone is encouraged to do so.
 Here are the different ways you might conѕider contributing:
 
 1. Reviews
-1. Bug reports
-1. Feature requests
-1. Code contribution
+2. Bug reports
+3. Feature requests
+4. Code contribution
 
 Please read the respective section below about the details.
 
-Otherwise you can spread the word and recommend Timewarrior to your friends and colleagues.
+Otherwise, you can spread the word and recommend Timewarrior to your friends and colleagues.
 
 
 ## Reviews
@@ -29,7 +29,7 @@ It is also the quickest way to get help, or confirm a bug.
 
 Review documentation: there are man pages, online articles, tutorials and so on, and these may contain errors, or they may not convey ideas in the best way.
 You can help improve it.
-Documentation is a separate effort from the codebase, and includes all web sites, and all are available using git.
+Documentation is a separate effort from the codebase, and includes all websites, and all are available using Git.
 
 Take a look at the bug database, and help triage the bug list.
 Bug triage is very useful and much needed.
@@ -43,7 +43,7 @@ Review the source code, and point out inefficiencies, problems, unreadable funct
 ## Bug reports
 
 Before you submit a bug report, make sure you are using the latest version of Timewarrior. 
-Also please take your time and scan the current bug tickets on our [Github issue tracker](https://github.com/GothenburgBitFactory/timewarrior/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Abug) whether your issue has already been reported.
+Also, please take your time and scan the current bug tickets on our [GitHub issue tracker](https://github.com/GothenburgBitFactory/timewarrior/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Abug) whether your issue has already been reported.
 
 When you submit a bug report, be precise and put as much information into your bug report as possible.
 You should at least provide
@@ -64,7 +64,7 @@ An example:
 
 ## Feature requests
 
-As for bug reports, you should check our [Github issue tracker](https://github.com/GothenburgBitFactory/timewarrior/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Aenhancement) whether your feature has already been requested.
+As for bug reports, you should check our [GitHub issue tracker](https://github.com/GothenburgBitFactory/timewarrior/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Aenhancement) whether your feature has already been requested.
 
 When you submit a feature request, provide a use case which captures the overall intention of your feature, not the technical implementation.
 
@@ -85,9 +85,9 @@ Plus, you might get your feature implemented.
 There are different ways you can contribute code to the project:
 
 1. Add extensions
-1. Add tests
-1. Fix bugs
-1. Add features
+2. Add tests
+3. Fix bugs
+4. Add features
 
 
 ### Extensions
@@ -96,12 +96,12 @@ Extensions are standalone programs or scripts that consume Timewarrior data outp
 
 Extensions are the easiest way to contribute as you only need to adhere to the extension API, but are otherwise free in your choice of programming language and style. 
 
-Consult the [documentation](https://taskwarrior.org/docs/timewarrior/api.html) on how you can use the extension API.
+Consult the [documentation](https://timewarrior.net/docs/api.html) on how you can use the extension API.
 
 
 ### Tests, Bug-fixes and Features
 
-In general your contributions have to be associated with an issue on our [Github issue tracker](https://github.com/GothenburgBitFactory/timewarrior/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen).
+In general your contributions have to be associated with an issue on our [GitHub issue tracker](https://github.com/GothenburgBitFactory/timewarrior/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen).
 See the sections above on how to submit bug reports and feature requests.
 
 Code contributions are only accepted as pull-requests.
@@ -123,32 +123,32 @@ By contributing, you are declaring that you have the right to submit the code un
  
 ## How to make a pull-request
 
-The main branch for development is named `dev`.
+The main branch for development is named `develop`.
 This is the branch where your changes must go.
-The `master` branch always points to the latest release.
+The `stable` branch always points to the latest release.
 No development takes place here.
 
-To make a pull request you need to have a Github account.
+To make a pull request you need to have a GitHub account.
 
-1. Fork the [Timewarrior repository](https://github.com/GothenburgBitFactory/timewarrior) on Github.
-1. Checkout the development branch.
+1. Fork the [Timewarrior repository](https://github.com/GothenburgBitFactory/timewarrior) on GitHub.
+2. Checkout the development branch.
 
        $ git checkout dev
 
-1. Create a feature branch.
+3. Create a feature branch.
 
        $ git checkout -b feature_branch
 
-1. Commit your changes, and finally push to the remote repository.
+4. Commit your changes, and finally push to the remote repository.
    Use a commit message that matches the prevailing format. (See `git log` for examples.)
    
-       $ git commit -am '<issue>: <description>'
+       $ git commit --signoff -am '<issue>: <description>'
        ...
        $ git push origin feature_branch
     
-    Furthermore, commits should be signed off according to the [DCO](DCO).
+    Furthermore, commits should be signed off according to the [DCO](DCO) (use `-s` / `--signoff` flag when committing).
     
-1. Create the pull request on Github.
+5. Create the pull request on GitHub.
 
 ## What happens next?
 
@@ -206,5 +206,5 @@ To be a little more explicit, the common elements across the languages are:
 
 We target Python 3 so that our test suite runs on the broadest set of platforms.
 
-We can safely target C++11 because all the default compilers on our supported platforms are ready.
-Feel free to use C++14 and C++17 provided that all build platforms support this.
+We can safely target C++17 because all the default compilers on our supported platforms are ready.
+Feel free to use C++20 provided that all build platforms support this.

COPYING

@@ -1,23 +0,0 @@
-Timewarrior - a command line time tracker
-
-Copyright 2015 - 2018, Paul Beckingham, Federico Hernandez.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included
-in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
-THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-https://www.opensource.org/licenses/mit-license.php

ChangeLog

@@ -1,6 +1,199 @@
+- #677    Extension names starting with 'timew' cause problems
+          (thanks to ftambara)
+- #661    Make display of ids and annotations the default in summary report for new users
+- #669    id filtering for charts and reports
+- #660    Fix man page section numbers and reference formatting
+
 ------ current release ---------------------------
 
-1.3.0 (2020-04-19) -
+1.8.0 (2025-04-20) - 2257084710247189231118bc9257180a815ef21a
+
+- #658    Add sub-command 'range' to command 'modify'
+          (thanks to Sebastian Carlos)
+- #620    Fix installation of man pages from tarball
+- #600    Add retag command to internal help
+          (thanks to Stefan Herold)
+- #616    Add zsh completion
+          (thanks to Ian Kenney)
+- #633    Make week number parsing ISO8601 compliant
+          (thanks to Scott Mcdermott)
+- #632    Fix py3.12 warnings for datetime usage, non-raw regex strings
+          (thanks to Scott Mcdermott)
+
+------ old releases ------------------------------
+
+1.7.1 (2024-01-16) - 2514d506b5580154f1e00c0e72b17c8e9bc89cb7
+
+- #580    internal parsing of tags starting with number broken
+          (thanks to arxel-sc)
+- #582    Retrieval of intervals with tags containing hyphens is broken
+          (thanks to Eugene Morozov)
+- #583    README - Update build instructions
+          (thanks to Joachim Meyer)
+
+1.7.0 (2023-12-24) - 63f7fc95a0fa20dc768ae4e94b7f2d79c306f9dd
+
+- #205    Wrap annotations in summary
+          (thanks to varac)
+- #493    :lastweek doesn't count last Sunday
+          (thanks to Saulius Krasuckas, Per Møldrup-Dalum, Beshoy Girgis, Sergey Zhuravlevich)
+- #494    Expand annotations in summary
+          (thanks to catexis)
+- #566    Set table width dynamically to terminal width
+- #573    Filter summary based on ids
+          (thanks to Aniket Meshram)
+- #576    Fix quoting of tags in DOM output
+-         Add ':today' hint
+-         Refactor holidays/refresh script
+-         Update task-timewarrior-hook script to 87a3426d8153f92aaee2edf36b2de62e48c4de0e
+
+1.6.0 (2023-09-18) - cd1aa610ed50558bb2cf141022fa7b41523091ac3ae5fbb9c2d459cfe1afc782
+
+- #529    Fix summary truncating multibyte characters in long annotations
+          (thanks to Maxim Beder, Leon Grünewald)
+- #531    Update CONTRIBUTING.md to use branch 'develop' instead of 'dev'
+          (thanks to Maxim Beder)
+- #535    Adding completion for fish shell
+          (thanks to Povl Filip Sonne-Frederiksen)
+- #538    Fix man page build for out-of-source builds
+          (thanks to Benedikt Fein)
+- #540    reports should end at current time if a task is still running
+          (thanks to Ankur Sinha)
+- #547    AtomicFile: Operate on the target of symlinks
+          (thanks to Shaun Ruffel, Ivo Forlin)
+- #551    Add retag command
+          (thanks to Iúri Archer)
+- #552    Extend XDG support to macOS
+          (thanks to Tadeas Uhlir)
+- #553    Configurability of CMake install directories
+          (thanks to aMOPel)
+- #554    Update documentation for command 'retag'
+          (thanks to quazgar)
+-         Use local man pages in tests
+          (thanks to Maxim Beder)
+-         Cleanup CMake files
+-         Update project to C++17
+
+1.5.0 (2023-04-04) - 51e7c2c772837bbd6d56da8d16506c4b6de8644166e0b5234ad36ae6a70dd4f6
+
+- #361    Improve documentation
+          (thanks to xeruf)
+- #389    Extend summary configuration
+          (thanks to Davide Crucitti)
+- #489    First execution creates database regardless of confirmation response
+          (thanks to Rafael Oliveira)
+- #403    Remove incorrect output stating that an empty interval was recorded
+          (thanks to xeruf)
+- #406    Clarify minimal value for 'epoch' as date value
+          (thanks to Daniel Hornung)
+- #408    Update documentation of hint `:all`
+          (thanks to quazgar)
+- #437    Minor AtomicFile cleanup
+          (thanks to Shaun Ruffel)
+- #439    Show error message if command track is called with an id
+- #441    Return report return code
+          (thanks to lospatchos)
+- #444    Improve documentation on annotations
+          (thanks to apkawel, Shaun Ruffel)
+- #450    Report 'totals.py' does not display data when no time range specified
+          (thanks to squirrellyDave)
+- #458    Add man documentation for configuring tag colors.
+          (thanks to Lim Ding Wen)
+- #463    Add colors to summary
+          (thanks to Lim Ding Wen)
+- #466    Ignore empty exclusion ranges
+- #468    Refactor interval filtering
+- #469    Do not leak IntervalFilters in IntervalFilterAndGroup
+          (thanks to Shaun Ruffel)
+- #470    Do not leak filter in IntervalFilterFirstOf
+          (thanks to Shaun Ruffel)
+- #474    Make display of ids and annotations in summary report configurable
+- #477    Add configurable default range for reports
+          (thanks to Oivvio Polite, Christian Kohlstedde)
+- #478    Add support for XDG Base Directory specification on Unixes
+          (thanks to Stanisław Wysocki)
+- #491    Tracking an interval in the future while actively tracking time results in a database inconsistency
+          (thanks to agentcoffee)
+- #505    Report 'totals.py' does not truncate intervals to report range
+          (thanks to eq0cdk)
+- #510    Export intervals by IDs
+          (thanks to Scott Mcdermott)
+- #512    help.t fails on alpine with mandoc package
+          (thanks to Edd Salkield)
+-         Add option '--details' to 'test/problems' script
+
+1.4.3 (2021-05-28) - fc618636aacba6e52d447b482aeef58b375dfc8c
+
+- #159    Tags enclosed in escaped double-quotes are not handled correctly
+          (thanks to Shaun Ruffell)
+- #379    CmdSummary: Fix calculation of display start in summary table
+          (thanks to Shaun Ruffell)
+- #387    Fixed URL for tarball download
+          (thanks to Joerg Kastning)
+- #390    dom.tracked.X.tag.Y always returns dom.tracked.1.tag.Y
+          (thanks to pweaver2019)
+- #393    Update dark_blue.theme
+          (thanks to Peter Zuidema)
+- #398    test: Thread.isAlive() -> Thread.is_alive()
+          (thanks to Shaun Ruffell)
+- #410    Replace roff man pages with asciidoctor
+- #411    Transfer platform testing from Travis CI to GitHub Actions
+- #416    Internal error. Failed encode / decode check when doing undo
+          (thanks to narudarurarasya, Shaun Ruffel)
+- #419    Links not preserved over linebreaks in man page
+          (thanks to draupadi77)
+- #422    Internal error. Failed encode / decode check.
+          (thanks to Glen Solsberry, Shaun Ruffell)
+-         Width determination of Unicode characters now works for up to
+          Unicode 11 (from Unicode 5). Emojis are correctly displayed.
+-         Fix test `summary.t` for single-digit weeks
+
+1.4.2 (2020-08-29) - 4aa8489243adb69958d7717fb2f010c72fd4505a
+
+- #377    make install with error due to missing file `COPYING`
+          (thanks to Dirk Deimeke)
+
+1.4.1 (2020-08-29) - 6747beb2963475f50d2d58b1da5465247eb9e28e
+
+- #378    Summary with `:all` hint is empty for open interval
+
+1.4.0 (2020-08-29) - 2447c3817212d0fd987a8fe749d181ba7073a978
+
+- #126    DOM-Query for ids
+- #188    DOM-Query for tags
+- #206    Add :all hint
+          (thanks to varac, Shaun Ruffell)
+- #241    Allow continue by tag.
+          (thanks to Christian Rösch)
+- #258    make error FS.cpp on freebsd 12.1
+          (thanks to choppy812, silent-at-gh, kbcb, Shaun Ruffell)
+- #307    Introduce 'journal.size' configuration item
+          (thanks to Shaun Ruffell)
+- #309    unicode input causes indefinite hang for commands like day or month
+          (thanks to sclee15, Shaun Ruffell)
+- #317    Fix memory leak in JSON parsing
+          (thanks to Shaun Ruffell)
+- #318    Speed up deserialization of Intervals
+          (thanks to Shaun Ruffell)
+- #331    start command adjust
+          (thanks to Shaun Ruffell)
+- #333    Summary command fails with `:all` hint
+- #335    Update docs links from taskwarrior.org to timewarrior.net
+          (thanks to George Buckingham)
+- #347    delete interval silently fails
+          (thanks to Shaun Ruffell)
+- #351    Stop failed to close currently tracking interval
+          (thanks to Shaun Ruffell)
+- #364    Entering an open interval with future date causes assertion error
+          (thanks to kbcb)
+- #370    Core dump on `timew week` when open interval overlaps into exclusion
+          (thanks to Maximilian Merz)
+- #367    CmdDiagnostics: Show per-file error messages.
+          (thanks to Shaun Ruffell)
+- #372    Empty intervals are not deleted in `:adjust` overlap resolution
+          (thanks to xeruf)
+
+1.3.0 (2020-04-19) - 3de53d7599d1e4364c8aaaeb3c3ef1fe89ee3380
 
 - #155    Corrupts database when no disk space available
           (thanks to Shaun Ruffell, Tom Dörr)
@@ -20,9 +213,9 @@
 - #278    New hint :fortnight added
           (thanks to quazgar)
 - #282    Database: Fix error when empty datafile is most recent / oldest
-          (Thanks to Shaun Ruffell)
+          (thanks to Shaun Ruffell)
 - #283    Use AtomicFile to commit files as a group
-          (Thanks to Shaun Ruffell)
+          (thanks to Shaun Ruffell)
 - #284    tags.data modification date updated when file is not modified
           (thanks to Shaun Ruffell, Charlie Gorichanaz)
 - #285    Pass record id to extensions
@@ -33,8 +226,6 @@
           (thanks to Shaun Ruffell, Saulius Krasuckas)
 - #298    Add current version of bash-completion
 
------- old releases ------------------------------
-
 1.2.0 (2019-11-22) 1d271508a27b9d8a5211ae5b01c7a0583ff690fd
 
 - #2      Generate a warning when a new tag is used on the command line

DCO

@@ -38,7 +38,7 @@ using your real name (sorry, no pseudonyms or anonymous contributions.)
 
 The DCO text can either be manually added to your commit body, or you can add either **-s** or **--signoff** to your usual git commit commands.
 If you forget to add the sign-off you can also amend a previous commit with the sign-off by running **git commit --amend -s**.
-If you've pushed your changes to Github already you'll need to force push your branch after this with **git push -f**.
+If you've pushed your changes to GitHub already you'll need to force push your branch after this with **git push -f**.
 
 
 #### Alternative Sign-Off Methods in rare cases

INSTALL

@@ -7,12 +7,13 @@ Please follow the instructions below to build and install Timewarrior from sourc
 
 In order to build Timewarrior, you will need:
 
-  - cmake (See https://cmake.org)
-  - make
+  - CMake (See https://cmake.org)
+  - Make
+  - Asciidoctor (for building documentation)
 
-You will need a C++ compiler that supports full C++11, which includes:
-  - gcc 4.8.1 (released 2013-03-31)
-  - clang 3.3 (released 2013-06-17)
+You will need a C++ compiler that supports full C++17, which includes:
+  - GCC 8
+  - Clang 5
 
 
 # Basic Installation
@@ -46,49 +47,41 @@ These commands are explained below:
 
 # Build and configurations options
 
-You can customize the configuration run with cmake variables.
-This will modify the installation process:
-
-To change the installation directory you use the following configuration variable:
-
-    $ cmake -DCMAKE_INSTALL_PREFIX=<path-to-installation-dir> .
-
-cmake configuration variables are applied with the -D option and consist of a <name> and a <value>:
+You can customize the configuration run with CMake variables.
+CMake configuration variables are applied with the `-D` option and consist of a `<name>` and a `<value>`:
 
     $ cmake -D<name>=<value> .
 
-Four more variables can customize the installation process.
-The following table lists them and their defaults plus the `CMAKE_INSTALL_PREFIX`:
+To change the installation directory, use the `CMAKE_INSTALL_PREFIX` variable:
 
-    CMAKE_INSTALL_PREFIX   /usr/local
-    TIMEW_BINDIR           bin
-    TIMEW_DOCDIR           share/doc/timew
-    TIMEW_RCDIR            share/doc/timew/rc
-    TIMEW_MAN1DIR          share/man/man1
-    TIMEW_MAN5DIR          share/man/man5
-    TIMEW_MAN7DIR          share/man/man7
+    $ cmake -DCMAKE_INSTALL_PREFIX=<path-to-installation-dir> .
 
-The corresponding `TIMEW_*` variables will be combined with `CMAKE_INSTALL_PREFIX` to get absolute installation directories:
+This variable defaults to `/usr/local` on UNIX/Linux systems.
 
-    CMAKE_INSTALL_PREFIX/TIMEW_BINDIR   /usr/local/bin
-    CMAKE_INSTALL_PREFIX/TIMEW_DOCDIR   /usr/local/share/doc/timew
-    CMAKE_INSTALL_PREFIX/TIMEW_RCDIR    /usr/local/share/doc/timew/rc
-    CMAKE_INSTALL_PREFIX/TIMEW_MAN1DIR  /usr/local/share/man/man1
-    CMAKE_INSTALL_PREFIX/TIMEW_MAN5DIR  /usr/local/share/man/man5
-    CMAKE_INSTALL_PREFIX/TIMEW_MAN7DIR  /usr/local/share/man/man7
+Five more variables can customize the installation process.
+The following table lists them and their default values:
+
+| Variable        | Default Value     |
+|-----------------|-------------------|
+| `TIMEW_BINDIR`  | `bin`             |
+| `TIMEW_DOCDIR`  | `share/doc/timew` |
+| `TIMEW_MANDIR`  | `share/man`       |
+| `TIMEW_MAN1DIR` | `share/man/man1`  |
+| `TIMEW_MAN7DIR` | `share/man/man7`  |
+
+On FreeBSD or DragonFly BSD systems, the `share/` directory is omitted for the `TIMEW_MAN*DIR` variables.
+
+The `TIMEW_*` variables are combined with the value of `CMAKE_INSTALL_PREFIX` to get the absolute paths.
 
 
 # Updating Timewarrior build
 
-This section concerns itself with the description of the procedure needed to update the local Timewarrior build from the 'timew' git repository.
-
-To update the local Timewarrior build, you need to update the git repository, including the `src/libshared` submodule.
-To do that, run:
+To update the local Timewarrior build, you need to update the Git repository, including the `src/libshared` submodule, run:
 
     $ git pull --recurse-submodules
     $ git submodule update
 
-At this point you have the fully updated sources at your disposal and you can update your local build following the regular build instructions:
+At this point you have the fully updated sources at your disposal, and you can update your local build following the regular build instructions:
 
     $ cmake .
     $ make
@@ -107,7 +100,7 @@ To uninstall Timewarrior, remove the files listed in the `install_manifest.txt`
 
 Timewarrior has dependencies that are detected by CMake in almost all cases, but there are situations and operating systems that mean you will need to offer a little help.
 
-If Timewarrior will not build on your system, first take a look at the Operating System notes below.
+If Timewarrior does not build on your system, first take a look at the Operating System notes below.
 If this doesn't help, then go to the Troubleshooting section, which includes instructions on how to contact us for help.
 
 

LICENSE

@@ -1,6 +1,8 @@
-Timewarrior - a command line time tracker
+MIT license
 
-Copyright 2015 - 2019, Thomas Lauf, Paul Beckingham, Federico Hernandez.
+https://opensource.org/licenses/mit-license.php
+
+Copyright 2015 - 2023, Thomas Lauf, Paul Beckingham, Federico Hernandez.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -20,4 +22,3 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-https://www.opensource.org/licenses/mit-license.php

NEWS

@@ -1,50 +0,0 @@
-New Features in 1.3.0
-
-  - Performance improvements
-  - Switch to python 3
-  - New hint ':fortnight'
-  - Pass interval id to extensions
-
-New Commands in 1.3.0
-
-  - None
-
-New Configuration Options 1.3.0
-
-  - None
-
-Newly Deprecated Features in 1.3.0
-
-  - None
-
-Removed Features in 1.3.0
-
-  - None
-
-Known Issues
-
-  - See https://github.com/GothenburgBitFactory/timewarrior/issues
-
-Timewarrior has been built and tested on the following configurations:
-
-  * Arch
-  * CentOS
-  * Debian
-  * Fedora
-  * Gentoo
-  * openSUSE
-  * Ubuntu
-  * macOS
-
----
-
-While Timewarrior has undergone testing, bugs are sure to remain.
-If you find a bug, please enter a new issue at:
-
-    https://github.com/GothenburgBitFactory/timewarrior/issues
-
-Or just send a message to:
-
-    support@gothenburgbitfactory.org
-
-Thank you.

README.md

@@ -1,71 +1,101 @@
-# Timewarrior
+<div align="center">
+<img alt="Timewarrior logo" src="https://avatars.githubusercontent.com/u/36100920?s=200&u=24da05914c20c4ccfe8485310f7b83049407fa9a&v=4">
+<br>
 
-[![Build Status](https://travis-ci.org/GothenburgBitFactory/timewarrior.svg?branch=dev)](https://travis-ci.org/GothenburgBitFactory/timewarrior)
+[![Tests](https://github.com/GothenburgBitFactory/timewarrior/actions/workflows/tests.yaml/badge.svg)](https://github.com/GothenburgBitFactory/timewarrior/actions/workflows/tests.yaml)
+[![Release](https://img.shields.io/github/v/release/GothenburgBitFactory/timewarrior)](https://github.com/GothenburgBitFactory/timewarrior/releases/latest)
+[![Release date](https://img.shields.io/github/release-date/GothenburgBitFactory/timewarrior)](https://github.com/GothenburgBitFactory/timewarrior/releases/latest)
+![Commits since release](https://img.shields.io/github/commits-since/GothenburgBitFactory/timewarrior/latest)
+<br>
+[![Twitter](https://img.shields.io/twitter/follow/timewarrior_net?style=social)](https://twitter.com/timewarrior_net)
+</div>
+
+# Timewarrior
+![macOS downloads](https://img.shields.io/homebrew/installs/dy/timewarrior?label=macOS%20downloads)
+![GitHub downloads](https://img.shields.io/github/downloads/GothenburgBitFactory/timewarrior/total?label=GitHub%20downloads)
+![Linux downloads](https://img.shields.io/badge/Linux%20downloads-unknown-gray)
 
 Thank you for taking a look at Timewarrior!
 
 Timewarrior is a time tracking utility that offers simple stopwatch features as well as sophisticated calendar-based backfill, along with flexible reporting.
-It is a portable, well supported and very active Open Source project.
+It is a portable, well-supported and very active Open Source project.
+
+Please visit [timewarrior.net](https://timewarrior.net/docs/) for extensive documentation, downloads, news and more.
 
 ## Installing
+[![Arch Linux](https://img.shields.io/archlinux/v/extra/x86_64/timew)](https://archlinux.org/packages/extra/x86_64/timew/)
+[![Debian](https://img.shields.io/debian/v/timewarrior/testing)](https://packages.debian.org/search?keywords=timewarrior&searchon=names&suite=all&section=all)
+[![Fedora](https://img.shields.io/fedora/v/timew)](https://bodhi.fedoraproject.org/updates/?packages=timew)
+[![Homebrew](https://img.shields.io/homebrew/v/timewarrior)](https://formulae.brew.sh/formula/timewarrior#default)
+[![Ubuntu](https://img.shields.io/ubuntu/v/timew)](https://packages.ubuntu.com/search?keywords=timewarrior&searchon=names&suite=hirsute&section=all)
 
 ### From Package
 
-Thanks to the community, there are binary packages available [here](https://timewarrior.net/docs/download.html#distributions).
+Thanks to the community, there are binary packages available [here](https://timewarrior.net/docs/install/#distributions).
 
 ### Building Timewarrior
 
 Building Timewarrior yourself requires
 
-* git
-* cmake
-* make
-* C++ compiler, currently gcc 4.8.1+ or clang 3.3+ for full C++11 support
-* Python 3, for running the testsuite
+* Git
+* CMake (>= 3.8)
+* Make
+* C++ compiler with full C++17 support, currently GCC 8+ or Clang 5+ 
+* Python 3 (for running the testsuite)
+* Asciidoctor (for creating documentation)
 
 There are two ways to retrieve the Timewarrior sources:
 
-* Clone the repository from Github,
-
+* Clone the repository from GitHub and update required submodules,
+  ```
   git clone --recurse-submodules https://github.com/GothenburgBitFactory/timewarrior
   cd timewarrior
-
+  ```
 * Or download the tarball with curl,
-
-      curl -O https://taskwarrior.org/download/timew-1.1.1.tar.gz
-
+  ```
+  curl -O https://github.com/GothenburgBitFactory/timewarrior/releases/download/v1.8.0/timew-1.8.0.tar.gz
+  ```
   and expand the tarball
-
-      tar xzf timew-1.1.1.tar.gz
-      cd timew-1.1.1
-
-Build Timewarrior, optionally run the test suite (note: the tarball does not contain tests), and install it.
-
-    cmake -DCMAKE_BUILD_TYPE=release
-    make
-    [make test]
-    sudo make install
-
+  ```
+  tar xzf timew-1.8.0.tar.gz
+  cd timew-1.8.0
+  ```
+Build Timewarrior, optionally run the test suite, and install it.
+```
+cmake -DCMAKE_BUILD_TYPE=release .
+make
+[make test]
+sudo make install
+```
 This copies files into the right place (default under `/usr/local`), and installs man pages.
 
 Add the optional parameter `-DCMAKE_INSTALL_PREFIX=/path/to/your/install/location` to the `cmake` command if you want to install Timewarrior at a location other than `/usr/local`.
 The `make install` command may not require `sudo` depending on your choice of install location.
 
-## Documentation
+## Community
+[![Twitter](https://img.shields.io/twitter/follow/timewarrior_net?style=social)](https://twitter.com/timewarrior_net)
+[![Reddit](https://img.shields.io/reddit/subreddit-subscribers/taskwarrior?style=social)](https://reddit.com/r/taskwarrior/)
+[![Libera.chat](https://img.shields.io/badge/IRC%20libera.chat-online-green)](https://web.libera.chat/#taskwarrior)
+[![Discord](https://img.shields.io/discord/796949983734661191?label=discord)](https://discord.gg/HYpSAeVH)
+[![GitHub discussions](https://img.shields.io/github/discussions/GothenburgBitFactory/timewarrior?label=GitHub%20discussions)](https://github.com/GothenburgBitFactory/timewarrior/discussions)
 
-There is extensive online documentation.
-You'll find all the details at [timewarrior.net/docs/](https://timewarrior.net/docs/).
+Timewarrior has a lively community on many places on the internet.
+The project has its own Twitter account, and shares community spaces on IRC and Discord with [Taskwarrior](https://github.com/GothenburgBitFactory/taskwarrior).
 
-There you will find the documentation, downloads, news and more.
+Best place to ask questions is our [discussions forum on GitHub](https://github.com/GothenburgBitFactory/timewarrior/discussions).
+For other support options, take a look at [timewarrior.net/support](https://timewarrior.net/support)
 
 ## Contributing
+[![Contributors](https://img.shields.io/github/contributors/GothenburgBitFactory/timewarrior)](https://github.com/GothenburgBitFactory/timewarrior/graphs/contributors)
+[![Milestone progress](https://img.shields.io/github/milestones/progress/GothenburgBitFactory/timewarrior/11?label=current%20milestone%20issues)](https://github.com/GothenburgBitFactory/timewarrior/milestone/11)
+[![Good first issues](https://img.shields.io/github/issues/GothenburgBitFactory/timewarrior/good%20first%20issue)](https://github.com/GothenburgBitFactory/timewarrior/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
 
-Your contributions are especially welcome.
-Whether it comes in the form of code patches, ideas, discussion, bug reports, encouragement or criticism, your input is needed.
+Contributions are greatly appreciated.
+Whether in the form of code patches, ideas, discussion, bug reports, encouragement or criticism, we need you!
 
-For support options, take a look at [CONTRIBUTING.md](CONTRIBUTING.md) or visit [taskwarrior.org](https://taskwarrior.org/support).
+For support options, take a look at [CONTRIBUTING.md](CONTRIBUTING.md) or visit [timewarrior.net](https://timewarrior.net/support).
 
-Visit [Github](https://github.com/GothenburgBitFactory/timewarrior) and participate in the future of Timewarrior.
+Visit [GitHub](https://github.com/GothenburgBitFactory/timewarrior) and participate in the future of Timewarrior.
 
 ## License
 

cmake.h.in

@@ -11,9 +11,6 @@
 
 #define CMAKE_BUILD_TYPE  "${CMAKE_BUILD_TYPE}"
 
-/* Installation details */
-#define TIMEW_RCDIR "${CMAKE_INSTALL_PREFIX}/${TIMEW_RCDIR}"
-
 /* git information */
 #cmakedefine HAVE_COMMIT
 
@@ -45,4 +42,3 @@
 #cmakedefine HAVE_GET_CURRENT_DIR_NAME
 #cmakedefine HAVE_TIMEGM
 #cmakedefine HAVE_UUID_UNPARSE_LOWER
-

cmake/CXXSniffer.cmake

@@ -1,30 +1,10 @@
-message ("-- Configuring C++11")
 message ("-- System: ${CMAKE_SYSTEM_NAME}")
 
-include (CheckCXXCompilerFlag)
-
-# NOTE: Phase out -std=gnu++0x and --std=c++0x as soon as realistically possible.
-CHECK_CXX_COMPILER_FLAG("-std=c++11"   _HAS_CXX11)
-CHECK_CXX_COMPILER_FLAG("-std=c++0x"   _HAS_CXX0X)
-CHECK_CXX_COMPILER_FLAG("-std=gnu++0x" _HAS_GNU0X)
-
-if (_HAS_CXX11)
-  set (_CXX11_FLAGS "-std=c++11")
-elseif (_HAS_CXX0X)
-  message (WARNING "Enabling -std=c++0x draft compile flag. Your compiler does not support the standard '-std=c++11' option.  Consider upgrading.")
-  set (_CXX11_FLAGS "-std=c++0x")
-elseif (_HAS_GNU0X)
-  message (WARNING "Enabling -std=gnu++0x draft compile flag. Your compiler does not support the standard '-std=c++11' option. Consider upgrading.")
-  set (_CXX11_FLAGS "-std=gnu++0x")
-else (_HAS_CXX11)
- message (FATAL_ERROR "C++11 support missing. Try upgrading your C++ compiler. If you have a good reason for using an outdated compiler, please let us know at support@gothenburgbitfactory.org.")
-endif (_HAS_CXX11)
-
 if (${CMAKE_SYSTEM_NAME} MATCHES "Linux")
   set (LINUX true)
 elseif (${CMAKE_SYSTEM_NAME} MATCHES "Darwin")
   set (DARWIN true)
-  set (_CXX11_FLAGS "${_CXX11_FLAGS} -stdlib=libc++")
+  set (CMAKE_CXX_FLAGS "-stdlib=libc++ ${CMAKE_CXX_FLAGS}")
 elseif (${CMAKE_SYSTEM_NAME} MATCHES "kFreeBSD")
   set (KFREEBSD true)
 elseif (${CMAKE_SYSTEM_NAME} MATCHES "FreeBSD")
@@ -41,13 +21,8 @@ elseif (${CMAKE_SYSTEM_NAME} STREQUAL "GNU")
   set (GNUHURD true)
 elseif (${CMAKE_SYSTEM_NAME} STREQUAL "CYGWIN")
   set (CYGWIN true)
-  # NOTE: Not setting -std=gnu++0x leads to compile errors even with
-  #       GCC 4.8.3, and debugging those leads to insanity. Adding this
-  #       workaround instead of fixing Cygwin.
-  set (_CXX11_FLAGS "-std=gnu++0x")
 else (${CMAKE_SYSTEM_NAME} MATCHES "Linux")
   set (UNKNOWN true)
 endif (${CMAKE_SYSTEM_NAME} MATCHES "Linux")
 
-set (CMAKE_CXX_FLAGS "${_CXX11_FLAGS} ${CMAKE_CXX_FLAGS}")
 set (CMAKE_CXX_FLAGS "-Wall -Wextra -Wsign-compare -Wreturn-type ${CMAKE_CXX_FLAGS}")

cmake/FindAsciidoctor.cmake

@@ -0,0 +1,16 @@
+message (CHECK_START "Detecting Asciidoctor")
+
+FIND_PROGRAM(ASCIIDOCTOR_EXECUTABLE asciidoctor
+             PATHS "/usr/bin" "/usr/sbin")
+
+MARK_AS_ADVANCED(ASCIIDOCTOR_EXECUTABLE)
+
+if (ASCIIDOCTOR_EXECUTABLE)
+  message(CHECK_PASS "found")
+  message(DEBUG "Found executable ${ASCIIDOCTOR_EXECUTABLE}")
+  set(ASCIIDOCTOR_FOUND "YES")
+else (ASCIIDOCTOR_EXECUTABLE)
+  message(CHECK_FAIL "not found")
+  message(NOTICE "   Could not find Asciidoctor!")
+  set(ASCIIDOCTOR_FOUND "NO")
+endif (ASCIIDOCTOR_EXECUTABLE)

completion/README.md

@@ -1,9 +1,13 @@
-# Shell completion
+# Shell completions
 
-The script here is taken from a separate project.
-Issues and pull-requests should go there.
-The updated version will then be included here.
+The completion scripts here are taken from separate projects.
+Issues and pull-requests regarding those should go there.
+The updated version of each script will then be included here.
 
 If you are missing a completion, feel free to contribute.
 
-* `timew-completion.bash` is taken from https://github.com/lauft/timew-bashcompletion which is released under [MIT license](https://github.com/lauft/timew-bashcompletion/blob/master/LICENSE)
+* `timew.fish` is taken from [pfmephisto/timew-fishcompletion](https://github.com/pfmephisto/timew-fishcompletion) which is released under [MIT license](https://github.com/pfmephisto/timew-fishcompletion/blob/main/LICENSE)
+* `timew-completion.bash` is taken from [lauft/timew-bashcompletion](https://github.com/lauft/timew-bashcompletion) which is released under [MIT license](https://github.com/lauft/timew-bashcompletion/blob/master/LICENSE)
+* `timew.zsh` is taken from [ianmkenney/timewarrior_zsh_completion](https://github.com/ianmkenney/timewarrior_zsh_completion) which is released under [MIT license](https://github.com/ianmkenney/timewarrior_zsh_completion/blob/main/LICENSE)
+
+Huge thanks to everyone contributing! ❤️ 

completion/timew-completion.bash

@@ -1,10 +1,10 @@
-# Bash completion for TimeWarrior
+# Bash completion for Timewarrior
 #
-# Copyright (C) 2017 - 2020 Thomas Lauf
+# Copyright (C) 2017 - 2020, 2023, Thomas Lauf
 #
 function __get_commands()
 {
-  echo "annotate cancel config continue day delete diagnostics export extensions gaps get help join lengthen modify month move report resize shorten show split start stop summary tag tags track undo untag week"
+  echo "annotate cancel config continue day delete diagnostics export extensions gaps get help join lengthen modify month move report resize retag shorten show split start stop summary tag tags track undo untag week"
 }
 
 function __get_subcommands()
@@ -42,7 +42,7 @@ function __get_ids()
 
 function __get_tags()
 {
-  timew tags | tail -n +4 -- | sed -e "s|[[:space:]]*-$||"
+  timew get dom.tracked.tags "${TIMEW_COMPLETION_TAGS_RANGE:-":all"}"
 }
 
 function __get_extensions()
@@ -63,7 +63,8 @@ function __has_entered_id()
 
 function __has_entered_subcommand()
 {
-  local subcommands=$( __get_subcommands "${1}" )
+  local subcommands
+  subcommands=$( __get_subcommands "${1}" )
 
   for word in "${COMP_WORDS[@]}" ; do
     for cmd in ${subcommands} ; do
@@ -78,7 +79,8 @@ function __has_entered_subcommand()
 
 function __has_entered_help_item()
 {
-  local items=$( __get_help_items )
+  local items
+  items=$( __get_help_items )
 
   for word in "${COMP_WORDS[@]:2}" ; do
     for item in ${items} ; do

completion/timew.fish

@@ -0,0 +1,197 @@
+# fish completion for timewarrior
+# https://timewarrior.net/
+# put this file in ~/.config/fish/completions/
+
+function __fish_timew_get_commands
+    timew help | sed -e '/^Usage:/d'  -e '/^Additional help:/Q' \
+        -e 's/timew \[*\([a-z]\+\)\]*.*/\1/g;tx;d;:x' | string trim
+end
+
+function __fish_timew_get_tags
+    timew tags | tail -n+4 | awk '{sub(/-([^-]*)$/, "\\1"); print}' | awk '!/^[[:space:]]*$/' | awk '{$1=$1};1' | awk '{ print "\'"$0"\'"}'
+end
+
+function __fish_timew_get_ids
+    timew summary :ids | sed -e 's/.*@\([0-9]\+\).*/@\1/g;tx;d;:x'
+end
+
+function __fish_timew_get_reports
+    timew extensions | sed -e 's/^\(.*\).*Active/\1/g;tx;d;:x'
+end
+
+# Interval:
+#        [from] <date>
+#        [from] <date> to/- <date>
+#        [from] <date> for <duration>
+#        <duration> before/after <date>
+#        <duration> ago
+#        [for] <duration>
+# timew show | sed -n '/\s\s.*:/p'
+
+set -l commands (__fish_timew_get_commands)
+set -l reports (__fish_timew_get_reports)
+set -l ids (__fish_timew_get_ids)
+set -l tags (__fish_timew_get_tags)
+set -l intervals ""
+set -l durations ""
+set -l dates ""
+set -l start_end "start end"
+
+
+complete -c timew -f
+
+complete -c timew -l version -d 'Print a short version string and exit'
+
+set -l commands_with_description "
+cancel\t'Cancel time tracking'
+diagnostics\t'Show diagnostic information'
+extensions\t'List available extensions'
+show\t 'Display configuration'
+undo\t'Revert Timewarrior commands'
+annotate\t'Add an annotation to intervals'
+config\t'Get and set Timewarrior configuration'
+continue\t'Resume tracking of existing interval'
+day\t'Display chart report'
+delete\t'Delete intervals'
+export\t'Export tracked time in JSON'
+gaps\t'Display time tracking gaps'
+get\t'Display DOM values'
+help\t'Display help'
+week\t'Display chart report'
+join\t'Join intervals'
+lengthen\t'Lengthen intervals'
+modify\t'Change start or end date of an interval'
+month\t'Display chart report'
+move\t'Change interval start-time'
+shorten\t'Shorten intervals'
+split\t'Split intervals'
+start\t'Start time tracking'
+stop\t'Stop time tracking'
+summary\t'Display a time-tracking summary'
+tag\t'Add tags to intervals'
+tags\t'Display a list of tags'
+track\t'Add intervals to the database'
+untag\t'Remove tags from intervals'
+week\t'Display chart report'
+"
+
+# Base Commands 
+complete -c timew -n "not __fish_seen_subcommand_from $commands" \
+  -a "$commands_with_description" \
+  -d "Timewarrior command"
+
+
+complete -c timew -n "not __fish_seen_subcommand_from $commands" \
+  -a "$reports" \
+  -d "Report"
+
+
+# Subcomands
+
+complete -c timew -n "__fish_seen_subcommand_from annotate" \
+  -a "$ids"
+  # @<id> [@<id> ...] <annotation>
+
+complete -c timew -n "__fish_seen_subcommand_from config" \
+  -a ""
+#[<name> [<value> | '']]
+
+complete -c timew -n "__fish_seen_subcommand_from continue" \
+  -a "$ids"
+#[@<id>] [<date>|<interval>]
+
+complete -c timew -n "__fish_seen_subcommand_from day" \
+  -a "$tags"
+#[<interval>] [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from delete" \
+  -a "$ids"
+#@<id> [@<id> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from export" \
+  -a "$tags"
+#[<interval>] [<tag> ...]
+#
+complete -c timew -n "__fish_seen_subcommand_from gaps" \
+  -a "$tags"
+# [<interval>] [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from get" \
+  -a ""
+# <DOM> [<DOM> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from join" \
+  -a "$ids"
+# @<id> @<id>
+
+complete -c timew -n "__fish_seen_subcommand_from lengthen" \
+  -a "$ids"
+# @<id> [@<id> ...] <duration>
+
+complete -c timew -n "__fish_seen_subcommand_from modify && not __fish_seen_subcommand_from $start_end" \
+  -a "start end"
+# (start|end) @<id> <date>
+
+complete -c timew -n "__fish_seen_subcommand_from modify && __fish_seen_subcommand_from $start_end" \
+  -a "$ids"
+# (start|end) @<id> <date>
+
+
+complete -c timew -n "__fish_seen_subcommand_from month" \
+  -a "$tags"
+# [<interval>] [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from move" \
+  -a "$ids"
+# @<id> <date>
+
+complete -c timew -n "__fish_seen_subcommand_from $reports" \
+  -a "$tags $interval"
+# <report> [<interval>] [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from shorten" \
+  -a "$ids"
+# @<id> [@<id> ...] <duration>
+
+complete -c timew -n "__fish_seen_subcommand_from split" \
+  -a "$ids"
+# @<id> [@<id> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from start && not __fish_seen_subcommand_from modify" \
+  -a "$tags $dates"
+# [<date>] [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from stop && not __fish_seen_subcommand_from modify" \
+  -a "$tags"
+# [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from summary" \
+  -a "$tags $intervals"
+# [<interval>] [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from tag" \
+  -a "$ids $tags"
+# @<id> [@<id> ...] <tag> [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from tags" \
+  -a "$tags $intervals"
+# [<interval>] [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from track" \
+  -a "$tags $intervals"
+# <interval> [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from untag" \
+  -a "$ids $tags"
+# @<id> [@<id> ...] <tag> [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from week" \
+  -a "$tags $intervals"
+# [<interval>] [<tag> ...]
+
+complete -c timew -n "__fish_seen_subcommand_from help" \
+  -a "$commands dates dom durations hints ranges" \
+  -d "Show help"
+
+ 
+

completion/timew.zsh

@@ -0,0 +1,120 @@
+#compdef _timew timew
+
+# zsh completion for timewarrior 1.7.1
+# timewarrior_zsh_completion v0.1.0
+
+_timew() {
+    local ret=1
+
+    if [ -d ${HOME}/.local/share/timewarrior/data ]; then
+        data_dir="${HOME}/.local/share/timewarrior/data"
+    fi
+
+    if [ -d ${HOME}/.timewarrior/data ]; then
+        data_dir="${HOME}/.timewarrior/data"
+    fi
+
+    if (( !${+data_dir} )); then
+        echo "\nCould not find data directory"
+        return $ret
+    fi
+
+    _arguments -C \
+        '1:command:->commands' \
+        '*:ids_tags_hints:->ids_tags_hints' && ret=0
+
+    case "$state" in
+        commands)
+            _describe 'commands' _commands
+            ;;
+        ids_tags_hints)
+            local arr
+
+            arr=()
+
+            # collect all tag data
+            vals=$(sed '1,1d' $data_dir/tags.data | \
+                sed '$d' | \
+                sed -E "s;^[[:space:]]+\"([[:space:][:alnum:]\._-]+)\":.*$;\1;g")
+
+            # add all of the tags to the output array
+            for i in ${(f)vals}; do arr+=$i; done
+
+            # append the predefined hints to the end
+            arr+=( "${_hints[@]} ")
+
+
+            vals=$(cat ${data_dir}/*-*.data | tail -n 9 | sed -E "s/inc .+# //g")
+
+            typeset -i count
+            count=$(echo $vals | wc -l)
+
+            for i in ${(f)vals};
+            do
+                arr+="@${count}:${i}"
+                ((count--))
+            done
+
+            _describe 'hints_tags_ids' arr
+            ;;
+    esac
+}
+
+_hints=(
+    "\:adjust:Automatically correct overlaps"
+    "\:blank:Leaves tracked time out of a report"
+    "\:color:Force color on, even if not connected to a TTY"
+    "\:day:The 24 hours of the current day"
+    "\:debug:Runs in debug mode, shows many runtime details"
+    "\:fill:Expand time to fill surrounding available gap"
+    "\:ids:Displays interval ID numbers in the summary report"
+    "\:lastmonth:Last month"
+    "\:lastquarter:Last quarter"
+    "\:lastweek:Last week"
+    "\:lastyear:Last year"
+    "\:month:This month"
+    "\:nocolor:Force color off, even if connected to a TTY"
+    "\:quarter:This quarter"
+    "\:quiet:Turns off all feedback. For automation"
+    "\:week:This week"
+    "\:year:This year"
+    "\:yes:Overrides confirmation by answering \'yes\' to the questions"
+    "\:yesterday:The 24 hours of the previous day"
+)
+
+_commands=(
+    'annotate:add an annotation to intervals'
+    'cancel:cancel time tracking'
+    'config:get and set Timewarrior configuration'
+    'continue:resume tracking of existing interval'
+    'day:Summarize the tracked and untracked time over the day'
+    'day:shows a chart depicting a single day (today by default)'
+    'delete:delete intervals'
+    'diagnostics:show diagnostic information'
+    'export:export tracked time in JSON'
+    'extensions:list available extensions'
+    'fill:adjust intervals to fill in surrounding gaps'
+    'gaps:display time tracking gaps'
+    'get:display DOM values'
+    'help:display help'
+    'join:join intervals'
+    'lengthen:lengthen intervals'
+    'modify:change start or end date of an interval'
+    'month:Summarize the tracked and untracked time over a month'
+    'month:shows a chart depicting a single month (current month by default)'
+    'move:change interval start-time'
+    'report:run an extension report'
+    'resize:set interval duration'
+    'revert:revert Timewarrior commands'
+    'shorten:shorten intervals'
+    'show:display configuration'
+    'split:split intervals'
+    'start:start time tracking'
+    'stop:stop time tracking'
+    'summary:display a time-tracking summary'
+    'tag:add tags to intervals'
+    'tags:display a list of tags'
+    'track:add intervals to the database'
+    'untag:remove tags from intervals'
+    'week:shows a chart depicting a single week (current week by default)'
+)

doc/CMakeLists.txt

@@ -1,51 +1,16 @@
-cmake_minimum_required (VERSION 2.8)
+cmake_minimum_required (VERSION 3.10)
 
 message ("-- Configuring documentation")
 
 add_subdirectory (holidays)
 add_subdirectory (themes)
 
-configure_file (man1/timew.1.in man1/timew.1)
-configure_file (man1/timew-annotate.1.in man1/timew-annotate.1)
-configure_file (man1/timew-cancel.1.in man1/timew-cancel.1)
-configure_file (man1/timew-chart.1.in man1/timew-chart.1)
-configure_file (man1/timew-config.1.in man1/timew-config.1)
-configure_file (man1/timew-continue.1.in man1/timew-continue.1)
-configure_file (man1/timew-day.1.in man1/timew-day.1)
-configure_file (man1/timew-delete.1.in man1/timew-delete.1)
-configure_file (man1/timew-diagnostics.1.in man1/timew-diagnostics.1)
-configure_file (man1/timew-export.1.in man1/timew-export.1)
-configure_file (man1/timew-extensions.1.in man1/timew-extensions.1)
-configure_file (man1/timew-fill.1.in man1/timew-fill.1)
-configure_file (man1/timew-gaps.1.in man1/timew-gaps.1)
-configure_file (man1/timew-get.1.in man1/timew-get.1)
-configure_file (man1/timew-help.1.in man1/timew-help.1)
-configure_file (man1/timew-join.1.in man1/timew-join.1)
-configure_file (man1/timew-lengthen.1.in man1/timew-lengthen.1)
-configure_file (man1/timew-modify.1.in man1/timew-modify.1)
-configure_file (man1/timew-month.1.in man1/timew-month.1)
-configure_file (man1/timew-move.1.in man1/timew-move.1)
-configure_file (man1/timew-report.1.in man1/timew-report.1)
-configure_file (man1/timew-resize.1.in man1/timew-resize.1)
-configure_file (man1/timew-shorten.1.in man1/timew-shorten.1)
-configure_file (man1/timew-show.1.in man1/timew-show.1)
-configure_file (man1/timew-split.1.in man1/timew-split.1)
-configure_file (man1/timew-start.1.in man1/timew-start.1)
-configure_file (man1/timew-stop.1.in man1/timew-stop.1)
-configure_file (man1/timew-summary.1.in man1/timew-summary.1)
-configure_file (man1/timew-tag.1.in man1/timew-tag.1)
-configure_file (man1/timew-tags.1.in man1/timew-tags.1)
-configure_file (man1/timew-track.1.in man1/timew-track.1)
-configure_file (man1/timew-undo.1.in man1/timew-undo.1)
-configure_file (man1/timew-untag.1.in man1/timew-untag.1)
-configure_file (man1/timew-week.1.in man1/timew-week.1)
+if (ASCIIDOCTOR_FOUND)
+  set (ASCIIDOCTOR_OPTIONS "--attribute=manmanual=User Manuals"
+                           "--attribute=mansource=timew ${PROJECT_VERSION}")
+endif (ASCIIDOCTOR_FOUND)
 
-configure_file (man7/timew-config.7.in man7/timew-config.7)
-configure_file (man7/timew-dates.7.in man7/timew-dates.7)
-configure_file (man7/timew-dom.7.in man7/timew-dom.7)
-configure_file (man7/timew-durations.7.in man7/timew-durations.7)
-configure_file (man7/timew-hints.7.in man7/timew-hints.7)
-configure_file (man7/timew-ranges.7.in man7/timew-ranges.7)
+add_subdirectory (man1)
+add_subdirectory (man7)
 
-install (DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/man1/ DESTINATION ${TIMEW_MAN1DIR} FILES_MATCHING PATTERN "*.1")
-install (DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/man7/ DESTINATION ${TIMEW_MAN7DIR} FILES_MATCHING PATTERN "*.7")
+add_custom_target (doc ALL DEPENDS man1 man7)

doc/holidays/CMakeLists.txt

@@ -1,7 +1,7 @@
-cmake_minimum_required (VERSION 2.8)
+cmake_minimum_required (VERSION 3.10)
 
 message ("-- Configuring holiday documentation")
 
-install (FILES README         DESTINATION ${TIMEW_DOCDIR}/doc/holidays)
-install (FILES holidays.en-US DESTINATION ${TIMEW_DOCDIR}/doc/holidays)
-install (FILES refresh        DESTINATION ${TIMEW_DOCDIR}/doc/holidays)
+install (FILES README         DESTINATION ${TIMEW_DOCDIR}/holidays)
+install (FILES holidays.en-US DESTINATION ${TIMEW_DOCDIR}/holidays)
+install (FILES refresh        DESTINATION ${TIMEW_DOCDIR}/holidays)

doc/holidays/README

@@ -1,27 +1,35 @@
 # Timewarrior Holiday Files
 
-The holiday files were created by the `refresh` script using data from https://holidata.net.
-The holiday files can be updated using the command:
+The holiday files were created by the `refresh` script using data from [holidata.net](https://holidata.net).
+They can be updated using the following command:
 
-    $ ./refresh
+```shell
+$ ./refresh
+```
 
 This updates all present holiday files with holiday data for the current and the following year (default).
 
 If you need another locale (for example `sv-SE`), do this:
 
-    $ ./refresh --locale sv-SE
+```shell
+$ ./refresh --locale sv-SE
+```
 
 This creates a file `holidays.sv-SE` containing holiday data for the current and following year.
-The id for the locale is composed from the [ISO 639-1 language code](https://en.wikipedia.org/wiki/ISO_639-1) and the [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
+The id for the locale is composed of the [ISO 639-1 language code](https://en.wikipedia.org/wiki/ISO_639-1) and the [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
 
 If you need a specific locale region, do this:
 
-    $ ./refresh --locale de-CH --region BE
+```shell
+$ ./refresh --locale de-CH --region BE
+```
 
 For regions use the corresponding [ISO 3166-2 code for principal subdivisions](https://en.wikipedia.org/wiki/ISO_3166-2).
 
 To specify a set of years to update, do this:
 
-    $ ./refresh --locale en-US --year 2018 2019 2020
+```shell
+$ ./refresh --locale en-US --year 2020 2021 2022
+```
 
-If the locale is not yet supported by holidata.net, or there is no data available for the requested year, you will see an error.
+If the locale is not yet supported by [holidata.net](https://holidata.net), or there is no data available for the requested year, you will see an error.

doc/holidays/holidays.en-US

@@ -1,30 +1,31 @@
 # Holiday data provided by holidata.net
-#   Generated 2018-01-13T00:44:23
+#   Generated 2021-05-28T12:07:28
 
 define holidays:
   en-US:
-    2017_01_01 = New Year's Day
-    2017_01_02 = New Year's Day (observed)
-    2017_01_16 = Birthday of Martin Luther King, Jr.
-    2017_02_20 = Washington's Birthday
-    2017_04_17 = Patriots' Day
-    2017_05_29 = Memorial Day
-    2017_07_04 = Independence Day
-    2017_09_04 = Labor Day
-    2017_10_09 = Columbus Day
-    2017_11_11 = Veterans Day
-    2017_11_23 = Thanksgiving Day
-    2017_12_25 = Christmas Day
+    2020_01_01 = New Year's Day
+    2020_01_20 = Birthday of Martin Luther King, Jr.
+    2020_02_17 = Washington's Birthday
+    2020_04_20 = Patriots' Day
+    2020_05_25 = Memorial Day
+    2020_07_04 = Independence Day
+    2020_09_07 = Labor Day
+    2020_10_12 = Columbus Day
+    2020_11_11 = Veterans Day
+    2020_11_26 = Thanksgiving Day
+    2020_11_27 = Day after Thanksgiving
+    2020_12_24 = Christmas Eve
+    2020_12_25 = Christmas Day
 
-    2018_01_01 = New Year's Day
-    2018_01_15 = Birthday of Martin Luther King, Jr.
-    2018_02_19 = Washington's Birthday
-    2018_04_16 = Patriots' Day
-    2018_05_28 = Memorial Day
-    2018_07_04 = Independence Day
-    2018_09_03 = Labor Day
-    2018_10_08 = Columbus Day
-    2018_11_11 = Veterans Day
-    2018_11_22 = Thanksgiving Day
-    2018_12_25 = Christmas Day
+    2021_01_01 = New Year's Day
+    2021_01_18 = Birthday of Martin Luther King, Jr.
+    2021_02_15 = Washington's Birthday
+    2021_04_19 = Patriots' Day
+    2021_05_31 = Memorial Day
+    2021_07_04 = Independence Day
+    2021_09_06 = Labor Day
+    2021_10_11 = Columbus Day
+    2021_11_11 = Veterans Day
+    2021_11_25 = Thanksgiving Day
+    2021_12_25 = Christmas Day
 

doc/holidays/refresh

@@ -2,7 +2,7 @@
 
 ###############################################################################
 #
-# Copyright 2016, 2018 - 2020, Thomas Lauf, Paul Beckingham, Federico Hernandez.
+# Copyright 2016, 2018 - 2022, Gothenburg Bit Factory
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -26,96 +26,119 @@
 #
 ###############################################################################
 
+import argparse
 import datetime
 import json
 import os
 import re
+from textwrap import dedent
 from urllib.error import HTTPError
 from urllib.request import urlopen
 
-import argparse
+
+def gather_locale_files(path):
+    """Enumerate all holiday files in the current directory."""
+
+    locale_file_map = {}
+    re_holiday_file = re.compile(r"/holidays.([a-z]{2}-[A-Z]{2})$")
+
+    for file in enumerate(path):
+        result = re_holiday_file.search(file)
+        if result:
+            # Extract the locale name.
+            locale_file_map[result.group(1)] = file
+
+    return locale_file_map
 
 
 def enumerate(path):
     if not os.path.exists(path):
-        raise Exception("Directory '{}' does not exist".format(path))
+        raise Exception(f"Directory '{path}' does not exist")
 
     found = []
+
     for path, dirs, files in os.walk(path, topdown=True, onerror=None, followlinks=False):
         found.extend([os.path.join(path, x) for x in files])
+
     return found
 
 
-def holidata(locale, year):
-    return "https://holidata.net/{}/{}.json".format(locale, year)
+def create_locale_files(path, locales):
+    locale_file_map = {}
+
+    for locale in locales:
+        locale_file_map[locale] = os.path.join(path, f"holidays.{locale}")
+
+    return locale_file_map
 
 
-def update_locales(locales, regions, years):
+def update_locale_files(locales, regions, years):
     now = datetime.datetime.now()
 
     if not years:
         years = [now.year, now.year + 1]
 
-    for locale in locales:
-        with open("holidays.{}".format(locale), "w") as fh:
-            fh.write("# Holiday data provided by holidata.net\n")
-            fh.write("#   Generated {:%Y-%m-%dT%H:%M:%S}\n\n".format(now))
-            fh.write("define holidays:\n")
-            fh.write("  {}:\n".format(locale))
+    for locale, file in locales.items():
+        with open(file, "w") as fh:
+            fh.write(dedent(f"""\
+            # Holiday data provided by holidata.net
+            #   Generated {now:%Y-%m-%dT%H:%M:%S}
+            
+            define holidays:
+              {locale}:
+            """))
 
             for year in years:
-                holidays = dict()
-                url = holidata(locale, year)
-                print(url)
                 try:
-                    lines = urlopen(url).read().decode("utf-8")
-
-                    for line in lines.split('\n'):
-                        if line:
-                            j = json.loads(line)
-                            if not j['region'] or not regions or j['region'] in regions:
-                                day = j['date'].replace("-", "_")
-                                desc = j['description']
-                                holidays[day] = desc
+                    holidays = get_holidata(locale, regions, year)
 
                     for date, desc in holidays.items():
-                        fh.write("    {} = {}\n".format(date, desc))
+                        fh.write(f"    {date} = {desc}\n")
 
-                    fh.write('\n')
+                    fh.write("\n")
 
                 except HTTPError as e:
                     if e.code == 404:
-                        print("holidata.net does not have data for {}, for {}.".format(locale, year))
+                        print(f"holidata.net does not have data for {locale}, for {year}.")
                     else:
                         print(e.code, e.read())
 
 
-def main(args):
-    if args.locale:
-        update_locales(args.locale, args.region, args.year)
-    else:
-        # Enumerate all holiday files in the current directory.
-        locales = []
-        re_holiday_file = re.compile(r"/holidays.([a-z]{2}-[A-Z]{2}$)")
-        for file in enumerate('.'):
-            result = re_holiday_file.search(file)
-            if result:
-                # Extract the locale name.
-                locales.append(result.group(1))
+def get_holidata(locale, regions, year):
+    url = f"https://holidata.net/{locale}/{year}.json"
+    print(url)
+    holidays = dict()
+    lines = urlopen(url).read().decode("utf-8")
 
-        update_locales(locales, args.region, args.year)
+    for line in lines.split("\n"):
+        if line:
+            j = json.loads(line)
+
+            if not j["region"] or not regions or j["region"] in regions:
+                day = j["date"].replace("-", "_")
+                desc = j["description"]
+                holidays[day] = desc
+
+    return holidays
+
+
+def main(args):
+    locale_files = create_locale_files(args.path, args.locale) if args.locale else gather_locale_files(args.path)
+    update_locale_files(locale_files, args.region, args.year)
 
 
 if __name__ == "__main__":
     usage = """See https://holidata.net for details of supported locales and regions."""
     parser = argparse.ArgumentParser(
-        description="Update holiday data files. Simply run 'refresh' to update all of them.")
-    parser.add_argument('--locale', nargs='+', help='Specific locale to update.')
-    parser.add_argument('--region', nargs='+', help='Specific locale region to update.', default=[])
-    parser.add_argument('--year', nargs='+', help='Specific year to fetch.', type=int, default=[])
-    args = parser.parse_args()
+        description="Update holiday data files. Simply run 'refresh' to update all of them.",
+        usage="refresh [-h] [path] [--locale LOCALE [LOCALE ...]] [--region REGION [REGION ...]] [--year YEAR [YEAR ...]]"
+    )
+    parser.add_argument("--locale", nargs="+", help="specify locale to update")
+    parser.add_argument("--region", nargs="+", help="specify locale region to update", default=[])
+    parser.add_argument("--year", nargs="+", help="specify year to fetch (defaults to current and next year)", type=int, default=[])
+    parser.add_argument("path", nargs="?", help="base path to search for locales (defaults to current directory)", default=".")
 
     try:
-        main(args)
+        main(parser.parse_args())
     except Exception as msg:
-        print('Error:', msg)
+        print("Error:", msg)

doc/man1/.gitignore

@@ -1 +1,4 @@
 *.[0-9]
+!timew-day.1
+!timew-month.1
+!timew-week.1

doc/man1/CMakeLists.txt

@@ -0,0 +1,24 @@
+cmake_minimum_required (VERSION 3.10)
+
+if (ASCIIDOCTOR_FOUND)
+  file (GLOB DOC_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/*.1.adoc")
+  set (DOC_FILES)
+
+  foreach (SRC IN LISTS DOC_SOURCES)
+    string (REPLACE ".adoc" "" OUTPUT_FILE_NAME "${SRC}")
+    string (REPLACE "${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_BINARY_DIR}" OUTPUT_FILE_NAME "${OUTPUT_FILE_NAME}")
+
+    add_custom_command (OUTPUT "${OUTPUT_FILE_NAME}"
+                        COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage ${ASCIIDOCTOR_OPTIONS} "${SRC}" -o "${OUTPUT_FILE_NAME}"
+                        DEPENDS "${SRC}")
+
+    list (APPEND DOC_FILES "${OUTPUT_FILE_NAME}")
+  endforeach (SRC)
+
+  add_custom_target (man1 DEPENDS ${DOC_FILES})
+else (ASCIIDOCTOR_FOUND)
+  file (GLOB MAN_PAGES "${CMAKE_CURRENT_SOURCE_DIR}/*.1")
+  set (DOC_FILES ${MAN_PAGES})
+endif (ASCIIDOCTOR_FOUND)
+
+install (FILES ${DOC_FILES} DESTINATION ${TIMEW_MAN1DIR})

doc/man1/timew-annotate.1.adoc

@@ -0,0 +1,80 @@
+= timew-annotate(1)
+
+== NAME
+timew-annotate - add an annotation to intervals
+
+== SYNOPSIS
+[verse]
+*timew annotate* [_<id>_**...**] _<annotation>_
+
+== DESCRIPTION
+The 'annotate' command is used to add an annotation to an interval.
+
+See the 'summary' command on how to display the _<id>_ and _<annotation>_ of an interval.
+
+== EXAMPLES
+*Annotate a single interval*::
++
+Call the command with an _id_ and the _annotation_:
++
+[source]
+----
+$ timew annotate @2 'Lorem ipsum'
+Annotated @2 with "Lorem ipsum"
+----
+
+*Remove an annotation*::
++
+Annotating an interval with an empty string removes the annotation:
++
+[source]
+----
+$ timew annotate @1 ''
+Removed annotation from @1
+----
+
+*Annotate multiple intervals*::
++
+You can annotate multiple intervals with the same _annotation_ at once, by specifying their ids:
++
+[source]
+----
+$ timew annotate @2 @10 @23 'Lorem ipsum'
+Annotated @1 with "Lorem ipsum"
+Annotated @10 with "Lorem ipsum"
+Annotated @23 with "Lorem ipsum"
+----
+
+*Annotate the current open interval*::
++
+If there is active time tracking, you can omit the ID when you want to add an annotation to the current open interval:
++
+[source]
+----
+$ timew start foo
+...
+$ timew annotate bar
+Annotated @1 with "bar"
+----
++
+This results in the current interval having tag 'foo' and annotation 'bar'.
+
+== pass:[BUGS & LIMITATIONS]
+The summary command truncates annotations longer than 15 characters.
+To display longer annotations, one can use the 'export' command, or a custom report.
+
+Currently, the annotation command picks the last token from the command line and uses it as annotation.
+I.e. using no quotes in an annotation command like
+
+[source]
+----
+$ timew annotate @1 lorem ipsum
+----
+
+will result in interval @1 having only 'ipsum' as its annotation.
+Use quotes to avoid this.
+
+== SEE ALSO
+**timew-export**(1),
+**timew-summary**(1),
+**timew-tag**(1)

doc/man1/timew-annotate.1.in

@@ -1,50 +0,0 @@
-.TH timew-annotate 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-annotate \- add an annotation to intervals
-.
-.SH SYNOPSIS
-.B timew annotate
-[
-.I <id>
-.B ...
-]
-.I <annotation>
-.B ...
-.
-.SH DESCRIPTION
-The 'annotate' command is used to add an annotation to an interval.
-Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
-Using the right ID, you can identify an interval to annotate.
-.
-.SH EXAMPLES
-For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
-Then having selected '@2' as the interval you wish to annotate:
-.RS
-$ timew annotate @2 'Lorem ipsum...'
-.RE
-Note that you can annotate multiple intervals with the same annotation:
-.RS
-$ timew annotate @2 @10 @23 'Lorem ipsum dolor sit amet...'
-.RE
-If there is active time tracking, you can omit the ID when you want to add annotations to the current open interval:
-.RS
-$ timew start foo
-.br
-$ timew annotate bar
-.RE
-This results in the current interval having annotations 'foo' and 'bar'.
-.
-.SH BUGS
-Currently the annotation command picks the last token from the command line and uses it as annotation.
-I.e. using no quotes in an annotation command like
-.RS
-$ timew annotate @1 lorem ipsum dolor
-.RE
-will result in interval @1 having only 'dolor' as its annotation.
-.
-.SH "SEE ALSO"
-.BR timew-tag (1)

doc/man1/timew-cancel.1.adoc

@@ -0,0 +1,37 @@
+= timew-cancel(1)
+
+== NAME
+timew-cancel - cancel time tracking
+
+== SYNOPSIS
+[verse]
+*timew cancel*
+
+== DESCRIPTION
+If there is an open interval, it is abandoned.
+
+== EXAMPLES
+
+*Cancel with active time tracking*::
++
+    $ timew start
+    ...
+    $ timew cancel
+    Canceled active time tracking.
+
+This deletes the open interval.
+
+*Cancel with no active time tracking*::
++
+    ...
+    $ timew stop
+    $ timew cancel
+    There is no active time tracking.
+
+Cancel has no effect, only a warning is printed.
+
+== SEE ALSO
+**timew-continue**(1),
+**timew-start**(1),
+**timew-stop**(1),
+**timew-track**(1)

doc/man1/timew-cancel.1.in

@@ -1,45 +0,0 @@
-.TH timew-cancel 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-cancel \- cancel time tracking
-.
-.SH SYNOPSIS
-.B timew cancel
-.
-.SH DESCRIPTION
-If there is an open interval, it is abandoned.
-.
-.SH EXAMPLES
-.TP
-.B Cancel with active time tracking
-.RS
-.br
-$ timew start
-.br
-...
-.br
-$ timew cancel
-.br
-Canceled active time tracking.
-.RE
-.
-This deletes the open interval.
-.TP
-.B Cancel with no active time tracking
-.RS
-.br
-...
-.br
-$ timew stop
-.br
-$ timew cancel
-.br
-There is no active time tracking.
-.RE
-Cancel has no effect, only a warning is printed.
-.
-.SH "SEE ALSO"
-.BR timew-continue (1),
-.BR timew-start (1),
-.BR timew-stop (1),
-.BR timew-track (1)

doc/man1/timew-chart.1.adoc

@@ -1,183 +1,115 @@
-.TH timew-chart 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-chart \- display chart report
-.
-.SH SYNOPSIS
-.B timew day
-[
-.I <range>
-] [
-.I <tag>
-.B ...
-]
-.br
-.B timew month
-[
-.I <range>
-] [
-.I <tag>
-.B ...
-]
-.br
-.B timew week
-[
-.I <range>
-] [
-.I <tag>
-.B ...
-]
-.
-.SH DESCRIPTION
+= timew-chart(1)
+
+== NAME
+timew-chart - display chart report
+
+== SYNOPSIS
+[verse]
+*timew day* [_<range>_] [_<tag>_**...**]
+*timew month* [_<range>_] [_<tag>_**...**]
+*timew week* [_<range>_] [_<tag>_**...**]
+
+== DESCRIPTION
 A chart summarizes the tracked and untracked time with colored blocks drawn on a timeline.
 It accepts date ranges and tags for filtering.
-There are three types:
-.BR day ", " week ", and " month
-with their respective commands.
-The
-.BI reports. <type> .range
-configuration setting overrides the default date range.
+There are three types: *day*, *week*, and *month* with their respective commands.
+The **reports.**__<type>__**.range** configuration setting overrides the default date range.
+One can override the global default date range with the **reports.range** configuration.
 For more details, and precise times, use the 'summary' report.
 
-.TP
-.B month
+*month*::
 The month command shows a chart depicting a single month (current month by default).
-The default date range shown is
-.BR :month .
-.
-.TP
-.B week
+The default date range shown is *:month*.
+
+*week*::
 The week command shows a chart depicting a single week (current week by default).
-The default date range shown is
-.BR :week .
-.
-.TP
-.B day
+The default date range shown is *:week*.
+
+*day*::
 The day command shows a chart depicting a single day (today by default).
-The default date range shown is
-.BR :day .
-.
-.SH CONFIGURATION
-.IR <type> " is one of"
-.BR month ", " week ", " day "."
-.TP
-.BI reports. <type> .cell
-.RS
+The default date range shown is *:day*.
+
+== CONFIGURATION
+_<type>_ is one of **month**, **week**, **day**.
+
+**reports.**__<type>__**.cell**::
 Determines how many minutes are represented by a single character cell, for the charts.
 The value must be greater than '0'.
 A value of '15' means that an hour is represented by 60/15, or 4 character cells.
 Suitable values are the divisors of 60 (30, 20, 15, 12, ...).
-.br
 Default value is '15'.
-.RE
-.TP
-.BI reports. <type> .day
-.RS
+
+**reports.**__<type>__**.day**::
 Determines whether the current day of the month is shown at left margin.
-.br
 Default value is 'yes'.
-.RE
-.TP
-.BI reports. <type> .holidays
-.RS
+
+**reports.**__<type>__**.holidays**::
 Determines whether relevant holidays are shown beneath the report.
-.br
 Default value is 'yes'.
-.RE
-.TP
-.BI reports. <type> .hours
-.RS
-Determines how the <type> report shows all the hours in a day ('all'), or is limited to only hours where data is tracked ('auto').
-.br
+
+**reports.**__<type>__**.hours**::
+Determines how the <type> report shows all the hours in a day ('all'), or is limited to only hours when data is tracked ('auto').
 Default value is 'all'.
-.RE
-.TP
-.BI reports. <type> .lines
-.RS
+
+**reports.**__<type>__**.lines**::
 Determines how many lines are used to render each day on the <type> report.
-.br
 Default value is '1'.
-.RE
-.TP
-.BI reports. <type> .month
-.RS
+
+**reports.**__<type>__**.month**::
 Determines whether the current month is shown at left margin.
-.br
 Default value is 'yes'.
-.RE
-.TP
-.BI reports. <type> .range
-.RS
+
+**reports.**__<type>__**.range**::
 For reports that show a range of data, this setting will override the default value.
 The value should be a range hint, see
-.BR timew-hints (7).
-.RE
-.TP
-.BI reports. <type> .spacing
-.RS
+**timew-hints**(7).
+
+**reports.**__<type>__**.spacing**::
 Specifies how many spaces are inserted between the hours in the <type> report exclusions.
 A value of '0' yields a more compact report.
-.br
 Default value is '1'.
-.RE
-.TP
-.BI reports. <type> .axis
-.RS
-The value 'internal' puts the hour markers (time line at the top) inside the exclusion blocks, 'external' puts the hour markers in a separate line; additional values might be defined in the future.
-.br
+
+**reports.**__<type>__**.axis**::
+The value 'internal' puts the hour markers (timeline at the top) inside the exclusion blocks, 'external' puts the hour markers in a separate line; additional values might be defined in the future.
 Default is 'internal' for the day report and 'external' for other reports.
-.br
-.RE
-.TP
-.BI reports. <type> .summary
-.RS
+
+**reports.**__<type>__**.summary**::
 Determines whether the hours summary is shown.
-.br
 Default value is 'on'.
-.RE
-.TP
-.BI reports. <type> .totals
-.RS
+
+**reports.**__<type>__**.totals**::
 Determines whether the time totals are shown for each day on the report.
-.br
 Default value is 'on'.
-.RE
-.TP
-.BI reports. <type> .week
-.RS
+
+**reports.**__<type>__**.week**::
 Determines whether the current week number is shown at left margin.
-.br
 Default value is 'yes'.
-.RE
-.TP
-.BI reports. <type> .weekday
-.RS
+
+**reports.**__<type>__**.weekday**::
 Determines whether the current weekday is shown at left margin.
-.br
 Default value is 'yes'.
-.RE
-.
-.SH HINTS
-.TP
-.B :blank
+
+**tags.**__<tag>__**.color**::
+Assigns a specific foreground and background color to a tag, instead of the default color palette determined by your current theme.
+Examples of valid colors include 'white', 'gray8', 'black on yellow', and 'rgb345'.
+
+== HINTS
+
+*:blank*::
 The ':blank' hint causes only the excluded time to be shown, with no tracked time.
 This can be used to see the exclusions.
-.TP
-.B :ids
+
+*:ids*::
 The ':ids' hint causes the intervals to be displayed with their ids
-.
-.SH EXAMPLES
-Charts accept date ranges and tags for filtering, or shortcut hints:
-.RS
-$ timew month 1st - today
-.br
-$ timew week FOO BAR
-.br
-$ timew day :week
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-day (1),
-.BR timew-month (1),
-.BR timew-summary (1),
-.BR timew-week (1)
+
+== EXAMPLES
+Charts accept date ranges and/or tags, or ids for filtering:
+
+    $ timew month 1st - today
+    $ timew week FOO BAR
+    $ timew day @3 @4
+
+See **timew-ranges**(7) and **timew-hints**(7) on the different ways to provide date ranges.
+
+== SEE ALSO
+**timew-summary**(1),

doc/man1/timew-config.1.adoc

@@ -0,0 +1,37 @@
+= timew-config(1)
+
+== NAME
+timew-config - get and set Timewarrior configuration
+
+== SYNOPSIS
+[verse]
+*timew config* [_<name>_ {_<value>_|*''*}]
+
+== DESCRIPTION
+Allows setting and removing configuration values, as an alternative to directly editing your _timewarrior.cfg_ file.
+
+== EXAMPLES
+For example:
+
+    $ timew config verbose yes
+    $ timew config verbose ''
+    $ timew config verbose
+
+The first command sets 'verbose' to 'yes'.
+The second sets it to a blank value which overrides the default value.
+The third example deletes the 'verbose' setting.
+
+When modifying configuration in this way, interactive confirmation will be sought.
+To override this confirmation, use the ':yes' hint, which means you intend to answer 'yes' to the confirmation questions:
+
+    $ timew config verbose '' :yes
+
+If no arguments are provided, all configuration settings are shown:
+
+    $ timew config
+    verbose = yes
+    ...
+
+== SEE ALSO
+**timew-hints**(7),
+**timew-show**(1)

doc/man1/timew-config.1.in

@@ -1,49 +0,0 @@
-.TH timew-config 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-config \- get and set Timewarrior configuration
-.
-.SH SYNOPSIS
-.B timew config
-[
-.I <name>
-{
-.I <value>
-|
-.B ''
-}
-]
-.
-.SH DESCRIPTION
-Allows setting and removing configuration values, as an alternative to directly editing your ~/.timewarrior/timewarrior.cfg file.
-.
-.SH EXAMPLES
-For example:
-.RS
-$ timew config verbose yes
-.br
-$ timew config verbose ''
-.br
-$ timew config verbose
-.RE
-The first command sets 'verbose' to 'yes'.
-The second sets it to a blank value which overrides the default value.
-The third example deletes the 'verbose' setting.
-.
-When modifying configuration in this way, interactive confirmation will be sought.
-To override this confirmation, use the ':yes' hint, which means you intend to answer 'yes' to the confirmation questions:
-.RS
-$ timew config verbose '' :yes
-.RE
-If no arguments are provided, all configuration settings are shown:
-.RS
-$ timew config
-.br
-verbose = yes
-.br
-...
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-hints (1),
-.BR timew-show (1)

doc/man1/timew-continue.1.adoc

@@ -0,0 +1,82 @@
+= timew-continue(1)
+
+== NAME
+timew-continue - resume tracking of existing interval
+
+== SYNOPSIS
+[verse]
+*timew continue* [_<id>_|_<tag>_**...**] [_<datetime>_|_<range>_]
+
+== DESCRIPTION
+The 'continue' command is used to resume tracking specified by a closed interval.
+This command is a convenient way to resume work without re-entering the tags.
+
+The interval to be resumed can be specified either by its id or by a set of tags.
+Specifying multiple ids or both ids and tags will result in an error.
+
+When given a set of tags, the first interval matching it will be taken as a blueprint for the new interval.
+When given neither id nor tags, the first interval in the database is taken.
+
+When no datetime or range given, the new interval is started at the current time.
+
+== EXAMPLES
+Using the 'summary' command and specifying the ':ids' hint shows interval IDs.
+Consider the following intervals:
+
+    $ src/timew summary :ids
+
+    Wk  Date       Day ID Tags             Start      End    Time   Total
+    W23 2020-06-04 Thu @4 BAR           13:00:00 14:00:00 1:00:00
+                       @3 BAR, FOO      14:00:00 15:00:00 1:00:00
+                       @2 BAR, BAZ, FOO 15:00:00 16:00:00 1:00:00
+                       @1 FOO           16:00:00 17:00:00 1:00:00 4:00:00
+
+                                                                  4:00:00
+
+Simple continue::
++
+    $ timew continue
+
+The 'continue' command creates a new open interval, starting now, with tag 'FOO'
+
+Continue an interval via id::
++
+    $ timew continue @3
+
+The 'continue' command creates a new open interval, starting now, with tags 'BAR' and 'FOO'.
+
+Continue an interval via tag set::
++
+    $ timew continue FOO BAR
+
+The 'continue' command creates a new open interval, starting now, with tags 'FOO', 'BAR', and 'BAZ'.
+
+Note that the first matching interval (here '@2') is taken as a blueprint for the new interval, although '@3' would have been a perfect match for the given tag set.
+The command 'timew continue BAR' would have the same effect.
+This means that there is no way to continue '@4' via a tag set.
+
+Continue an interval at a specific date & time::
++
+    $ timew continue @4 19:00  (1)
+    $ timew continue FOO 19:00 (2)
+
+The 'continue' command creates a new open interval
+
+1. with tag 'BAR' (as specified by '@4') and start time '19:00'.
+2. with tag 'FOO' (as specified by '@1') and start time '19:00'.
+
+Continue an interval with a specific range::
++
+    $ timew continue @4 19:00 - 20:00  (1)
+    $ timew continue FOO 19:00 - 20:00 (2)
+
+The 'continue' command creates a new closed interval
+
+1. with tag 'BAR' (as specified by '@4'), start time '19:00', and end time '20:00'.
+2. with tag 'FOO' (as specified by '@1') and start time '19:00', and end time '20:00'.
+
+== SEE ALSO
+**timew-cancel**(1),
+**timew-start**(1),
+**timew-stop**(1),
+**timew-track**(1)

doc/man1/timew-continue.1.in

@@ -1,38 +0,0 @@
-.TH timew-continue 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-continue \- resume tracking of existing interval
-.
-.SH SYNOPSIS
-.B timew continue
-[
-.I <id>
-] [
-{
-.I <date>
-|
-.I <range>
-}
-]
-.
-.SH DESCRIPTION
-Resumes tracking of closed intervals.
-.
-.SH EXAMPLES
-For example:
-.RS
-$ timew track 9am - 10am tag1 tag2
-.br
-$ timew track 11am - 1pm tag3
-.br
-$ timew continue @2
-.RE
-The 'continue' command creates a new interval, starting now, and using the tags 'tag1' and 'tag2'.
-Using the 'summary' command and specifying the ':ids' hint shows interval IDs.
-This command is a convenient way to resume work without re-entering the tags.
-.
-.SH "SEE ALSO"
-.BR timew-cancel (1),
-.BR timew-start (1),
-.BR timew-stop (1),
-.BR timew-track (1)

doc/man1/timew-day.1

@@ -0,0 +1 @@
+.so man1/timew-chart.1

doc/man1/timew-delete.1.adoc

@@ -0,0 +1,26 @@
+= timew-delete(1)
+
+== NAME
+timew-delete - delete intervals
+
+== SYNOPSIS
+[verse]
+*timew delete* _<id>_**...**
+
+== DESCRIPTION
+Deletes an interval.
+Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
+Using the right ID, you can identify an interval to delete.
+
+== EXAMPLES
+For example, show the IDs:
+
+    $ timew summary :week :ids
+
+Then having selected '@2' as the interval you wish to delete:
+
+    $ timew delete @2
+
+
+== SEE ALSO
+**timew-cancel**(1)

doc/man1/timew-delete.1.in

@@ -1,27 +0,0 @@
-.TH timew-delete 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-delete \- delete intervals
-.
-.SH SYNOPSIS
-.B timew delete
-.I <id>
-.B ...
-.
-.SH DESCRIPTION
-Deletes an interval.
-Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
-Using the right ID, you can identify an interval to delete.
-.
-.SH EXAMPLES
-For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
-Then having selected '@2' as the interval you wish to delete:
-.RS
-$ timew delete @2
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-cancel

doc/man1/timew-diagnostics.1.adoc

@@ -1,14 +1,16 @@
-.TH timew-diagnostics 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-diagnostics \- show diagnostic information
-.
-.SH SYNOPSIS
-.B timew diagnostics
-.
-.SH DESCRIPTION
+= timew-diagnostics(1)
+
+== NAME
+timew-diagnostics - show diagnostic information
+
+== SYNOPSIS
+[verse]
+*timew diagnostics*
+
+== DESCRIPTION
 This command shows details about your version of Timewarrior, your platform, how it was built, compiler features, configuration, file access, extensions and more.
+
 The purpose of this command is to help diagnose configuration problems and provide supplemental information when reporting a problem.
-.
-.SH "SEE ALSO"
-.BR timew-extensions (1)
+
+== SEE ALSO
+**timew-extensions**(1)

doc/man1/timew-export.1.adoc

@@ -0,0 +1,36 @@
+= timew-export(1)
+
+== NAME
+timew-export - export tracked time in JSON
+
+== SYNOPSIS
+[verse]
+*timew export* [ _<id>_**...** | ([_<range>_] [_<tag>_**...**]) ]
+
+== DESCRIPTION
+Exports all the tracked time in JSON format.
+
+Supply either a list of interval IDs (e.g. `@1 @2`), or optional filters (see **timew-ranges**(7) and/or **timew-tags**(1))
+
+== EXAMPLES
+
+*Export all intervals*::
+[source]
+----
+$ timew export
+...
+----
+
+*Export intervals filtered by range and tag*::
+[source]
+----
+$ timew export from 2016-01-01 for 3wks tag1
+...
+----
+
+*Export intervals by their ids*::
+[source]
+----
+$ timew export @1 @3 @7
+...
+----

doc/man1/timew-export.1.in

@@ -1,22 +0,0 @@
-.TH timew-export 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-export \- export tracked time in JSON
-.
-.SH SYNOPSIS
-.B timew export
-[
-.I <range>
-] [
-.I <tag> ...
-]
-.
-.SH DESCRIPTION
-Exports all the tracked time in JSON format.
-Supports filtering.
-.
-.SH EXAMPLES
-For example:
-.RS
-$ timew export from 2016-01-01 for 3wks tag1
-.RE

doc/man1/timew-extensions.1.adoc

@@ -0,0 +1,14 @@
+= timew-extensions(1)
+
+== NAME
+timew-extensions - list available extensions
+
+== SYNOPSIS
+[verse]
+*timew extensions*
+
+== DESCRIPTION
+Displays the directory containing the extension programs and a table showing each extension and its status.
+
+== SEE ALSO
+**timew-diagnostics**(1)

doc/man1/timew-extensions.1.in

@@ -1,13 +0,0 @@
-.TH timew-extensions 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-extensions \- list available extensions
-.
-.SH SYNOPSIS
-.B timew extensions
-.
-.SH DESCRIPTION
-Displays the directory containing the extension programs and a table showing each extension and its status.
-.
-.SH "SEE ALSO"
-.BR timew-diagnostics (1)

doc/man1/timew-fill.1.adoc

@@ -1,31 +1,30 @@
-.TH timew-fill 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-fill \- adjust intervals to fill in surrounding gaps
-.
-.SH SYNOPSIS
-.B timew fill
-.I <id>
-.B ...
-.
-.SH DESCRIPTION
+= timew-fill(1)
+
+== NAME
+timew-fill - adjust intervals to fill in surrounding gaps
+
+== SYNOPSIS
+[verse]
+*timew fill* _<id>_**...**
+
+== DESCRIPTION
 The 'fill' command is used to adjust any interval to fill in surrounding gaps.
 Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
 Using the right ID, you can identify an interval to fill.
-.
-.SH EXAMPLES
+
+== EXAMPLES
 For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
+
+    $ timew summary :week :ids
+
 Then having selected '@2' as the interval you wish to fill:
-.RS
-$ timew fill @2
-.RE
+
+    $ timew fill @2
+
 Note that you can fill multiple intervals:
-.RS
-$ timew fill @2 @10 @23
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-hints (1)
+
+    $ timew fill @2 @10 @23
+
+
+== SEE ALSO
+**timew-hints**(7)

doc/man1/timew-gaps.1.adoc

@@ -0,0 +1,23 @@
+= timew-gaps(1)
+
+== NAME
+timew-gaps - display time tracking gaps
+
+== SYNOPSIS
+[verse]
+*timew gaps* [_<range>_] [_<tag>_**...**]
+
+== DESCRIPTION
+Displays a summary of time that is neither tracked nor excluded from tracking.
+
+The 'reports.gaps.range' configuration setting overrides the default date range.
+The ':blank' hint causes only the excluded time to be shown, with no tracked time.
+The default date range shown is ':day'.
+
+== CONFIGURATION
+**reports.gaps.range**::
+For reports that show a range of data, this setting will override the default value.
+The value should be a range hint, see **timew-hints**(7).
+
+== SEE ALSO
+**timew-summary**(1)

doc/man1/timew-gaps.1.in

@@ -1,34 +0,0 @@
-.TH timew-gaps 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-gaps \- display time tracking gaps
-.
-.SH SYNOPSIS
-.B timew gaps
-[
-.I <range>
-] [
-.I <tag>
-.B ...
-]
-.
-.SH DESCRIPTION
-Displays a summary of time that is neither tracked nor excluded from tracking.
-.
-The 'reports.gaps.range' configuration setting overrides the default date range.
-The ':blank' hint causes only the excluded time to be shown, with no tracked time.
-The default date range shown is ':day'.
-.
-The ':blank' hint causes only the excluded time to be shown, with no tracked time.
-.
-.SH CONFIGURATION
-.TP
-.B reports.gaps.range
-.RS
-For reports that show a range of data, this setting will override the default value.
-The value should be a range hint, see
-.BR timew-hints (7).
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-summary (1)

doc/man1/timew-get.1.adoc

@@ -0,0 +1,22 @@
+= timew-get(1)
+
+== NAME
+timew-get - display DOM values
+
+== SYNOPSIS
+[verse]
+*timew get* _<DOM>_**...**
+
+== DESCRIPTION
+Validates the DOM reference, then obtains the value and displays it.
+
+== EXAMPLES
+For example:
+
+    $ timew get dom.active
+    1
+
+It is an error to reference an interval or tag that does not exist.
+
+== SEE ALSO
+**timew-dom**(7)

doc/man1/timew-get.1.in

@@ -1,23 +0,0 @@
-.TH timew-get 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-get \- display DOM values
-.
-.SH SYNOPSIS
-.B timew get
-.I <DOM>
-.B ...
-.
-.SH DESCRIPTION
-Validates the DOM reference, then obtains the value and displays it.
-.
-.SH EXAMPLES
-For example:
-.RS
-$ timew get dom.active
-1
-.RE
-It is an error to reference an interval or tag that does not exist.
-.
-.SH "SEE ALSO"
-.BR timew-DOM

doc/man1/timew-help.1.adoc

@@ -0,0 +1,22 @@
+= timew-help(1)
+
+== NAME
+timew-help - display help
+
+== SYNOPSIS
+[verse]
+*timew help* {_<command>_|*interval*|*hints*|*date*|*duration*}
+
+== DESCRIPTION
+The help command shows detailed descriptions and examples of commands, interval syntax, supported hints, date and duration formats and DOM references.
+
+== EXAMPLES
+For example:
+
+    $ timew help
+    $ timew help start
+    $ timew help hints
+    $ timew help interval
+    $ timew help date
+    $ timew help duration
+    $ timew help dom

doc/man1/timew-help.1.in

@@ -1,39 +0,0 @@
-.TH timew-help 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-help \- display help
-.
-.SH SYNOPSIS
-.B timew help
-{
-.I <command>
-|
-.B interval
-|
-.B hints
-|
-.B date
-|
-.B duration
-}
-.
-.SH DESCRIPTION
-The help command shows detailed descriptions and examples of commands, interval syntax, supported hints, date and duration formats and DOM references.
-.
-.SH EXAMPLES
-For example:
-.RS
-$ timew help
-.br
-$ timew help start
-.br
-$ timew help hints
-.br
-$ timew help interval
-.br
-$ timew help date
-.br
-$ timew help duration
-.br
-$ timew help dom
-.RE

doc/man1/timew-join.1.adoc

@@ -0,0 +1,28 @@
+= timew-join(1)
+
+== NAME
+timew-join - join intervals
+
+== SYNOPSIS
+[verse]
+*timew join* _<id> <id>_
+
+== DESCRIPTION
+Joins two intervals, by using the earlier one of the two start times, and the later one of the two end times, and the combined set of tags.
+Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
+Using the correct IDs, you can identify an intervals to join.
+
+== EXAMPLES
+For example, show the IDs:
+
+    $ timew summary :week :ids
+
+Then having selected '@1' and '@2' as the intervals you wish to join:
+
+    $ timew join @1 @2
+
+== SEE ALSO
+**timew-lengthen**(1),
+**timew-resize**(1),
+**timew-shorten**(1),
+**timew-split**(1)

doc/man1/timew-join.1.in

@@ -1,29 +0,0 @@
-.TH timew-join 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-join \- join intervals
-.
-.SH SYNOPSIS
-.B timew join
-.I <id> <id>
-.
-.SH DESCRIPTION
-Joins two intervals, by using the earlier of the two start times, and the later of the two end times, and the combined set of tags.
-Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
-Using the correct IDs, you can identify an intervals to join.
-.
-.SH EXAMPLES
-For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
-Then having selected '@1' and '@2' as the intervals you wish to join:
-.RS
-$ timew join @1 @2
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-lengthen (1),
-.BR timew-resize (1),
-.BR timew-shorten (1),
-.BR timew-split (1)

doc/man1/timew-lengthen.1.adoc

@@ -0,0 +1,34 @@
+= timew-lengthen(1)
+
+== NAME
+timew-lengthen - lengthen intervals
+
+== SYNOPSIS
+[verse]
+*timew lengthen* _<id>_**...** _<duration>_
+
+== DESCRIPTION
+The 'lengthen' command is used to defer the end date of a closed interval.
+Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
+Using the right ID, you can identify an interval to lengthen.
+
+== EXAMPLES
+For example, show the IDs:
+
+    $ timew summary :week :ids
+
+Then having selected '@2' as the interval you wish to lengthen:
+
+    $ timew lengthen @2 10mins
+
+Note that you can lengthen multiple intervals,:
+
+    $ timew lengthen @2 @10 @23 1hour
+
+== SEE ALSO
+**timew-modify**(1),
+**timew-resize**(1),
+**timew-shorten**(1),
+**timew-summary**(1),
+**timew-tag**(1),
+**timew-untag**(1)

doc/man1/timew-lengthen.1.in

@@ -1,37 +0,0 @@
-.TH timew-lengthen 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-lengthen \- lengthen intervals
-.
-.SH SYNOPSIS
-.B timew lengthen
-.I <id>
-.B ...
-.I <duration>
-.
-.SH DESCRIPTION
-The 'lengthen' command is used to defer the end date of a closed interval.
-Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
-Using the right ID, you can identify an interval to lengthen.
-.
-.SH EXAMPLES
-For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
-Then having selected '@2' as the interval you wish to lengthen:
-.RS
-$ timew lengthen @2 10mins
-.RE
-Note that you can lengthen multiple intervals,:
-.RS
-$ timew lengthen @2 @10 @23 1hour
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-modify (1),
-.BR timew-resize (1),
-.BR timew-shorten (1),
-.BR timew-summary (1),
-.BR timew-tag (1),
-.BR timew-untag (1)

doc/man1/timew-modify.1.adoc

@@ -0,0 +1,51 @@
+= timew-modify(1)
+
+== NAME
+timew-modify - change the range of an interval
+
+== SYNOPSIS
+[verse]
+*timew modify* (*start*|*end*) _<id>_ _<date>_
+*timew modify* range _<id>_ _<range>_
+
+== DESCRIPTION
+The 'modify' command is used to change range of an interval.
+
+Using the 'start' or 'end' subcommand, one can either specify a new start or end date respectively, or with the 'range' subcommand, change the complete range.
+The interval to be modified is specified via its id.
+
+If the resulting interval overlaps with an existing interval, the command will return an error.
+One can add the ':adjust' hint to force an overwrite in this case.
+
+See **timew-summary**(1) on how to retrieve the interval id.
+
+== EXAMPLES
+*Modify the start date of an interval*::
++
+    $ timew modify start @3 2020-12-28T17:00
++
+This sets the start of interval '@3' to '17:00' of date '2020-12-28'.
+If this datetime is after the end of the interval, the command will return an error.
+
+*Modify the end date of an interval*::
++
+If the interval to be modified has the same date as today, it can be omitted:
++
+    $ timew modify end @3 18:00
++
+Similar to when modifying the interval start, the end datetime has to be after the start datetime.
+
+*Modify the range of an interval*::
++
+Instead of modifying start and end separately, those can be combined into a single call of the 'range' subcommand:
++
+    $ timew modify range @3 2020-12-28T17:00 - 2020-12-28T18:00
++
+As in the examples above, the date portion can be omitted, if the date of the interval is today.
+
+== SEE ALSO
+**timew-lengthen**(1),
+**timew-move**(1),
+**timew-resize**(1),
+**timew-shorten**(1),
+**timew-summary**(1)

doc/man1/timew-modify.1.in

@@ -1,36 +0,0 @@
-.TH timew-modify 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-modify \- change start or end date of an interval
-.
-.SH SYNOPSIS
-.B timew modify (
-.I start
-|
-.I end
-) 
-.I <id>
-.I <date>
-.
-.SH DESCRIPTION
-The 'modify' command is used to change the start or end date of an interval.
-Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
-Using the right ID, you can identify an interval to modify.
-.
-.SH EXAMPLES
-For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
-.PP
-Then having selected '@3' as the interval you wish to modify:
-.RS
-$ timew modify end @3 "${PACKAGE_DATE}"T17:00:00
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-lengthen (1),
-.BR timew-move (1),
-.BR timew-resize (1)
-.BR timew-shorten (1),
-.BR timew-summary (1)

doc/man1/timew-month.1

@@ -0,0 +1 @@
+.so man1/timew-chart.1

doc/man1/timew-move.1.adoc

@@ -0,0 +1,31 @@
+= timew-move(1)
+
+== NAME
+timew-move - change interval start-time
+
+== SYNOPSIS
+[verse]
+*timew move* _<id>_ _<date>_
+
+== DESCRIPTION
+The 'move' command is used to reposition an interval at a new start time.
+Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
+Using the right ID, you can identify an interval to move.
+
+== EXAMPLES
+For example, show the IDs:
+
+    $ timew summary :week :ids
+
+Then having selected '@2' as the interval you wish to move:
+
+    $ timew move @2 9am
+
+== SEE ALSO
+**timew-lengthen**(1),
+**timew-modify**(1),
+**timew-resize**(1),
+**timew-shorten**(1),
+**timew-summary**(1),
+**timew-tag**(1),
+**timew-untag**(1)

doc/man1/timew-move.1.in

@@ -1,32 +0,0 @@
-.TH timew-move 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-move \- change interval start-time
-.
-.SH SYNOPSIS
-.B timew move
-.I <id> <date>
-.
-.SH DESCRIPTION
-The 'move' command is used to reposition an interval at a new start time.
-Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
-Using the right ID, you can identify an interval to move.
-.
-.SH EXAMPLES
-For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
-Then having selected '@2' as the interval you wish to move:
-.RS
-$ timew move @2 9am
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-lengthen (1),
-.BR timew-modify (1),
-.BR timew-resize (1),
-.BR timew-shorten (1),
-.BR timew-summary (1),
-.BR timew-tag (1),
-.BR timew-untag (1)

doc/man1/timew-report.1.adoc

@@ -0,0 +1,36 @@
+= timew-report(1)
+
+== NAME
+timew-report - run an extension report
+
+== SYNOPSIS
+[verse]
+*timew* [*report*] _<report>_ [_<range>_] [_<tag>_**...**]
+*timew* [*report*] _<report>_ _<id>_**...**
+
+== DESCRIPTION
+Runs an extension report, and supports filtering data.
+The 'report' command itself is optional, which means that these two commands are equivalent:
+
+    $ timew report foo :week
+    $ timew        foo :week
+
+This does however assume there is a 'foo' extension installed.
+
+The return code is the return code of the extension.
+If the extension produces no output and a non-zero rc, then 255 is returned.
+
+Filtering is either possible by range and/or tags, or by ids.
+
+== CONFIGURATION
+
+**reports.range**::
+Sets the default date range for all reports.
+The value has to correspond to a range hint, see **timew-hints**(7).
+Defaults to `all`
+
+**reports.**__<name>__**.range**::
+Set the date range for report _name_, used if no _range_ is given on the command line.
+Here, _name_ is the name of the report executable without its extension (i.e. a report executable 'foo.py' is referred to by 'foo').
+The value has to correspond to a range hint, see **timew-hints**(7).
+Defaults to the value of **reports.range**.

doc/man1/timew-report.1.in

@@ -1,27 +0,0 @@
-.TH timew-report 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-report \- run an extension report
-.
-.SH SYNOPSIS
-.B timew
-[
-.B report
-]
-.I <report>
-[
-.I <range>
-] [
-.I <tag>
-.B ...
-]
-.
-.SH DESCRIPTION
-Runs an extension report, and supports filtering data.
-The 'report' command itself is optional, which means that these two commands are equivalent:
-.RS
-$ timew report foo :week
-.br
-$ timew        foo :week
-.RE
-This does however assume there is a 'foo' extension installed.

doc/man1/timew-resize.1.adoc

@@ -0,0 +1,34 @@
+= timew-resize(1)
+
+== NAME
+timew-resize - set interval duration
+
+== SYNOPSIS
+[verse]
+*timew resize* _<id>_**...** _<duration>_
+
+== DESCRIPTION
+The 'resize' command is used to change the duration of a closed interval.
+Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
+Using the right ID, you can identify an interval to resize.
+
+== EXAMPLES
+For example, show the IDs:
+
+    $ timew summary :week :ids
+
+Then having selected '@3' as the interval you wish to resize:
+
+    $ timew resize @3 15mins
+
+Note that you can resize multiple intervals,:
+
+    $ timew resize @3 @1 @13 1hour
+
+== SEE ALSO
+**timew-lengthen**(1),
+**timew-modify**(1),
+**timew-shorten**(1),
+**timew-summary**(1),
+**timew-tag**(1),
+**timew-untag**(1)

doc/man1/timew-resize.1.in

@@ -1,37 +0,0 @@
-.TH timew-resize 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-resize \- set interval duration
-.
-.SH SYNOPSIS
-.B timew resize
-.I <id>
-.B ...
-.I <duration>
-.
-.SH DESCRIPTION
-The 'resize' command is used to change the duration of a closed interval.
-Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
-Using the right ID, you can identify an interval to resize.
-.
-.SH EXAMPLES
-For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
-Then having selected '@3' as the interval you wish to resize:
-.RS
-$ timew resize @3 15mins
-.RE
-Note that you can resize multiple intervals,:
-.RS
-$ timew resize @3 @1 @13 1hour
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-lengthen (1),
-.BR timew-modify (1),
-.BR timew-shorten (1),
-.BR timew-summary (1),
-.BR timew-tag (1),
-.BR timew-untag (1)

doc/man1/timew-retag.1.adoc

@@ -0,0 +1,40 @@
+= timew-retag(1)
+
+== NAME
+timew-retag - replace all tags in intervals
+
+== SYNOPSIS
+[verse]
+*timew retag* [_<id>_**...**] _<tag>_**...**
+
+== DESCRIPTION
+The 'retag' command is used to replace all tags in an interval with the newly provided tags.
+Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
+Using the right ID, you can identify an interval to retag.
+
+== EXAMPLES
+For example, show the IDs:
+
+    $ timew summary :week :ids
+
+Then having selected '@2' as the interval you wish to retag:
+
+    $ timew retag @2 'New Tag'
+
+Note that you can retag multiple intervals, with multiple tags:
+
+    $ timew retag @2 @10 @23 'Tag One' tag2 tag3
+
+If there is active time tracking, you can omit the ID when you want to retag the current open interval:
+
+    $ timew start foo
+    $ timew retag bar
+
+This results in the current interval having only the 'bar' tag.
+
+== SEE ALSO
+**timew-lengthen**(1),
+**timew-shorten**(1),
+**timew-summary**(1),
+**timew-tag**(1),
+**timew-untag**(1)

doc/man1/timew-shorten.1.adoc

@@ -0,0 +1,34 @@
+= timew-shorten(1)
+
+== NAME
+timew-shorten - shorten intervals
+
+== SYNOPSIS
+[verse]
+*timew shorten* _<id>_**...** _<duration>_
+
+== DESCRIPTION
+The 'shorten' command is used to advance the end date of a closed interval.
+Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
+Using the right ID, you can identify an interval to shorten.
+
+== EXAMPLES
+For example, show the IDs:
+
+    $ timew summary :week :ids
+
+Then having selected '@2' as the interval you wish to shorten:
+
+    $ timew shorten @2 10mins
+
+Note that you can shorten multiple intervals,:
+
+    $ timew shorten @2 @10 @23 1hour
+
+== SEE ALSO
+**timew-lengthen**(1),
+**timew-modify**(1),
+**timew-resize**(1),
+**timew-summary**(1),
+**timew-tag**(1),
+**timew-untag**(1)

doc/man1/timew-shorten.1.in

@@ -1,38 +0,0 @@
-.TH timew-shorten 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-shorten \- shorten intervals
-.
-.SH SYNOPSIS
-.B timew shorten
-.I <id>
-.B ...
-.I <duration>
-.
-.SH DESCRIPTION
-The 'shorten' command is used to advance the end date of a closed interval.
-Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
-Using the right ID, you can identify an interval to shorten.
-.
-.SH EXAMPLES
-For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
-.br
-Then having selected '@2' as the interval you wish to shorten:
-.RS
-$ timew shorten @2 10mins
-.RE
-Note that you can shorten multiple intervals,:
-.RS
-$ timew shorten @2 @10 @23 1hour
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-lengthen (1),
-.BR timew-modify (1),
-.BR timew-resize (1),
-.BR timew-summary (1),
-.BR timew-tag (1),
-.BR timew-untag (1)

doc/man1/timew-show.1.adoc

@@ -0,0 +1,14 @@
+= timew-show(1)
+
+== NAME
+timew-show - display configuration
+
+== SYNOPSIS
+[verse]
+*timew show*
+
+== DESCRIPTION
+Displays the effective configuration in hierarchical form.
+
+== SEE ALSO
+**timew-config**(1)

doc/man1/timew-show.1.in

@@ -1,13 +0,0 @@
-.TH timew-show 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-show \- display configuration
-.
-.SH SYNOPSIS
-.B timew show
-.
-.SH DESCRIPTION
-Displays the effective configuration in hierarchical form.
-.
-.SH "SEE ALSO"
-.BR timew-config (1)

doc/man1/timew-split.1.adoc

@@ -0,0 +1,27 @@
+= timew-split(1)
+
+== NAME
+timew-split - split intervals
+
+== SYNOPSIS
+[verse]
+*timew split* _<id>_**...**
+
+== DESCRIPTION
+Ѕplits an interval into two equally sized adjacent intervals, having the same tags.
+Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
+Using the right ID, you can identify an interval to split.
+
+== EXAMPLES
+For example, show the IDs:
+
+    $ timew summary :week :ids
+
+Then having selected '@2' as the interval you wish to split:
+
+    $ timew split @2
+
+== SEE ALSO
+**timew-join**(1),
+**timew-lengthen**(1),
+**timew-shorten**(1)

doc/man1/timew-split.1.in

@@ -1,29 +0,0 @@
-.TH timew-split 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-split \- split intervals
-.
-.SH SYNOPSIS
-.B timew split
-.I <id>
-.B ...
-.
-.SH DESCRIPTION
-Ѕplits an interval into two equally sized adjacent intervals, having the same tags.
-Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
-Using the right ID, you can identify an interval to split.
-.
-.SH EXAMPLES
-For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
-Then having selected '@2' as the interval you wish to split:
-.RS
-$ timew split @2
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-join (1),
-.BR timew-lengthen (1),
-.BR timew-shorten (1)

doc/man1/timew-start.1.adoc

@@ -1,36 +1,31 @@
-.TH timew-start 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-start \- start time tracking
-.
-.SH SYNOPSIS
-.B timew start
-[
-.I <date>
-] [
-.I <tag>
-.B ...
-]
-.
-.SH DESCRIPTION
+= timew-start(1)
+
+== NAME
+timew-start - start time tracking
+
+== SYNOPSIS
+[verse]
+*timew start* [_<date>_] [_<tag>_**...**]
+
+== DESCRIPTION
 Begins tracking using the current time with any specified set of tags.
 If a tag contains multiple words, therefore containing spaces, use quotes to surround the whole tag.
-.
-.SH EXAMPLES
+
+== EXAMPLES
 For example, this command specifies two tags ('weekend' and 'Home & Garden'), the second of which requires quotes.
-.RS
-$ timew start weekend 'Home & Garden'
-.RE
+
+    $ timew start weekend 'Home & Garden'
+
 An optional date may be specified to indicate the intended start of the tracked time:
-.RS
-$ timew start 8am weekend 'Home & Garden'
-.RE
+
+    $ timew start 8am weekend 'Home & Garden'
+
 If there is a previous open interval, it will be closed at the given start time.
-.
+
 Quotes are harmless if used unnecessarily.
-.
-.SH "SEE ALSO"
-.BR timew-cancel (1),
-.BR timew-continue (1),
-.BR timew-stop (1),
-.BR timew-track (1)
+
+== SEE ALSO
+**timew-cancel**(1),
+**timew-continue**(1),
+**timew-stop**(1),
+**timew-track**(1)

doc/man1/timew-stop.1.adoc

@@ -0,0 +1,32 @@
+= timew-stop(1)
+
+== NAME
+timew-stop - stop time tracking
+
+== SYNOPSIS
+[verse]
+*timew stop* [_<date>_] [_<tag>_**...**]
+
+== DESCRIPTION
+Stops tracking time.
+If tags are specified, then they are no longer tracked.
+If no tags are specified, all tracking stops.
+
+== EXAMPLES
+For example:
+
+    $ timew start tag1 tag2
+    ...
+    $ timew stop tag1
+
+Initially time is tracked for both 'tag1' and 'tag2', then 'tag1' tracking is stopped, leaving tag2 active.
+To stop all tracking:
+
+    $ timew stop
+
+
+== SEE ALSO
+**timew-cancel**(1),
+**timew-continue**(1),
+**timew-start**(1),
+**timew-track**(1)

doc/man1/timew-stop.1.in

@@ -1,39 +0,0 @@
-.TH timew-stop 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-stop \- stop time tracking
-.
-.SH SYNOPSIS
-.B timew stop
-[
-.I <date>
-] [
-.I <tag>
-.B ...
-]
-.
-.SH DESCRIPTION
-Stops tracking time.
-If tags are specified, then they are no longer tracked.
-If no tags are specified, all tracking stops.
-.
-.SH EXAMPLES
-For example:
-.RS
-$ timew start tag1 tag2
-.br
-...
-.br
-$ timew stop tag1
-.RE
-Initially time is tracked for both 'tag1' and 'tag2', then 'tag1' tracking is stopped, leaving tag2 active.
-To stop all tracking:
-.RS
-$ timew stop
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-cancel (1),
-.BR timew-continue (1),
-.BR timew-start (1),
-.BR timew-track (1)

doc/man1/timew-summary.1.adoc

@@ -0,0 +1,94 @@
+= timew-summary(1)
+
+== NAME
+timew-summary - display a time-tracking summary
+
+== SYNOPSIS
+[verse]
+*timew summary* [_<range>_] [_<tag>_**...**]
+*timew summary* [_<id>_**...**]
+
+== DESCRIPTION
+Displays a table summarizing tracked time, by default for the current day.
+Accepts date ranges (or range hints) and tags, or ids for filtering.
+
+When ids are given, date ranges are ignored.
+Specifying both, tags and ids, is an error.
+
+== HINTS
+Apart from range hints (see **timew-hints**(7)), the summary report adheres to the following hints:
+
+**:annotations**::
+**:no-annotations**::
+Toggle the display of annotations in the summary report.
+Can be used on the command line to override the configured setting.
+The ':annotations' hint adds an 'Annotation' column to the summary table.
+The annotation column is limited to 15 characters.
+Longer values in this column are truncated to 12 characters and shown with an ellipsis attached.
+
+**:holidays**::
+**:no-holidays**::
+Toggle the display of holidays in the summary report.
+Can be used on the command line to override the configured setting.
+
+**:ids**::
+**:no-ids**::
+Toggle the display of ids in the summary report.
+Can be used on the command line to override the configured setting.
+The ':ids' hint adds an 'ID' column to the summary table.
+Those ids can be used for interval modification.
+
+**:tags**::
+**:no-tags**::
+Toggle the display of tags in the summary report.
+Can be used on the command line to override the configured setting.
+The ':tags' hint adds a 'Tags' column to the summary table.
+
+== CONFIGURATION
+**reports.summary.annotations**::
+Determines whether the annotation column is shown in the summary.
+Can be overridden by the ':annotations' or ':no-annotations' hint, respectively.
+Default value is 'no'
+
+**reports.summary.holidays**::
+Determines whether relevant holidays are shown beneath the report.
+Can be overridden by the ':holidays' or ':no-holidays' hint, respectively.
+Default value is 'yes'.
+
+**reports.summary.ids**::
+Determines whether the id column is shown in the summary.
+Can be overridden by the ':ids' or ':no-ids' hint, respectively.
+Default value is 'no'.
+
+**reports.summary.tags**::
+Determines whether the tags column is shown in the summary.
+Can be overridden by the ':tags' or ':no-tags' hint, respectively.
+Default value is 'yes'.
+
+**reports.summary.range**::
+Set the date range for the summary report.
+The value has to correspond to a range hint, see **timew-hints**(7).
+Default value is 'day'
+
+**reports.summary.weekdays**::
+Determines whether the weekday column is shown in the summary.
+Default value is 'yes'
+
+**reports.summary.weeks**::
+Determines whether the week column is shown in the summary.
+Default value is 'yes'
+
+**tags.**__<tag>__**.color**::
+Assigns a specific foreground and background color to a tag.
+Examples of valid colors include 'white', 'gray8', 'black on yellow', and 'rgb345'.
+
+== SEE ALSO
+**timew-day**(1),
+**timew-hints**(7),
+**timew-lengthen**(1),
+**timew-modify**(1),
+**timew-month**(1),
+**timew-shorten**(1),
+**timew-tag**(1),
+**timew-untag**(1),
+**timew-week**(1)

doc/man1/timew-summary.1.in

@@ -1,44 +0,0 @@
-.TH timew-summary 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-summary \- display a time-tracking summary
-.
-.SH SYNOPSIS
-.B timew summary
-[
-.I <range>
-] [
-.I <tag>
-.B ...
-]
-.
-.SH DESCRIPTION
-Displays a report summarizing tracked and untracked time for the current day by default.
-Accepts date ranges and tags for filtering, or shortcut hints:
-.RS
-$ timew summary monday - today
-.br
-$ timew summary :week
-.br
-$ timew summary :month
-.RE
-The ':ids' hint adds an 'ID' column to the summary report output for interval modification.
-.
-.SH CONFIGURATION
-.TP
-.B reports.summary.holidays
-.RS
-Determines whether relevant holidays are shown beneath the report.
-.br
-Default value is 'yes'.
-.RE
-.
-.SH "SEE ALSO"
-.BR timew-day (1),
-.BR timew-lengthen (1),
-.BR timew-modify (1),
-.BR timew-month (1),
-.BR timew-shorten (1),
-.BR timew-tag (1),
-.BR timew-untag (1),
-.BR timew-week (1)

doc/man1/timew-tag.1.adoc

@@ -1,45 +1,40 @@
-.TH timew-tag 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-tag \- add tags to intervals
-.
-.SH SYNOPSIS
-.B timew tag
-[
-.I <id>
-.B ...
-]
-.I <tag>
-.B ...
-.
-.SH DESCRIPTION
+= timew-tag(1)
+
+== NAME
+timew-tag - add tags to intervals
+
+== SYNOPSIS
+[verse]
+*timew tag* [_<id>_**...**] _<tag>_**...**
+
+== DESCRIPTION
 The 'tag' command is used to add a tag to an interval.
 Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
 Using the right ID, you can identify an interval to tag.
-.
-.SH EXAMPLES
+
+== EXAMPLES
 For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
+
+    $ timew summary :week :ids
+
 Then having selected '@2' as the interval you wish to tag:
-.RS
-$ timew tag @2 'New Tag'
-.RE
+
+    $ timew tag @2 'New Tag'
+
 Note that you can tag multiple intervals, with multiple tags:
-.RS
-$ timew tag @2 @10 @23 'Tag One' tag2 tag3
-.RE
+
+    $ timew tag @2 @10 @23 'Tag One' tag2 tag3
+
 If there is active time tracking, you can omit the ID when you want to add tags to the current open interval:
-.RS
-$ timew start foo
-.br
-$ timew tag bar
-.RE
+
+    $ timew start foo
+    $ timew tag bar
+
 This results in the current interval having tags 'foo' and 'bar'.
-.
-.SH "SEE ALSO"
-.BR timew-lengthen (1),
-.BR timew-shorten (1),
-.BR timew-summary (1),
-.BR timew-untag (1)
+
+== SEE ALSO
+**timew-lengthen**(1),
+**timew-retag**(1),
+**timew-shorten**(1),
+**timew-summary**(1),
+**timew-untag**(1)

doc/man1/timew-tags.1.adoc

@@ -0,0 +1,18 @@
+= timew-tags(1)
+
+== NAME
+timew-tags - display a list of tags
+
+== SYNOPSIS
+[verse]
+*timew tags* [_<range>_]
+
+== DESCRIPTION
+Displays all the tags that have been used by default.
+When a filter is specified, shows only the tags that were used during that time.
+
+== CONFIGURATION
+
+**tags.**__<tag>__**.color**::
+Assigns a specific foreground and background color to a tag.
+Examples of valid colors include 'white', 'gray8', 'black on yellow', and 'rgb345'.

doc/man1/timew-tags.1.in

@@ -1,14 +0,0 @@
-.TH timew-tags 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-tags \- display a list of tags
-.
-.SH SYNOPSIS
-.B timew tags
-[
-.I <range>
-]
-.
-.SH DESCRIPTION
-Displays all the tags that have been used by default.
-When a filter is specified, shows only the tags that were used during that time.

doc/man1/timew-track.1.adoc

@@ -0,0 +1,27 @@
+= timew-track(1)
+
+== NAME
+timew-track - add intervals to the database
+
+== SYNOPSIS
+[verse]
+*timew track* _<range>_ [_<tag>_**...**]
+
+== DESCRIPTION
+The track command is used to add tracked time in the past.
+Perhaps you forgot to record time, or are just filling in old entries.
+
+== EXAMPLES
+For example:
+
+    $ timew track :yesterday 'Training Course'
+    $ timew track 9am - 11am 'Staff Meeting'
+
+Note that the track command expects a closed interval (start and end time), when recording.
+If a closed interval is not provided, the 'track' command behaves the same as the 'start' command.
+
+== SEE ALSO
+**timew-cancel**(1),
+**timew-continue**(1),
+**timew-start**(1),
+**timew-stop**(1)

doc/man1/timew-track.1.in

@@ -1,32 +0,0 @@
-.TH timew-track 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-track \- add intervals to the database
-.
-.SH SYNOPSIS
-.B timew track
-.I <range>
-[
-.I <tag>
-.B ...
-]
-.
-.SH DESCRIPTION
-The track command is used to add tracked time in the past.
-Perhaps you forgot to record time, or are just filling in old entries.
-.
-.SH EXAMPLES
-For example:
-.RS
-$ timew track :yesterday 'Training Course'
-.br
-$ timew track 9am - 11am 'Staff Meeting'
-.RE
-Note that the track command expects a closed interval (start and end time), when recording.
-If a closed interval is not provided, the 'track' command behaves the same as the 'start' command.
-.
-.SH "SEE ALSO"
-.BR timew-cancel (1),
-.BR timew-continue (1),
-.BR timew-start (1),
-.BR timew-stop (1)

doc/man1/timew-undo.1.adoc

@@ -1,12 +1,13 @@
-.TH timew-undo 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-undo \- revert Timewarrior commands
-.
-.SH SYNOPSIS
-.B timew undo
-.
-.SH DESCRIPTION
+= timew-undo(1)
+
+== NAME
+timew-undo - revert Timewarrior commands
+
+== SYNOPSIS
+[verse]
+*timew undo*
+
+== DESCRIPTION
 The 'undo' command is used to revert the action of Timewarrior commands.
 Only commands affecting intervals or Timewarrior configuration can be reverted.
 Timewarrior keeps a journal of changes to the interval database and Timewarrior configuration.
@@ -14,10 +15,8 @@ A call to 'undo' removes the last entry in the journal and restores the previous
 As long as there are entries in the journal, you can revert the respective action.
 The 'undo' command itself cannot be undone!
 
-.SH EXAMPLES
-Undo an interval modification:
-.RS
-$ timew split @1
-.br
-$ timew undo
-.RE
+== EXAMPLES
+Undo an interval modification::
++
+    $ timew split @1
+    $ timew undo

doc/man1/timew-untag.1.adoc

@@ -1,45 +1,40 @@
-.TH timew-untag 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-untag \- remove tags from intervals
-.
-.SH SYNOPSIS
-.B timew untag
-[
-.I <id>
-.B ...
-]
-.I <tag>
-.B ...
-.
-.SH DESCRIPTION
+= timew-untag(1)
+
+== NAME
+timew-untag - remove tags from intervals
+
+== SYNOPSIS
+[verse]
+*timew untag* [_<id>_**...** ] _<tag>_**...**
+
+== DESCRIPTION
 The 'untag' command is used to remove a tag from an interval.
 Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
 Using the right ID, you can identify an interval to untag.
-.
-.SH EXAMPLES
+
+== EXAMPLES
 For example, show the IDs:
-.RS
-$ timew summary :week :ids
-.RE
+
+    $ timew summary :week :ids
+
 Then having selected '@2' as the interval you wish to untag:
-.RS
-$ timew untag @2 'Old Tag'
-.RE
+
+    $ timew untag @2 'Old Tag'
+
 Note that you can untag multiple intervals, with multiple tags:
-.RS
-$ timew untag @2 @10 @23 'Old Tag' tag2 tag3
-.RE
+
+    $ timew untag @2 @10 @23 'Old Tag' tag2 tag3
+
 If there is active time tracking, you can omit the ID when you want to remove tags from the current open interval:
-.RS
-$ timew start foo bar
-.br
-$ timew untag bar
-.RE
+
+    $ timew start foo bar
+    $ timew untag bar
+
 This results in the current interval having tag 'foo' but not 'bar'.
-.
-.SH "SEE ALSO"
-.BR timew-lengthen (1),
-.BR timew-shorten (1),
-.BR timew-summary (1),
-.BR timew-tag (1)
+
+== SEE ALSO
+**timew-lengthen**(1),
+**timew-retag**(1),
+**timew-shorten**(1),
+**timew-summary**(1),
+**timew-tag**(1)

doc/man1/timew-week.1

@@ -0,0 +1 @@
+.so man1/timew-chart.1

doc/man1/timew.1.adoc

@@ -0,0 +1,177 @@
+= timew(1)
+
+== NAME
+timew - a command line time tracker
+
+== SYNOPSIS
+[verse]
+*timew* [*--version*|*--help*]
+*timew* [_<command>_ [_<arg>_**...**]]
+
+== DESCRIPTION
+Timewarrior is a command line time tracker.
+It allows you to easily track your time and generate summary reports.
+
+This is a reference, not a tutorial.
+If you are looking for a tutorial, check the online documentation here:
+[source]
+----
+https://timewarrior.net/docs/
+----
+
+When run without arguments or options, the default command is run, which indicates whether there is any active tracking, and if so, shows a summary and exits with code 0.
+If there is no active time tracking, exit code is 1.
+
+== OPTIONS
+
+*--version*::
+Display Timewarrior version information
+
+*--help*::
+Display Timewarrior usage information
+
+== Timewarrior commands
+Timewarrior supports many commands.
+Alphabetically:
+
+*timew-annotate*(1)::
+    Add annotation to intervals
+
+*timew-cancel*(1)::
+    Cancel time tracking
+
+*timew-config*(1)::
+    Get and set Timewarrior configuration
+
+*timew-continue*(1)::
+    Resume tracking of existing interval
+
+*timew-day*(1)::
+    Display day chart
+
+*timew-delete*(1)::
+    Delete intervals
+
+*timew-diagnostics*(1)::
+    Show diagnostic information
+
+*timew-export*(1)::
+    Export tracked time in JSON
+
+*timew-extensions*(1)::
+    List available extensions
+
+*timew-get*(1)::
+    Display DOM values
+
+*timew-help*(1)::
+    Display help
+
+*timew-join*(1)::
+    Join intervals
+
+*timew-lengthen*(1)::
+    Lengthen intervals
+
+*timew-modify*(1)::
+    Change start or end time of an interval
+
+*timew-month*(1)::
+    Display month chart
+
+*timew-move*(1)::
+    Change interval start-time
+
+*timew-report*(1)::
+    Run an extension report
+
+*timew-resize*(1)::
+    Set interval duration
+
+*timew-retag*(1)::
+    Replace tags in intervals
+
+*timew-shorten*(1)::
+    Shorten intervals
+
+*timew-show*(1)::
+    Display configuration
+
+*timew-split*(1)::
+    Split intervals
+
+*timew-start*(1)::
+    Start time tracking
+
+*timew-stop*(1)::
+    Stop time tracking
+
+*timew-summary*(1)::
+    Display a time-tracking summary
+
+*timew-tag*(1)::
+    Add tags to intervals
+
+*timew-tags*(1)::
+    Display a list of tags
+
+*timew-track*(1)::
+    Add intervals to the database
+
+*timew-undo*(1)::
+    Undo Timewarrior commands
+
+*timew-untag*(1)::
+    Remove tags from intervals
+
+*timew-week*(1)::
+    Display week chart
+
+== MORE EXAMPLES
+
+For examples please see the online documentation at:
+
+https://timewarrior.net/docs/
+
+Note that the online documentation is often more detailed and more current than this man page.
+
+== FILES
+
+=== Non-Unix systems
+~/.timewarrior/timewarrior.cfg::
+    User configuration file.
+
+~/.timewarrior/data/YYYY-MM.data::
+    Time tracking data files.
+
+=== Unix systems
+${XDG_CONFIG_HOME:-$HOME/.config}/timewarrior/timewarrior.cfg::
+    User configuration file if legacy _~/.timewarrior_ directory doesn't exist.
+
+${XDG_DATA_HOME:-$HOME/.local/share}/timewarrior/data/YYYY-MM.data::
+    Time tracking data files if legacy _~/.timewarrior_ directory doesn't exist.
+
+== pass:[CREDITS & COPYRIGHT]
+Copyright (C) 2015 - 2018 T. Lauf, P. Beckingham, F. Hernandez. +
+Timewarrior is distributed under the MIT license.
+See https://www.opensource.org/licenses/mit-license.php for more information.
+
+== FURTHER DOCUMENTATION
+For more information regarding Timewarrior, see the following:
+
+The official site at https://timewarrior.net
+
+The official code repository at https://github.com/GothenburgBitFactory/timewarrior
+
+You can contact the project by emailing support@gothenburgbitfactory.org
+
+== REPORTING BUGS
+Bugs in Timewarrior may be reported to the issue-tracker at https://github.com/GothenburgBitFactory/timewarrior/issues
+
+== SEE ALSO
+**timew-config**(7),
+**timew-dates**(7),
+**timew-dom**(7),
+**timew-durations**(7),
+**timew-hints**(7),
+**timew-ranges**(7)

doc/man1/timew.1.in

@@ -1,239 +0,0 @@
-.TH timew 1 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew \- A command line time tracker.
-.
-.SH SYNOPSIS
-.BR "timew " [ --version | --help ]
-.br
-.B timew
-.RI [ "<command> " [ <arg> "...]]"
-.
-.SH DESCRIPTION
-Timewarrior is a command line time tracker.
-It allows you to easily track your time and generate summary reports.
-.
-This is a reference, not a tutorial.
-If you are looking for a tutorial, check the online documentation here:
-.br
-  https://taskwarrior.org/docs/timewarrior
-.br
-When run without arguments or options, the default command is run, which indicates whether there is any active tracking, and if so, shows a summary, then exits with a code 0.
-If there is no active time tracking, exit code is 1.
-.
-.SH OPTIONS
-.TP
-.B \-\-version
-.RS
-Displays TimeWarrior version information
-.RE
-.TP
-.B \-\-help
-.RS
-Display TimeWarrior usage information
-.RE
-.
-.SH "TIMEWARRIOR COMMANDS"
-Timewarrior supports many commands.
-Alphabetically:
-.
-.TP
-.BR timew-annotate (1)
-.RS
-Add annotation to intervals
-.RE
-.TP
-.BR timew-cancel (1)
-.RS
-Cancel time tracking
-.RE
-.TP
-.BR timew-config (1)
-.RS
-Get and set Timewarrior configuration
-.RE
-.TP
-.BR timew-continue (1)
-.RS
-Resume tracking of existing interval
-.RE
-.TP
-.BR timew-day (1)
-.RS
-Display day chart
-.RE
-.TP
-.BR timew-delete (1)
-.RS
-Delete intervals
-.RE
-.TP
-.BR timew-diagnostics (1)
-.RS
-Show diagnostic information
-.RE
-.TP
-.BR timew-export (1)
-.RS
-Export tracked time in JSON
-.RE
-.TP
-.BR timew-extensions (1)
-.RS
-List available extensions
-.RE
-.TP
-.BR timew-get (1)
-.RS
-Display DOM values
-.RE
-.TP
-.BR timew-help (1)
-.RS
-Display help
-.RE
-.TP
-.BR timew-join (1)
-.RS
-Join intervals
-.RE
-.TP
-.BR timew-lengthen (1)
-.RS
-Lengthen intervals
-.RE
-.TP
-.BR timew-modify (1)
-.RS
-Change start or end time of an interval
-.RE
-.TP
-.BR timew-month (1)
-.RS
-Display month chart
-.RE
-.TP
-.BR timew-move (1)
-.RS
-Change interval start-time
-.RE
-.TP
-.BR timew-report (1)
-.RS
-Run an extension report
-.RE
-.TP
-.BR timew-resize (1)
-.RS
-Set interval duration
-.RE
-.TP
-.BR timew-shorten (1)
-.RS
-Shorten intervals
-.RE
-.TP
-.BR timew-show (1)
-.RS
-Display configuration
-.RE
-.TP
-.BR timew-split (1)
-.RS
-Split intervals
-.RE
-.TP
-.BR timew-start (1)
-.RS
-Start time tracking
-.RE
-.TP
-.BR timew-stop (1)
-.RS
-Stop time tracking
-.RE
-.TP
-.BR timew-summary (1)
-.RS
-Display a time-tracking summary
-.RE
-.TP
-.BR timew-tag (1)
-.RS
-Add tags to intervals
-.RE
-.TP
-.BR timew-tags (1)
-.RS
-Display a list of tags
-.RE
-.TP
-.BR timew-track (1)
-.RS
-Add intervals to the database
-.RE
-.TP
-.BR timew-undo (1)
-.RS
-Undo Timewarrior commands
-.RE
-.TP
-.BR timew-untag (1)
-.RS
-Remove tags from intervals
-.RE
-.TP
-.BR timew-week (1)
-.RS
-Display week chart
-.RE
-.
-.SH "MORE EXAMPLES"
-.
-For examples please see the online documentation starting at:
-.
-.RS
-<https://taskwarrior.org/docs/timewarrior/>
-.RE
-.
-Note that the online documentation can be more detailed and more current than this man page.
-.
-.SH FILES
-.
-.TP
-~/.timewarrior/timewarrior.cfg
-User configuration file.
-.
-.TP
-~/.timewarrior/data/YYYY-MM.data
-Time tracking data files.
-.
-.SH "CREDITS & COPYRIGHTS"
-Copyright (C) 2015 \- 2018 T. Lauf, P. Beckingham, F. Hernandez.
-.br
-Timewarrior is distributed under the MIT license.
-See https://www.opensource.org/licenses/mit-license.php for more information.
-.
-.SH "FURTHER DOCUMENTATION"
-For more information regarding Timewarrior, see the following:
-.
-.TP
-The official site at <https://timewarrior.net>
-.
-.TP
-The official code repository at <https://github.com/GothenburgBitFactory/timewarrior>
-.
-.TP
-You can contact the project by emailing <support@gothenburgbitfactory.org>
-.
-.SH "REPORTING BUGS"
-.TP
-Bugs in Timewarrior may be reported to the issue-tracker at <https://github.com/GothenburgBitFactory/timewarrior/issues>
-.
-.SH "SEE ALSO"
-.BR timew-config (7),
-.BR timew-dates (7),
-.BR timew-dom (7),
-.BR timew-durations (7),
-.BR timew-hints (7),
-.BR timew-ranges (7)

doc/man7/CMakeLists.txt

@@ -0,0 +1,24 @@
+cmake_minimum_required (VERSION 3.10)
+
+if (ASCIIDOCTOR_FOUND)
+  file (GLOB DOC_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/*.7.adoc")
+  set (DOC_FILES)
+
+  foreach (SRC IN LISTS DOC_SOURCES)
+    string (REPLACE ".adoc" "" OUTPUT_FILE_NAME "${SRC}")
+    string (REPLACE "${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_BINARY_DIR}" OUTPUT_FILE_NAME "${OUTPUT_FILE_NAME}")
+
+    add_custom_command (OUTPUT "${OUTPUT_FILE_NAME}"
+                        COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage ${ASCIIDOCTOR_OPTIONS} "${SRC}" -o "${OUTPUT_FILE_NAME}"
+                        DEPENDS "${SRC}")
+
+    list (APPEND DOC_FILES "${OUTPUT_FILE_NAME}")
+  endforeach (SRC)
+
+  add_custom_target (man7 DEPENDS ${DOC_FILES})
+else (ASCIIDOCTOR_FOUND)
+  file (GLOB MAN_PAGES "${CMAKE_CURRENT_SOURCE_DIR}/*.7")
+  set (DOC_FILES ${MAN_PAGES})
+endif (ASCIIDOCTOR_FOUND)
+
+install (FILES ${DOC_FILES} DESTINATION ${TIMEW_MAN7DIR})

doc/man7/timew-config.7.adoc

@@ -0,0 +1,72 @@
+= timew-config(7)
+
+== NAME
+timew-config - Timewarrior configuration file and override options
+
+== SYNOPSIS
+**timew rc.**__<name>__**=**__<value>__ _<command>_
+
+== DESCRIPTION
+Timewarrior stores its configuration in the user's home directory in _~/.timewarrior/timewarrior.cfg_ on non-Unix systems (e.g. Windows).
+
+On Unix systems, XDG Base Directory specification is supported, if _~/.timewarrior_ directory doesn't exist
+(old config directory is still supported and has precedence over XDG BD compliant locations).
+
+This means configuration is stored in _$XDG_CONFIG_HOME/timewarrior/timewarrior.cfg_, which defaults to _~/.config/timewarrior/timewarrior.cfg_ if _$XDG_CONFIG_HOME_ environment variable is not specified.
+
+Those wanting to migrate their data to a new directory scheme, might do that with following shell snippet:
+
+[source,shell]
+----
+LEGACY="${HOME}/.timewarrior"
+CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/timewarrior"
+DATA_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/timewarrior"
+mkdir -p "${CONFIG_DIR}"
+mkdir -p "${DATA_DIR}"
+mv "${LEGACY}/timewarrior.cfg" "${CONFIG_DIR}"
+mv "${LEGACY}/extensions" "${CONFIG_DIR}"
+mv "${LEGACY}/data" "${DATA_DIR}"
+rmdir "${LEGACY}"
+----
+
+This file contains a mix of rules and configuration settings.
+Note that the TIMEWARRIORDB environment variable can be set to override this location.
+
+The values 'true', '1', 'y', 'yes' and 'on' are all equivalent and enable a setting.
+Any other value means disable the setting.
+
+Default values may be overridden by timewarrior.cfg values, which may in turn be overridden on the command line using: **rc.**__<name>__**=**__<value>__
+
+For example, to turn off verbose mode:
+
+    rc.verbose=0
+
+Note that hints can also do this (:quiet).
+
+== CONFIGURATION
+
+*confirmation*::
+Determines whether harmful operations require interactive confirmation.
++
+May be overridden by the ':yes' hint.
++
+Default value is 'yes'.
+
+*verbose*::
+Determines whether Timewarrior generates feedback.
++
+May be overridden by the ':quiet' hint.
++
+Default value is 'yes'.
+
+*debug*::
+Determines whether diagnostic debugging information is shown.
++
+Useful for troubleshooting, but not for general use.
++
+Default value is 'off'.
+
+*debug.indicator*::
+The debug output prefix string.
++
+Default value is '>>'.

doc/man7/timew-config.7.in

@@ -1,62 +0,0 @@
-.TH timew-config 7 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-config \- Timewarrior configuration file and override options
-.
-.SH SYNOPSIS
-.BI "timew rc." <name> = "<value> <command>"
-.
-.SH DESCRIPTION
-Timewarrior stores its configuration in the user's home directory in
-.I ~/.timewarrior/timewarrior.cfg.
-This file contains a mix of rules and configuration settings.
-Note that the TIMEWARRIORDB environment variable can be set to override this location.
-.
-The values 'true', '1', 'y', 'yes' and 'on' are all equivalent and enable a setting.
-Any other value means disable the setting.
-.
-Default values may be overridden by timewarrior.cfg values, which may in turn be overridden on the command line using:
-.BI rc. <name> = <value>
-.PP
-For example, to turn off verbose mode:
-.RS
-rc.verbose=0
-.RE
-.PP
-Note that hints can also do this (:quiet).
-.
-.SH CONFIGURATION
-.TP
-.B confirmation
-.RS
-Determines whether harmful operations require interactive confirmation.
-.br
-May be overridden by the ':yes' hint.
-.br
-Default value is 'yes'.
-.RE
-.TP
-.B verbose
-.RS
-Determines whether Timewarrior generates feedback.
-.br
-May be overridden by the ':quiet' hint.
-.br
-Default value is 'yes'.
-.RE
-.TP
-.B debug
-.RS
-Determines whether diagnostic debugging information is shown.
-.br
-Useful for troubleshooting, but not for general use.
-.br
-Default value is 'off'.
-.RE
-.TP
-.B debug.indicator
-.RS
-The debug output prefix string.
-.br
-Default value is '>>'.
-.RE

doc/man7/timew-dates.7.adoc

@@ -1,39 +1,46 @@
-.TH timew-dates 7 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-dates \- date formats supported by Timewarrior
-.
-.SH SYNOPSIS
-.
-.SH DESCRIPTION
-Timewarrior supports the following date formats based on ISO-8601:
-.
+= timew-dates(7)
+
+== NAME
+timew-dates - date formats supported by Timewarrior
+
+== SYNOPSIS
+
+== DESCRIPTION
+Timewarrior supports the following datetime formats based on ISO-8601.
+If times are followed by a 'Z', they are assumed to be in UTC, otherwise local time (TZ) is assumed.
+
   <extended-date> [T <extended-time>]   Extended date, optional extended time
   <date> [T <time>]                     Date, optional time
   <extended-time>                       Extended time
   <time>                                Time
-.
-  extended-date:
+
+extended-date::
++
     YYYY-MM-DD                          Year, month, day
     YYYY-MM                             Year, month, 1st
     YYYY-DDD                            Year, Julian day 001-366
     YYYY-WwwD                           Year, week number, day number
     YYYY-Www                            Year, week number, day 1
-.
-  extended-time:
+
+extended-time::
++
     hh:mm[:ss]Z                         Hours, minutes, optional seconds, UTC
     hh:mm[:ss][+/-hh:mm]                Hours, minutes, optional seconds, TZ
-.
-  date:
+
+date::
++
     YYYYMMDD                            Year, month, day
     YYYYWww                             Year, week number, day number
     YYYYDDD                             Year, Julian day 001-366
-.
-  time:
+
+time::
++
     hhmm[ss]Z                           Hour, minutes, optional seconds, UTC
     hhmm[ss][+/-hh[mm]]                 Hour, minutes, optional seconds, TZ
-.br
-Examples:
+
+== EXAMPLES
+Here are some examples for ISO datetimes:
+
   2016-06-09T08:12:00Z
   2016-06T08:12:00+01:00
   2016-06T08:12Z
@@ -44,9 +51,9 @@ Examples:
   2016W24
   8:12:00Z
   0812-0500
-.br
-In addition to the standard date formats, the following are supported:
-.
+
+In addition to the standard date formats, the following named dates are supported:
+
   now                                   Current date and time
   today                                 Current date at 0:00:00
   yesterday                             Yesterday at 0:00:00
@@ -55,7 +62,7 @@ In addition to the standard date formats, the following are supported:
   <month-of-year>                       Previous 1st of the month at 0:00:00
   hh:mm[:ss][am|a|pm|p]                 Short time format
   Nst, Nnd, Nrd, Nth                    Previous 1st, 2nd, 3rd ...
-  <epoch>                               POSIX time
+  <epoch>                               POSIX time (at least 315532800)
   later                                 2038-01-18T0:00:00 (Y2K38)
   someday                               2038-01-18T0:00:00 (Y2K38)
   sopd, eopd                            Start/end of previous day
@@ -84,14 +91,31 @@ In addition to the standard date formats, the following are supported:
   midsommar                             midnight, 1st Saturday after 20th June
   midsommarafton                        midnight, 1st Friday after 19th June
   juhannus                              midnight, 1st Friday after 19th June
-.br
-Examples:
+
+For times, the following are also possible:
+
   8am
   24th
   monday
   august
-.br
-.
-.SH "SEE ALSO"
-.BR timew-durations (7),
-.BR timew-hints (7)
+
+== NOTES
+The minimum value for the POSIX time format of 315532800 (that is 1980-01-01) was chosen to avoid confusion with ISO dates in the YYYYMMDD format.
+
+Because named dates are defined with time 0:00:00, using them as range end excludes the respective day.
+E.g. using 'today' as upper range
+[source]
+----
+$ timew sum 2d before today
+----
+will not show any intervals of the current day.
+Use either 'now' or 'tomorrow' in this case:
+[source]
+----
+$ timew sum 2d before now
+$ timew sum 2d before tomorrow
+----
+
+== SEE ALSO
+**timew-durations**(7),
+**timew-hints**(7)

doc/man7/timew-dom.7.adoc

@@ -1,23 +1,23 @@
-.TH timew-dom 7 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-dom \- Timewarrior DOM
-.
-.SH SYNOPSIS
-.
-.SH DESCRIPTION
+= timew-dom(7)
+
+== NAME
+timew-dom - Timewarrior DOM
+
+== SYNOPSIS
+
+== DESCRIPTION
 Supported DOM references are:
-.
+
   dom.tag.count             Count of all tags
   dom.tag.1                 Nth tag used
-.
+
   dom.active                '1' if there is active tracking, otherwise '0'
   dom.active.tag.count      Count of active tags
   dom.active.tag.1          Active Nth tag
   dom.active.start          Active start timestamp (ISO Extended local date)
   dom.active.duration       Active elapsed (ISO Period)
   dom.active.json           Active interval as JSON
-.
+
   dom.tracked.count         Count of tracked intervals
   dom.tracked.1.tag.count   Count of active tags
   dom.tracked.1.tag.1       Tracked Nth, Nth tag
@@ -25,5 +25,5 @@ Supported DOM references are:
   dom.tracked.1.end         Tracked Nth, end time, blank if closed
   dom.tracked.1.duration    Tracked Nth, elapsed
   dom.tracked.1.json        Tracked Nth, interval as JSON
-.
+
   dom.rc.<name>             Configuration setting

doc/man7/timew-durations.7.adoc

@@ -1,17 +1,18 @@
-.TH timew-durations 7 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-durations \- duration formats supported by Timewarrior
-.
-.SH SYNOPSIS
-.
-.SH DESCRIPTION
+= timew-durations(7)
+
+== NAME
+timew-durations - duration formats supported by Timewarrior
+
+== SYNOPSIS
+
+== DESCRIPTION
 Timewarrior supports the following duration formats based on ISO-8601:
-.
+
   'P' [nn 'Y'] [nn 'M'] [nn 'D'] ['T' [nn 'H'] [nn 'M'] [nn 'S']]
   PnnW
-.br
+
 Examples:
+
   P1Y           1 year
   P1.5M         1.5 months
   PT1S          1 second
@@ -20,16 +21,16 @@ Examples:
   P600D         600 days
   P3W           3 weeks
   P1Y1DT1H1M1S  1 year and 25 hours, 61 seconds (imprecise term)
-.br
+
 Note that the year and month terms are imprecise, being defined as 365d and 30d respectively.
 For precision use the other terms.
-.br
+
 In addition to the standard duration formats, the following are supported:
-.
+
   n[.n]<unit>
-.br
+
 Where the <unit> is one of:
-.
+
   annual
   biannual
   bimonthly
@@ -48,12 +49,12 @@ Where the <unit> is one of:
   weekdays
   weekly, weeks, week, wks, wk, w
   yearly, years, year, yrs, yr, y
-.br
+
 Examples:
   1hour         60 minutes
   1.5h          90 minutes
   3mo           3 months
   10d           10 days
-.br
+
 Note that the year, quarter and month terms are imprecise, being defined as 365d, 91d and 30d respectively.
 For precision use the other terms.

doc/man7/timew-hints.7.adoc

@@ -1,41 +1,42 @@
-.TH timew-hints 7 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-hints \- Timewarrior hints
-.
-.SH SYNOPSIS
-.
-.SH DESCRIPTION
+= timew-hints(7)
+
+== NAME
+timew-hints - Timewarrior hints
+
+== SYNOPSIS
+
+== DESCRIPTION
 Timewarrior supports hints, which are single-word command line features that start with a colon like this:
-.
+
   :week
-.br
+
 Hints serve several purposes.
 This example is a shortcut for the date range that defines the current week.
-.br
+
 Other hints, such as:
-.
+
   :quiet
-.br
-Are ways to control the behavior of Timewarrior, in this case eliminating all forms of feedback, for purposes of automation.
-.br
+
+are ways to control the behavior of Timewarrior, in this case eliminating all forms of feedback, for purposes of automation.
+
 The supported hints are:
-.
+
   :quiet         Turns off all feedback. For automation
   :debug         Runs in debug mode, shows many runtime details
   :yes           Overrides confirmation by answering 'yes' to the questions
-.
+
   :color         Force color on, even if not connected to a TTY
   :nocolor       Force color off, even if connected to a TTY
   :blank         Leaves tracked time out of a report
   :fill          Expand time to fill surrounding available gap
   :adjust        Automatically correct overlaps
   :ids           Displays interval ID numbers in the summary report
-.br
+
 Range hints provide convenient shortcuts to date ranges:
-.
+
+  :all           All tracked time
   :yesterday     The 24 hours of the previous day
-  :day           The 24 hours of the current day
+  :day / :today  The 24 hours of the current day
   :week          This week
   :fortnight     This week and the one before
   :month         This month

doc/man7/timew-ranges.7.adoc

@@ -1,23 +1,23 @@
-.TH timew-ranges 7 "${PACKAGE_DATE}" "${PACKAGE_STRING}" "User Manuals"
-.
-.SH NAME
-timew-ranges \- date and time ranges supported by Timewarrior
-.
-.SH SYNOPSIS
-.
-.SH DESCRIPTION
+= timew-ranges(7)
+
+== NAME
+timew-ranges - date and time ranges supported by Timewarrior
+
+== SYNOPSIS
+
+== DESCRIPTION
 An interval defines a block of time that is tracked.
 The syntax for specifying an interval is flexible, and may be one of:
-.
+
   [from] <date>
   [from] <date> to/- <date>
   [from] <date> for <duration>
   <duration> before/after <date>
   <duration> ago
   [for] <duration>
-.br
+
 Examples are:
-.
+
   from 9:00
   from 9am - 11am
   from 9:00:00 to 11:00
@@ -26,5 +26,10 @@ Examples are:
   2h before 11:00
   2h ago
   for 2h
-.br
-An interval is said to be 'closed' if there is both a start and end, and 'open' if there is no end date.
+
+An interval is called 'closed' if there is both a start date and an end date, and 'open' if there is no end date.
+
+There is also a number of useful hints for common ranges.
+
+== SEE ALSO
+**timew-hints**(7)

doc/rules.txt

@@ -1,26 +1,26 @@
 Rules System
 ============
-The Timewarrior rule system reads your ~/.timewarrior/timewarrior.cfg file and
-uses the combination of configuration settings and logic within to:
+The Timewarrior rule system reads your timewarrior.cfg file and uses the combination of configuration settings and logic within to:
 
 - Define configuration and customization details
 - Define tags, exclusions, constraints
 - Define various policies
 
-The rules are a mechanism to apply late-bound logic and data to various
-functions. Whenever data changes, the rule system is run, which will run each
-rule in turn, if it applies, going from top to bottom in the rules file. There
-are no chained rules, but errors will be able to terminate rule processing and
-program execution.
+On non-Unix systems config file is expected in ~/.timewarrior directory.
+On Unix systems, if legacy ~/.timewarrior directory doesn't exist, config is read from $XDG_CONFIG_HOME/timewarrior directory (if not specified, $XDG_CONFIG_HOME defaults to ~/.config).
 
-As much functionality as possible is to be deferred to the rules system, which
-will initially be minimal, but grow to be come more capable.
+The rules are a mechanism to apply late-bound logic and data to various functions.
+Whenever data changes, the rule system is run, which will run each
+rule in turn, if it applies, going from top to bottom in the rules file.
+There are no chained rules, but errors will be able to terminate rule processing and program execution.
+
+As much functionality as possible is to be deferred to the rules system, which will initially be minimal, but grow to become more capable.
 
 
 Format
 ------
-The rules are written as UTF8 text in the ~/.timewarrior/timewarrior.cfg text
-file. Other rules files may be included:
+The rules are written as UTF8 text in the timewarrior.cfg text file.
+Other rules files may be included:
 
   import /path/to/other/rule/file
 
@@ -29,8 +29,7 @@ The syntax of rules is Python-like, in that indentation is significant.
 
 Types of Rules
 --------------
-There are several different types of rules, for example there is the rule that
-defines all exclusions:
+There are several different types of rules, for example there is the rule that defines all exclusions:
 
   define exclusions:
     ...
@@ -55,8 +54,7 @@ There are rules that will serve as hooks:
 
 Rule Type: Exclusions
 ---------------------
-Because exclusions are resolved at run time, and only when needed, they should
-be stored in a readily-interpreted form:
+Because exclusions are resolved at run time, and only when needed, they should be stored in a readily-interpreted form:
 
   define exclusions:
     monday    = <8:00:00 12:00:00-12:45:00 >17:30:00
@@ -69,17 +67,15 @@ be stored in a readily-interpreted form:
       2016_01_01 = Working
       2016_01_02 = Off
 
-If you want to track your lunch breaks, then you would make a tag for it, and
-track it like any other project. If you do not want to track that time, add an
-exclusion for it.
+If you want to track your lunch breaks, then you would make a tag for it, and track it like any other project.
+If you do not want to track that time, add an exclusion for it.
 
 
 Rule Type: General
 ------------------
-There are rules triggered by changes to the data. In this example, rule 'one'
-is a constraint that prevents the value 'foo' from exceeding three. It is
-triggered by a change to 'foo', which is a DOM reference, and can prevent the
-update by failing:
+There are rules triggered by changes to the data.
+In this example, rule 'one' is a constraint that prevents the value 'foo' from exceeding three.
+It is triggered by a change to 'foo', which is a DOM reference, and can prevent the update by failing:
 
   define rules:
     one:
@@ -92,8 +88,7 @@ Note that this rule is defined as applying to the tagset 'tag1'.
 
 Rule Type: Tag
 --------------
-A defined tag is a way to associate metadata with a tag, such as a description
-and start/end dates for use:
+A defined tag is a way to associate metadata with a tag, such as a description and start/end dates for use:
 
   define tags:
     "tag1":
@@ -107,8 +102,7 @@ and start/end dates for use:
 
 Rule Type: Theme
 ----------------
-A color theme is defined by a rule, and consists of color definitions for
-various report and feedback elements:
+A color theme is defined by a rule, and consists of color definitions for various report and feedback elements:
 
   define theme:
     description = "A monochrome, 256-color theme"
@@ -120,20 +114,16 @@ various report and feedback elements:
       color2 = "white on blue"
       ...
 
-The palette group is a list (more is better) of themed colors for use when auto-
-coloring tags.
+The palette group is a list (more is better) of themed colors for use when auto-coloring tags.
 
-There is only one theme namespace, so if multiple themes are imported, the last
-one can override all the prior theme settings. This means themes can be layered,
-but they would need to be designed for this.
+There is only one theme namespace, so if multiple themes are imported, the last one can override all the prior theme settings.
+This means themes can be layered, but they would need to be designed for this.
 
 
 Rule Type: Hook
 ---------------
-While there may not be hooks in the traditional sense, with fixed arguments,
-there will be rules that have the same role. Hook rules will allow an internal
-event to trigger a rule that calls an external script, and passes an arbitrary
-set of arguments.
+While there may not be hooks in the traditional sense, with fixed arguments, there will be rules that have the same role.
+Hook rules will allow an internal event to trigger a rule that calls an external script, and passes an arbitrary set of arguments.
 
 [Mechanism TBD]
 
@@ -149,8 +139,7 @@ set of arguments.
       on_modify:
         ...
 
-These rules can run an external script and provide arguments, based on rules
-DOM access:
+These rules can run an external script and provide arguments, based on rules DOM access:
 
     define rules:
       on_modify:
@@ -159,8 +148,7 @@ DOM access:
 
 Rules Type: Hint
 ----------------
-Hints may be defined using the rules system, to augment the built-in hints that
-are used by almost every command.
+Hints may be defined using the rules system, to augment the built-in hints that are used by almost every command.
 
     define hints:
       staff:
@@ -172,8 +160,7 @@ are used by almost every command.
 
 --- Raw Notes ---
 
-- Need to distinguish between regular time and over time, with different rates
-  and limits.
+- Need to distinguish between regular time and over time, with different rates and limits.
 
 - Policy support involves things like:
   - warn after 40 hrs/wk
@@ -181,8 +168,7 @@ are used by almost every command.
   - auto-tag intervals that exceed 40 hrs/wk
   - auto-tag intervals during exclusion time
 
-- Need to distinguish between rules that will be supported at 1.0.0, and the
-  long term enhancements.
+- Need to distinguish between rules that will be supported at 1.0.0, and the long term enhancements.
 
 - There will need to be several built-in functions, for use by rules:
 
@@ -193,12 +179,10 @@ are used by almost every command.
 
   These are not good examples.
 
-- Need reports to help users doing fixed-rate work - finding the longest task
-  for example.
+- Need reports to help users doing fixed-rate work - finding the longest task for example.
 
-- If an interval has more than one tag with a defined color, and is being
-  rendered, then use the first tag color. It doesn't really matter which.
-
-- Use display granularity/resolution to see more or less details.  This would
-  combine nicely with a tag hierarchy. (Tomas Babej)
+- If an interval has more than one tag with a defined color, and is being rendered, then use the first tag color.
+  It doesn't really matter which.
 
+- Use display granularity/resolution to see more or less details.
+  This would combine nicely with a tag hierarchy. (Tomas Babej)

doc/themes/CMakeLists.txt

@@ -1,9 +1,9 @@
-cmake_minimum_required (VERSION 2.8)
+cmake_minimum_required (VERSION 3.10)
 
 message ("-- Configuring theme documentation")
 
-install (FILES README           DESTINATION ${TIMEW_DOCDIR}/doc/themes)
-INSTALL (FILES dark.theme       DESTINATION ${TIMEW_DOCDIR}/doc/themes)
-INSTALL (FILES dark_blue.theme  DESTINATION ${TIMEW_DOCDIR}/doc/themes)
-INSTALL (FILES dark_green.theme DESTINATION ${TIMEW_DOCDIR}/doc/themes)
-INSTALL (FILES dark_red.theme   DESTINATION ${TIMEW_DOCDIR}/doc/themes)
+install (FILES README           DESTINATION ${TIMEW_DOCDIR}/themes)
+install (FILES dark.theme       DESTINATION ${TIMEW_DOCDIR}/themes)
+install (FILES dark_blue.theme  DESTINATION ${TIMEW_DOCDIR}/themes)
+install (FILES dark_green.theme DESTINATION ${TIMEW_DOCDIR}/themes)
+install (FILES dark_red.theme   DESTINATION ${TIMEW_DOCDIR}/themes)

doc/themes/README

@@ -4,7 +4,8 @@ The theme files define colors that Timewarrior uses in various situations.
 There are several themes provided with Timewarrior, and you use a theme by importing it into your configuration file.
 Edit this file:
 
-    ~/.timewarrior/timewarrior.cfg
+    ~/.timewarrior/timewarrior.cfg (non-Unix systems or instalations using pre-XDG paths on Unix systems)
+    ${XDG_CONFIG_HOME:-$HOME/.config}/timewarrior/timewarrior.cfg (Unix systems)
 
 And add the import line, which looks like this:
 
@@ -35,7 +36,7 @@ Color settings include:
 
 The color palette is used to automatically color tagged time in reports.
 When creating a color theme, the palette should be larger rather than smaller.
-It is recommended that you provide at least 16 colors, otherwise Timewarrior cycles through them and you'll see repetitions.
+It is recommended that you provide at least 16 colors, otherwise Timewarrior cycles through them, and you'll see repetitions.
 
 ## Share Your Theme