diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..3ed40888 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,7 @@ +version: 2 +updates: + # Enable version updates for GitHub actions + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/workflows/docker-image.yaml b/.github/workflows/docker-image.yaml new file mode 100644 index 00000000..6e23e16c --- /dev/null +++ b/.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 }} diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml new file mode 100644 index 00000000..fe1829de --- /dev/null +++ b/.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 diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml new file mode 100644 index 00000000..b8642ce8 --- /dev/null +++ b/.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} }}" diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..4e6a92c4 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1 @@ +repos: [] diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 521aac6c..00000000 --- a/.travis.yml +++ /dev/null @@ -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 diff --git a/AUTHORS b/AUTHORS index b2d27527..9c69d2b5 100644 --- a/AUTHORS +++ b/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 diff --git a/CMakeLists.txt b/CMakeLists.txt index c220b161..715c847f 100644 --- a/CMakeLists.txt +++ b/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,8 +17,8 @@ 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 - ${CMAKE_SOURCE_DIR}/commit.h) + 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,20 +32,22 @@ 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 - ${CMAKE_SOURCE_DIR}/cmake.h) +configure_file (${CMAKE_SOURCE_DIR}/cmake.h.in + ${CMAKE_SOURCE_DIR}/cmake.h) add_subdirectory (src) add_subdirectory (src/commands) @@ -54,18 +57,31 @@ 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}) + install (FILES ${doc_FILE} DESTINATION ${TIMEW_DOCDIR}) 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) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1dfe0fb7..8f4b8642 100644 --- a/CONTRIBUTING.md +++ b/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 ': ' + $ git commit --signoff -am ': ' ... $ 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. diff --git a/COPYING b/COPYING deleted file mode 100644 index ac41de38..00000000 --- a/COPYING +++ /dev/null @@ -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 diff --git a/ChangeLog b/ChangeLog index 6aa760d8..9e0bcdaa 100644 --- a/ChangeLog +++ b/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 diff --git a/DCO b/DCO index 8b33caed..8154b336 100644 --- a/DCO +++ b/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 diff --git a/INSTALL b/INSTALL index 8a71bde5..7e0abfc3 100644 --- a/INSTALL +++ b/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= . - -cmake configuration variables are applied with the -D option and consist of a and a : +You can customize the configuration run with CMake variables. +CMake configuration variables are applied with the `-D` option and consist of a `` and a ``: $ cmake -D= . -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= . -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. diff --git a/LICENSE b/LICENSE index 9f67a7c9..22c6e2b4 100644 --- a/LICENSE +++ b/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 diff --git a/NEWS b/NEWS deleted file mode 100644 index 275eedff..00000000 --- a/NEWS +++ /dev/null @@ -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. diff --git a/README.md b/README.md index 64acf22f..effd5b58 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,101 @@ -# Timewarrior +
+Timewarrior logo +
-[![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) +
+[![Twitter](https://img.shields.io/twitter/follow/timewarrior_net?style=social)](https://twitter.com/timewarrior_net) +
+ +# 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§ion=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§ion=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, - - git clone --recurse-submodules https://github.com/GothenburgBitFactory/timewarrior - cd timewarrior - +* 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 diff --git a/cmake.h.in b/cmake.h.in index f190459f..ad29ddda 100644 --- a/cmake.h.in +++ b/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 - diff --git a/cmake/CXXSniffer.cmake b/cmake/CXXSniffer.cmake index e7ad810a..97bd5673 100644 --- a/cmake/CXXSniffer.cmake +++ b/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}") diff --git a/cmake/FindAsciidoctor.cmake b/cmake/FindAsciidoctor.cmake new file mode 100644 index 00000000..893541e7 --- /dev/null +++ b/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) diff --git a/completion/README.md b/completion/README.md index 795699b7..cbbae022 100644 --- a/completion/README.md +++ b/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) \ No newline at end of file +* `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! ❤️ diff --git a/completion/timew-completion.bash b/completion/timew-completion.bash index 3e691ed9..160a3dd3 100644 --- a/completion/timew-completion.bash +++ b/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 diff --git a/completion/timew.fish b/completion/timew.fish new file mode 100644 index 00000000..722a7ffe --- /dev/null +++ b/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] +# [from] to/- +# [from] for +# before/after +# ago +# [for] +# 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" + # @ [@ ...] + +complete -c timew -n "__fish_seen_subcommand_from config" \ + -a "" +#[ [ | '']] + +complete -c timew -n "__fish_seen_subcommand_from continue" \ + -a "$ids" +#[@] [|] + +complete -c timew -n "__fish_seen_subcommand_from day" \ + -a "$tags" +#[] [ ...] + +complete -c timew -n "__fish_seen_subcommand_from delete" \ + -a "$ids" +#@ [@ ...] + +complete -c timew -n "__fish_seen_subcommand_from export" \ + -a "$tags" +#[] [ ...] +# +complete -c timew -n "__fish_seen_subcommand_from gaps" \ + -a "$tags" +# [] [ ...] + +complete -c timew -n "__fish_seen_subcommand_from get" \ + -a "" +# [ ...] + +complete -c timew -n "__fish_seen_subcommand_from join" \ + -a "$ids" +# @ @ + +complete -c timew -n "__fish_seen_subcommand_from lengthen" \ + -a "$ids" +# @ [@ ...] + +complete -c timew -n "__fish_seen_subcommand_from modify && not __fish_seen_subcommand_from $start_end" \ + -a "start end" +# (start|end) @ + +complete -c timew -n "__fish_seen_subcommand_from modify && __fish_seen_subcommand_from $start_end" \ + -a "$ids" +# (start|end) @ + + +complete -c timew -n "__fish_seen_subcommand_from month" \ + -a "$tags" +# [] [ ...] + +complete -c timew -n "__fish_seen_subcommand_from move" \ + -a "$ids" +# @ + +complete -c timew -n "__fish_seen_subcommand_from $reports" \ + -a "$tags $interval" +# [] [ ...] + +complete -c timew -n "__fish_seen_subcommand_from shorten" \ + -a "$ids" +# @ [@ ...] + +complete -c timew -n "__fish_seen_subcommand_from split" \ + -a "$ids" +# @ [@ ...] + +complete -c timew -n "__fish_seen_subcommand_from start && not __fish_seen_subcommand_from modify" \ + -a "$tags $dates" +# [] [ ...] + +complete -c timew -n "__fish_seen_subcommand_from stop && not __fish_seen_subcommand_from modify" \ + -a "$tags" +# [ ...] + +complete -c timew -n "__fish_seen_subcommand_from summary" \ + -a "$tags $intervals" +# [] [ ...] + +complete -c timew -n "__fish_seen_subcommand_from tag" \ + -a "$ids $tags" +# @ [@ ...] [ ...] + +complete -c timew -n "__fish_seen_subcommand_from tags" \ + -a "$tags $intervals" +# [] [ ...] + +complete -c timew -n "__fish_seen_subcommand_from track" \ + -a "$tags $intervals" +# [ ...] + +complete -c timew -n "__fish_seen_subcommand_from untag" \ + -a "$ids $tags" +# @ [@ ...] [ ...] + +complete -c timew -n "__fish_seen_subcommand_from week" \ + -a "$tags $intervals" +# [] [ ...] + +complete -c timew -n "__fish_seen_subcommand_from help" \ + -a "$commands dates dom durations hints ranges" \ + -d "Show help" + + + diff --git a/completion/timew.zsh b/completion/timew.zsh new file mode 100644 index 00000000..61092441 --- /dev/null +++ b/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)' +) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 51f9a43a..379baf2c 100644 --- a/doc/CMakeLists.txt +++ b/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) diff --git a/doc/holidays/CMakeLists.txt b/doc/holidays/CMakeLists.txt index 44e0f4cb..319b75d8 100644 --- a/doc/holidays/CMakeLists.txt +++ b/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) diff --git a/doc/holidays/README b/doc/holidays/README index 73a40ee2..4afc2d77 100644 --- a/doc/holidays/README +++ b/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. diff --git a/doc/holidays/holidays.en-US b/doc/holidays/holidays.en-US index fb6c27fc..ba8090b0 100644 --- a/doc/holidays/holidays.en-US +++ b/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 diff --git a/doc/holidays/refresh b/doc/holidays/refresh index 789e471b..a53e5778 100755 --- a/doc/holidays/refresh +++ b/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) diff --git a/doc/man1/.gitignore b/doc/man1/.gitignore index 181f3143..90a6b24c 100644 --- a/doc/man1/.gitignore +++ b/doc/man1/.gitignore @@ -1 +1,4 @@ *.[0-9] +!timew-day.1 +!timew-month.1 +!timew-week.1 diff --git a/doc/man1/CMakeLists.txt b/doc/man1/CMakeLists.txt new file mode 100644 index 00000000..4ceaf279 --- /dev/null +++ b/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}) diff --git a/doc/man1/timew-annotate.1.adoc b/doc/man1/timew-annotate.1.adoc new file mode 100644 index 00000000..85f17a98 --- /dev/null +++ b/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* [__**...**] __ + +== DESCRIPTION +The 'annotate' command is used to add an annotation to an interval. + +See the 'summary' command on how to display the __ and __ 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) diff --git a/doc/man1/timew-annotate.1.in b/doc/man1/timew-annotate.1.in deleted file mode 100644 index 540d5faf..00000000 --- a/doc/man1/timew-annotate.1.in +++ /dev/null @@ -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 -.B ... -] -.I -.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) \ No newline at end of file diff --git a/doc/man1/timew-cancel.1.adoc b/doc/man1/timew-cancel.1.adoc new file mode 100644 index 00000000..5af5f813 --- /dev/null +++ b/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) diff --git a/doc/man1/timew-cancel.1.in b/doc/man1/timew-cancel.1.in deleted file mode 100644 index a5204674..00000000 --- a/doc/man1/timew-cancel.1.in +++ /dev/null @@ -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) \ No newline at end of file diff --git a/doc/man1/timew-chart.1.in b/doc/man1/timew-chart.1.adoc similarity index 50% rename from doc/man1/timew-chart.1.in rename to doc/man1/timew-chart.1.adoc index 48675716..386dd266 100644 --- a/doc/man1/timew-chart.1.in +++ b/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 -] [ -.I -.B ... -] -.br -.B timew month -[ -.I -] [ -.I -.B ... -] -.br -.B timew week -[ -.I -] [ -.I -.B ... -] -. -.SH DESCRIPTION += timew-chart(1) + +== NAME +timew-chart - display chart report + +== SYNOPSIS +[verse] +*timew day* [__] [__**...**] +*timew month* [__] [__**...**] +*timew week* [__] [__**...**] + +== 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. .range -configuration setting overrides the default date range. +There are three types: *day*, *week*, and *month* with their respective commands. +The **reports.**____**.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 " is one of" -.BR month ", " week ", " day "." -.TP -.BI reports. .cell -.RS +The default date range shown is *:day*. + +== CONFIGURATION +__ is one of **month**, **week**, **day**. + +**reports.**____**.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. .day -.RS + +**reports.**____**.day**:: Determines whether the current day of the month is shown at left margin. -.br Default value is 'yes'. -.RE -.TP -.BI reports. .holidays -.RS + +**reports.**____**.holidays**:: Determines whether relevant holidays are shown beneath the report. -.br Default value is 'yes'. -.RE -.TP -.BI reports. .hours -.RS -Determines how the report shows all the hours in a day ('all'), or is limited to only hours where data is tracked ('auto'). -.br + +**reports.**____**.hours**:: +Determines how the 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. .lines -.RS + +**reports.**____**.lines**:: Determines how many lines are used to render each day on the report. -.br Default value is '1'. -.RE -.TP -.BI reports. .month -.RS + +**reports.**____**.month**:: Determines whether the current month is shown at left margin. -.br Default value is 'yes'. -.RE -.TP -.BI reports. .range -.RS + +**reports.**____**.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. .spacing -.RS +**timew-hints**(7). + +**reports.**____**.spacing**:: Specifies how many spaces are inserted between the hours in the report exclusions. A value of '0' yields a more compact report. -.br Default value is '1'. -.RE -.TP -.BI reports. .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.**____**.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. .summary -.RS + +**reports.**____**.summary**:: Determines whether the hours summary is shown. -.br Default value is 'on'. -.RE -.TP -.BI reports. .totals -.RS + +**reports.**____**.totals**:: Determines whether the time totals are shown for each day on the report. -.br Default value is 'on'. -.RE -.TP -.BI reports. .week -.RS + +**reports.**____**.week**:: Determines whether the current week number is shown at left margin. -.br Default value is 'yes'. -.RE -.TP -.BI reports. .weekday -.RS + +**reports.**____**.weekday**:: Determines whether the current weekday is shown at left margin. -.br Default value is 'yes'. -.RE -. -.SH HINTS -.TP -.B :blank + +**tags.**____**.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) \ No newline at end of file + +== 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), diff --git a/doc/man1/timew-config.1.adoc b/doc/man1/timew-config.1.adoc new file mode 100644 index 00000000..31f0f03c --- /dev/null +++ b/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* [__ {__|*''*}] + +== 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) diff --git a/doc/man1/timew-config.1.in b/doc/man1/timew-config.1.in deleted file mode 100644 index d95256f2..00000000 --- a/doc/man1/timew-config.1.in +++ /dev/null @@ -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 -{ -.I -| -.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) \ No newline at end of file diff --git a/doc/man1/timew-continue.1.adoc b/doc/man1/timew-continue.1.adoc new file mode 100644 index 00000000..79fe7538 --- /dev/null +++ b/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* [__|__**...**] [__|__] + +== 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) diff --git a/doc/man1/timew-continue.1.in b/doc/man1/timew-continue.1.in deleted file mode 100644 index 60b8ac8a..00000000 --- a/doc/man1/timew-continue.1.in +++ /dev/null @@ -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 -] [ -{ -.I -| -.I -} -] -. -.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) \ No newline at end of file diff --git a/doc/man1/timew-day.1 b/doc/man1/timew-day.1 new file mode 100644 index 00000000..1782cd78 --- /dev/null +++ b/doc/man1/timew-day.1 @@ -0,0 +1 @@ +.so man1/timew-chart.1 diff --git a/doc/man1/timew-delete.1.adoc b/doc/man1/timew-delete.1.adoc new file mode 100644 index 00000000..66eecbbf --- /dev/null +++ b/doc/man1/timew-delete.1.adoc @@ -0,0 +1,26 @@ += timew-delete(1) + +== NAME +timew-delete - delete intervals + +== SYNOPSIS +[verse] +*timew delete* __**...** + +== 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) diff --git a/doc/man1/timew-delete.1.in b/doc/man1/timew-delete.1.in deleted file mode 100644 index 03746b4f..00000000 --- a/doc/man1/timew-delete.1.in +++ /dev/null @@ -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 -.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 \ No newline at end of file diff --git a/doc/man1/timew-diagnostics.1.in b/doc/man1/timew-diagnostics.1.adoc similarity index 56% rename from doc/man1/timew-diagnostics.1.in rename to doc/man1/timew-diagnostics.1.adoc index cb93b215..e51f6ea1 100644 --- a/doc/man1/timew-diagnostics.1.in +++ b/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) \ No newline at end of file + +== SEE ALSO +**timew-extensions**(1) diff --git a/doc/man1/timew-export.1.adoc b/doc/man1/timew-export.1.adoc new file mode 100644 index 00000000..da85b9c3 --- /dev/null +++ b/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* [ __**...** | ([__] [__**...**]) ] + +== 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 +... +---- diff --git a/doc/man1/timew-export.1.in b/doc/man1/timew-export.1.in deleted file mode 100644 index afd3fc52..00000000 --- a/doc/man1/timew-export.1.in +++ /dev/null @@ -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 -] [ -.I ... -] -. -.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 \ No newline at end of file diff --git a/doc/man1/timew-extensions.1.adoc b/doc/man1/timew-extensions.1.adoc new file mode 100644 index 00000000..33254740 --- /dev/null +++ b/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) diff --git a/doc/man1/timew-extensions.1.in b/doc/man1/timew-extensions.1.in deleted file mode 100644 index 5738368d..00000000 --- a/doc/man1/timew-extensions.1.in +++ /dev/null @@ -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) \ No newline at end of file diff --git a/doc/man1/timew-fill.1.in b/doc/man1/timew-fill.1.adoc similarity index 50% rename from doc/man1/timew-fill.1.in rename to doc/man1/timew-fill.1.adoc index 02ceea55..713570bb 100644 --- a/doc/man1/timew-fill.1.in +++ b/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 -.B ... -. -.SH DESCRIPTION += timew-fill(1) + +== NAME +timew-fill - adjust intervals to fill in surrounding gaps + +== SYNOPSIS +[verse] +*timew fill* __**...** + +== 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) \ No newline at end of file + + $ timew fill @2 @10 @23 + + +== SEE ALSO +**timew-hints**(7) diff --git a/doc/man1/timew-gaps.1.adoc b/doc/man1/timew-gaps.1.adoc new file mode 100644 index 00000000..6fa5c36d --- /dev/null +++ b/doc/man1/timew-gaps.1.adoc @@ -0,0 +1,23 @@ += timew-gaps(1) + +== NAME +timew-gaps - display time tracking gaps + +== SYNOPSIS +[verse] +*timew gaps* [__] [__**...**] + +== 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) diff --git a/doc/man1/timew-gaps.1.in b/doc/man1/timew-gaps.1.in deleted file mode 100644 index 18d3f0ef..00000000 --- a/doc/man1/timew-gaps.1.in +++ /dev/null @@ -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 -] [ -.I -.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) \ No newline at end of file diff --git a/doc/man1/timew-get.1.adoc b/doc/man1/timew-get.1.adoc new file mode 100644 index 00000000..09b5746d --- /dev/null +++ b/doc/man1/timew-get.1.adoc @@ -0,0 +1,22 @@ += timew-get(1) + +== NAME +timew-get - display DOM values + +== SYNOPSIS +[verse] +*timew get* __**...** + +== 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) diff --git a/doc/man1/timew-get.1.in b/doc/man1/timew-get.1.in deleted file mode 100644 index 1eb56209..00000000 --- a/doc/man1/timew-get.1.in +++ /dev/null @@ -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 -.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 \ No newline at end of file diff --git a/doc/man1/timew-help.1.adoc b/doc/man1/timew-help.1.adoc new file mode 100644 index 00000000..980296fb --- /dev/null +++ b/doc/man1/timew-help.1.adoc @@ -0,0 +1,22 @@ += timew-help(1) + +== NAME +timew-help - display help + +== SYNOPSIS +[verse] +*timew help* {__|*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 diff --git a/doc/man1/timew-help.1.in b/doc/man1/timew-help.1.in deleted file mode 100644 index 0f16858c..00000000 --- a/doc/man1/timew-help.1.in +++ /dev/null @@ -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 -| -.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 \ No newline at end of file diff --git a/doc/man1/timew-join.1.adoc b/doc/man1/timew-join.1.adoc new file mode 100644 index 00000000..c593bd72 --- /dev/null +++ b/doc/man1/timew-join.1.adoc @@ -0,0 +1,28 @@ += timew-join(1) + +== NAME +timew-join - join intervals + +== SYNOPSIS +[verse] +*timew join* _ _ + +== 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) diff --git a/doc/man1/timew-join.1.in b/doc/man1/timew-join.1.in deleted file mode 100644 index 3a056085..00000000 --- a/doc/man1/timew-join.1.in +++ /dev/null @@ -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 -. -.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) \ No newline at end of file diff --git a/doc/man1/timew-lengthen.1.adoc b/doc/man1/timew-lengthen.1.adoc new file mode 100644 index 00000000..39db2afb --- /dev/null +++ b/doc/man1/timew-lengthen.1.adoc @@ -0,0 +1,34 @@ += timew-lengthen(1) + +== NAME +timew-lengthen - lengthen intervals + +== SYNOPSIS +[verse] +*timew lengthen* __**...** __ + +== 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) diff --git a/doc/man1/timew-lengthen.1.in b/doc/man1/timew-lengthen.1.in deleted file mode 100644 index 8e8d339c..00000000 --- a/doc/man1/timew-lengthen.1.in +++ /dev/null @@ -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 -.B ... -.I -. -.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) \ No newline at end of file diff --git a/doc/man1/timew-modify.1.adoc b/doc/man1/timew-modify.1.adoc new file mode 100644 index 00000000..96aadcaa --- /dev/null +++ b/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*) __ __ +*timew modify* 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) \ No newline at end of file diff --git a/doc/man1/timew-modify.1.in b/doc/man1/timew-modify.1.in deleted file mode 100644 index 37db9cd2..00000000 --- a/doc/man1/timew-modify.1.in +++ /dev/null @@ -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 -.I -. -.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) \ No newline at end of file diff --git a/doc/man1/timew-month.1 b/doc/man1/timew-month.1 new file mode 100644 index 00000000..1782cd78 --- /dev/null +++ b/doc/man1/timew-month.1 @@ -0,0 +1 @@ +.so man1/timew-chart.1 diff --git a/doc/man1/timew-move.1.adoc b/doc/man1/timew-move.1.adoc new file mode 100644 index 00000000..4b994650 --- /dev/null +++ b/doc/man1/timew-move.1.adoc @@ -0,0 +1,31 @@ += timew-move(1) + +== NAME +timew-move - change interval start-time + +== SYNOPSIS +[verse] +*timew move* __ __ + +== 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) diff --git a/doc/man1/timew-move.1.in b/doc/man1/timew-move.1.in deleted file mode 100644 index 64dede12..00000000 --- a/doc/man1/timew-move.1.in +++ /dev/null @@ -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 -. -.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) \ No newline at end of file diff --git a/doc/man1/timew-report.1.adoc b/doc/man1/timew-report.1.adoc new file mode 100644 index 00000000..1c1aa776 --- /dev/null +++ b/doc/man1/timew-report.1.adoc @@ -0,0 +1,36 @@ += timew-report(1) + +== NAME +timew-report - run an extension report + +== SYNOPSIS +[verse] +*timew* [*report*] __ [__] [__**...**] +*timew* [*report*] __ __**...** + +== 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.**____**.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**. diff --git a/doc/man1/timew-report.1.in b/doc/man1/timew-report.1.in deleted file mode 100644 index d2e8333d..00000000 --- a/doc/man1/timew-report.1.in +++ /dev/null @@ -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 -[ -.I -] [ -.I -.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. \ No newline at end of file diff --git a/doc/man1/timew-resize.1.adoc b/doc/man1/timew-resize.1.adoc new file mode 100644 index 00000000..040ba529 --- /dev/null +++ b/doc/man1/timew-resize.1.adoc @@ -0,0 +1,34 @@ += timew-resize(1) + +== NAME +timew-resize - set interval duration + +== SYNOPSIS +[verse] +*timew resize* __**...** __ + +== 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) diff --git a/doc/man1/timew-resize.1.in b/doc/man1/timew-resize.1.in deleted file mode 100644 index f666bd30..00000000 --- a/doc/man1/timew-resize.1.in +++ /dev/null @@ -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 -.B ... -.I -. -.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) \ No newline at end of file diff --git a/doc/man1/timew-retag.1.adoc b/doc/man1/timew-retag.1.adoc new file mode 100644 index 00000000..7df199f9 --- /dev/null +++ b/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* [__**...**] __**...** + +== 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) diff --git a/doc/man1/timew-shorten.1.adoc b/doc/man1/timew-shorten.1.adoc new file mode 100644 index 00000000..c83b3650 --- /dev/null +++ b/doc/man1/timew-shorten.1.adoc @@ -0,0 +1,34 @@ += timew-shorten(1) + +== NAME +timew-shorten - shorten intervals + +== SYNOPSIS +[verse] +*timew shorten* __**...** __ + +== 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) diff --git a/doc/man1/timew-shorten.1.in b/doc/man1/timew-shorten.1.in deleted file mode 100644 index 1b2757dc..00000000 --- a/doc/man1/timew-shorten.1.in +++ /dev/null @@ -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 -.B ... -.I -. -.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) \ No newline at end of file diff --git a/doc/man1/timew-show.1.adoc b/doc/man1/timew-show.1.adoc new file mode 100644 index 00000000..ec9f9079 --- /dev/null +++ b/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) diff --git a/doc/man1/timew-show.1.in b/doc/man1/timew-show.1.in deleted file mode 100644 index cf83a30a..00000000 --- a/doc/man1/timew-show.1.in +++ /dev/null @@ -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) \ No newline at end of file diff --git a/doc/man1/timew-split.1.adoc b/doc/man1/timew-split.1.adoc new file mode 100644 index 00000000..dee76e37 --- /dev/null +++ b/doc/man1/timew-split.1.adoc @@ -0,0 +1,27 @@ += timew-split(1) + +== NAME +timew-split - split intervals + +== SYNOPSIS +[verse] +*timew split* __**...** + +== 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) diff --git a/doc/man1/timew-split.1.in b/doc/man1/timew-split.1.in deleted file mode 100644 index e8cac1aa..00000000 --- a/doc/man1/timew-split.1.in +++ /dev/null @@ -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 -.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) \ No newline at end of file diff --git a/doc/man1/timew-start.1.in b/doc/man1/timew-start.1.adoc similarity index 54% rename from doc/man1/timew-start.1.in rename to doc/man1/timew-start.1.adoc index 91996b35..3ec98585 100644 --- a/doc/man1/timew-start.1.in +++ b/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 -] [ -.I -.B ... -] -. -.SH DESCRIPTION += timew-start(1) + +== NAME +timew-start - start time tracking + +== SYNOPSIS +[verse] +*timew start* [__] [__**...**] + +== 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) \ No newline at end of file + +== SEE ALSO +**timew-cancel**(1), +**timew-continue**(1), +**timew-stop**(1), +**timew-track**(1) diff --git a/doc/man1/timew-stop.1.adoc b/doc/man1/timew-stop.1.adoc new file mode 100644 index 00000000..492fecc3 --- /dev/null +++ b/doc/man1/timew-stop.1.adoc @@ -0,0 +1,32 @@ += timew-stop(1) + +== NAME +timew-stop - stop time tracking + +== SYNOPSIS +[verse] +*timew stop* [__] [__**...**] + +== 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) diff --git a/doc/man1/timew-stop.1.in b/doc/man1/timew-stop.1.in deleted file mode 100644 index 58d05296..00000000 --- a/doc/man1/timew-stop.1.in +++ /dev/null @@ -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 -] [ -.I -.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) \ No newline at end of file diff --git a/doc/man1/timew-summary.1.adoc b/doc/man1/timew-summary.1.adoc new file mode 100644 index 00000000..8e4dadaa --- /dev/null +++ b/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* [__] [__**...**] +*timew summary* [__**...**] + +== 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.**____**.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) diff --git a/doc/man1/timew-summary.1.in b/doc/man1/timew-summary.1.in deleted file mode 100644 index 3369684a..00000000 --- a/doc/man1/timew-summary.1.in +++ /dev/null @@ -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 -] [ -.I -.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) \ No newline at end of file diff --git a/doc/man1/timew-tag.1.in b/doc/man1/timew-tag.1.adoc similarity index 51% rename from doc/man1/timew-tag.1.in rename to doc/man1/timew-tag.1.adoc index 3840e49b..63a921b2 100644 --- a/doc/man1/timew-tag.1.in +++ b/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 -.B ... -] -.I -.B ... -. -.SH DESCRIPTION += timew-tag(1) + +== NAME +timew-tag - add tags to intervals + +== SYNOPSIS +[verse] +*timew 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) \ No newline at end of file + +== SEE ALSO +**timew-lengthen**(1), +**timew-retag**(1), +**timew-shorten**(1), +**timew-summary**(1), +**timew-untag**(1) diff --git a/doc/man1/timew-tags.1.adoc b/doc/man1/timew-tags.1.adoc new file mode 100644 index 00000000..636955a2 --- /dev/null +++ b/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* [__] + +== 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.**____**.color**:: +Assigns a specific foreground and background color to a tag. +Examples of valid colors include 'white', 'gray8', 'black on yellow', and 'rgb345'. diff --git a/doc/man1/timew-tags.1.in b/doc/man1/timew-tags.1.in deleted file mode 100644 index 85ab0aa8..00000000 --- a/doc/man1/timew-tags.1.in +++ /dev/null @@ -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 -] -. -.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. \ No newline at end of file diff --git a/doc/man1/timew-track.1.adoc b/doc/man1/timew-track.1.adoc new file mode 100644 index 00000000..9eacc4b5 --- /dev/null +++ b/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* __ [__**...**] + +== 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) diff --git a/doc/man1/timew-track.1.in b/doc/man1/timew-track.1.in deleted file mode 100644 index f88ed065..00000000 --- a/doc/man1/timew-track.1.in +++ /dev/null @@ -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 -[ -.I -.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) \ No newline at end of file diff --git a/doc/man1/timew-undo.1.in b/doc/man1/timew-undo.1.adoc similarity index 64% rename from doc/man1/timew-undo.1.in rename to doc/man1/timew-undo.1.adoc index a1b7920f..ab863462 100644 --- a/doc/man1/timew-undo.1.in +++ b/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 \ No newline at end of file +== EXAMPLES +Undo an interval modification:: ++ + $ timew split @1 + $ timew undo diff --git a/doc/man1/timew-untag.1.in b/doc/man1/timew-untag.1.adoc similarity index 51% rename from doc/man1/timew-untag.1.in rename to doc/man1/timew-untag.1.adoc index e263c6a8..7b42bec9 100644 --- a/doc/man1/timew-untag.1.in +++ b/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 -.B ... -] -.I -.B ... -. -.SH DESCRIPTION += timew-untag(1) + +== NAME +timew-untag - remove tags from intervals + +== SYNOPSIS +[verse] +*timew untag* [__**...** ] __**...** + +== 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) \ No newline at end of file + +== SEE ALSO +**timew-lengthen**(1), +**timew-retag**(1), +**timew-shorten**(1), +**timew-summary**(1), +**timew-tag**(1) diff --git a/doc/man1/timew-week.1 b/doc/man1/timew-week.1 new file mode 100644 index 00000000..1782cd78 --- /dev/null +++ b/doc/man1/timew-week.1 @@ -0,0 +1 @@ +.so man1/timew-chart.1 diff --git a/doc/man1/timew.1.adoc b/doc/man1/timew.1.adoc new file mode 100644 index 00000000..223a0df7 --- /dev/null +++ b/doc/man1/timew.1.adoc @@ -0,0 +1,177 @@ += timew(1) + +== NAME +timew - a command line time tracker + +== SYNOPSIS +[verse] +*timew* [*--version*|*--help*] +*timew* [__ [__**...**]] + +== 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) diff --git a/doc/man1/timew.1.in b/doc/man1/timew.1.in deleted file mode 100644 index 57db9c73..00000000 --- a/doc/man1/timew.1.in +++ /dev/null @@ -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 [ " " [ "...]]" -. -.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 - -.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 -. -.TP -The official code repository at -. -.TP -You can contact the project by emailing -. -.SH "REPORTING BUGS" -.TP -Bugs in Timewarrior may be reported to the issue-tracker at -. -.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) \ No newline at end of file diff --git a/doc/man7/CMakeLists.txt b/doc/man7/CMakeLists.txt new file mode 100644 index 00000000..58b1b968 --- /dev/null +++ b/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}) diff --git a/doc/man7/timew-config.7.adoc b/doc/man7/timew-config.7.adoc new file mode 100644 index 00000000..27a0a81a --- /dev/null +++ b/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.**____**=**____ __ + +== 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.**____**=**____ + +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 '>>'. diff --git a/doc/man7/timew-config.7.in b/doc/man7/timew-config.7.in deleted file mode 100644 index c09b2893..00000000 --- a/doc/man7/timew-config.7.in +++ /dev/null @@ -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." = " " -. -.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. = -.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 diff --git a/doc/man7/timew-dates.7.in b/doc/man7/timew-dates.7.adoc similarity index 74% rename from doc/man7/timew-dates.7.in rename to doc/man7/timew-dates.7.adoc index 9ab4e3a5..f8f3cd27 100644 --- a/doc/man7/timew-dates.7.in +++ b/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. + [T ] Extended date, optional extended time [T