diff --git a/INSTALL b/INSTALL index 67d5c4fe..d4ed5ab4 100644 --- a/INSTALL +++ b/INSTALL @@ -1,12 +1,9 @@ -Installation Instructions -------------------------- +# Installation Instructions -Please follow the instructions below to build and install Timewarrior from -source. +Please follow the instructions below to build and install Timewarrior from source. -Dependencies ------------- +# Dependencies In order to build Timewarrior, you will need: @@ -18,140 +15,118 @@ You will need a C++ compiler that supports full C++11, which includes: - clang 3.4 (released 2014-01-02) -Basic Installation ------------------- +# Basic Installation Briefly, these shell commands will unpack, build and install Timewarrior: - $ tar xzf timew-X.Y.Z.tar.gz [1] - $ cd timew-X.Y.Z [2] - $ cmake . [3] - $ make [4] - $ sudo make install [5] - $ cd .. ; rm -r timew-X.Y.Z [6] + $ tar xzf timew-X.Y.Z.tar.gz [1] + $ cd timew-X.Y.Z [2] + $ cmake . [3] + $ make [4] + $ sudo make install [5] + $ cd .. ; rm -r timew-X.Y.Z [6] These commands are explained below: - 1. Unpacks the source tarball. This creates the directory timew-X.Y.Z, - containing all the code. + 1. Unpacks the source tarball. + This creates the directory timew-X.Y.Z, containing all the code. 2. Change directory to the root of the distribution. - 3. Invokes CMake to scan for dependencies and machine-specific details, then - generate the makefiles. This may take a minute. + 3. Invokes CMake to scan for dependencies and machine-specific details, then generate the makefiles. + This may take a minute. - 4. Builds Timewarrior. This may take a minute. + 4. Builds Timewarrior. + This may take a minute. 5. Installs the program, documentation and other data files. 6. Removes the temporary directory. -Build and configurations options --------------------------------- +# Build and configurations options -You can customize the configuration run with cmake variables. This will modify -the installation process: +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: +To change the installation directory you use the following configuration variable: - $ cmake -DCMAKE_INSTALL_PREFIX= . + $ cmake -DCMAKE_INSTALL_PREFIX= . -cmake configuration variables are applied with the -D option and consist of a - and a : +cmake configuration variables are applied with the -D option and consist of a and a : - $ cmake -D= . + $ cmake -D= . -Four more variables can customize the installation process. The following table -lists them and their defaults plus the CMAKE_INSTALL_PREFIX: +Four more variables can customize the installation process. +The following table lists them and their defaults plus the `CMAKE_INSTALL_PREFIX`: - 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 + 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 -The corresponding TIMEW_* variables will be combined with CMAKE_INSTALL_PREFIX to -get absolute installation directories: +The corresponding `TIMEW_*` variables will be combined with `CMAKE_INSTALL_PREFIX` to get absolute installation directories: - 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_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 -Updating Timewarrior build --------------------------- +# 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. +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. +To do that, run: - $ git pull --recurse-submodules - $ git submodule update + $ 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 - $ sudo make install + $ cmake . + $ make + $ sudo make install -Uninstallation --------------- +# Uninstallation -There is no uninstall option in CMake makefiles. This is a manual process. +There is no uninstall option in CMake makefiles. +This is a manual process. -To uninstall Timewarrior, remove the files listed in the install_manifest.txt -file that was generated when you built Timewarrior. +To uninstall Timewarrior, remove the files listed in the `install_manifest.txt` file that was generated when you built Timewarrior. -Timewarrior Build Notes ------------------------ +# Timewarrior Build Notes -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. +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 this doesn't help, then go to the Troubleshooting -section, which includes instructions on how to contact us for help. +If Timewarrior will 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. -Operating System Notes ----------------------- +# Operating System Notes -Cygwin - If 'make install' fails when writing to the /usr/local/share/ directory, - this may be because your current login doesn't have permission to write - to the Windows directory containing your Cygwin installation. Either - login to Windows as an Administrator and try the 'make install' process - again, or reinstall Cygwin under your normal Windows login. +## Cygwin + +If `make install` fails when writing to the `/usr/local/share/` directory, this may be because your current login doesn't have permission to write to the Windows directory containing your Cygwin installation. + +Either login to Windows as an Administrator and try the `make install` process again, or reinstall Cygwin under your normal Windows login. -Troubleshooting ---------------- +# Troubleshooting -If you've recently made changes to dependencies (by reinstalling them, for -example) be sure to rerun 'cmake .' before trying to execute 'make' again. +If you've recently made changes to dependencies (by reinstalling them, for example) be sure to rerun `cmake .` before trying to execute `make` again. -CMake will run and locate all the necessary pieces for the build, and create -a Makefile. There may be errors and warnings when running CMake, or there -may be compiler errors and warnings when running 'make'. Sometimes you will run -CMake with no reported problems, and the build will fail later. This is -almost always because CMake is mistaken about some assumption. +CMake will run and locate all the necessary pieces for the build, and create a Makefile. +There may be errors and warnings when running CMake, or there may be compiler errors and warnings when running `make`. +Sometimes you will run CMake with no reported problems, and the build will fail later. +This is almost always because CMake is mistaken about some assumption. -If a build does not succeed, please send the contents of the 'CMakeCache.txt' -and 'CMakeFiles/CMakeOutput.log' files to support@gothenburgbitfactory.org. +If a build does not succeed, please send the contents of the `CMakeCache.txt` and `CMakeFiles/CMakeOutput.log` files to `support@gothenburgbitfactory.org`. -If CMake runs but Timewarrior does not build, please send the contents of the -above files as well as a transcript from the build, which is not written to a -file and must be captured from the terminal. - ---- +If CMake runs but Timewarrior does not build, please send the contents of the above files as well as a transcript from the build, which is not written to a file and must be captured from the terminal. diff --git a/NEWS b/NEWS index e2b9532d..f4606af9 100644 --- a/NEWS +++ b/NEWS @@ -35,13 +35,13 @@ Timewarrior has been built and tested on the following configurations: --- -While Timewarrior has undergone testing, bugs are sure to remain. If you find -a bug, please enter a new issue at: +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 + https://github.com/GothenburgBitFactory/timewarrior/issues Or just send a message to: - support@gothenburgbitfactory.org + support@gothenburgbitfactory.org Thank you. diff --git a/doc/holidays/README b/doc/holidays/README index 8af29fb8..040cce59 100644 --- a/doc/holidays/README +++ b/doc/holidays/README @@ -1,24 +1,21 @@ -Timewarrior Holiday Files -========================= +# Timewarrior Holiday Files -The holiday files were created using https://holidata.net data by the 'refresh' -script. This data can be updated using these commands: +The holiday files were created using https://holidata.net data by the 'refresh' script. +This data can be updated using these commands: - $ ./refresh + $ ./refresh If you need another locale (for example sv-SE), do this: - $ ./refresh --locale sv-SE + $ ./refresh --locale sv-SE If you need a specific locale region, do this: - $ ./refresh --locale de-CH --region Bern + $ ./refresh --locale de-CH --region Bern -By default, the current and next year are updated. If the locale is not -supported by holidata.net, or there is no data (yet) for the locale for this -year and next year, you will see an error. +By default, the current and next year are updated. +If the locale is not supported by holidata.net, or there is no data (yet) for the locale for this year and next year, you will see an error. To specify a set of years to update, do this: - $ ./refresh --locale en-US --year 2015 2016 2017 - + $ ./refresh --locale en-US --year 2015 2016 2017 diff --git a/doc/themes/README b/doc/themes/README index e580a4e2..30bf5c8d 100644 --- a/doc/themes/README +++ b/doc/themes/README @@ -1,56 +1,47 @@ -Timewarrior Color Themes -======================== +# Timewarrior Color Themes The theme files define colors that Timewarrior uses in various situations. -There are several themes provided with Timewarrior, and you use a theme by -importing it into your configuration file. Edit this file: +There are several themes provided with Timewarrior, and you use a theme by importing it into your configuration file. +Edit this file: - ~/.timewarrior/timewarrior.cfg + ~/.timewarrior/timewarrior.cfg And add the import line, which looks like this: - import /path/to/theme/dark.theme + import /path/to/theme/dark.theme You can find more themes online at ... - TODO URL needed +TODO URL needed -Create Your Own ---------------- +## Create Your Own -It is easy to create your own Timewarrior color theme. The simplest approach is -to copy an existing theme and then modify the colors. +It is easy to create your own Timewarrior color theme. +The simplest approach is to copy an existing theme and then modify the colors. -There is no minimum requirement for a theme - it doesn't need to define any -colors, but that isn't really the point of a theme. Ideally define a description -which is shown in the 'diagnostics' command output: +There is no minimum requirement for a theme - it doesn't need to define any colors, but that isn't really the point of a theme. +Ideally define a description which is shown in the 'diagnostics' command output: - theme.description Description of the theme. + theme.description Description of the theme. -The individual color settings are all used by Taskwarrior, and providing a -color for each of these is best. If no color is provided for a setting, then no -color is used, a default does not apply. Color settings include: +The individual color settings are all used by Taskwarrior, and providing a color for each of these is best. +If no color is provided for a setting, then no color is used, a default does not apply. +Color settings include: - theme.colors.exclusion Used to color excluded time in reports - theme.colors.today Used to highlight today on reports that show dates - theme.colors.label Used for non-critical labels in reports + theme.colors.exclusion Used to color excluded time in reports + theme.colors.today Used to highlight today on reports that show dates + theme.colors.label Used for non-critical labels in reports -The color palette is used to automatically color tagged time in reports. When -creating a color theme, the palette should be larger rather than smaller. It is -recommended that you provide at least 16 colors, otherwise Timewarrior cycles -through them and you'll see repetitions. +The color palette is used to automatically color tagged time in reports. +When creating a color theme, the palette should be larger rather than smaller. +It is recommended that you provide at least 16 colors, otherwise Timewarrior cycles through them and you'll see repetitions. +## Share Your Theme -Share Your Theme ----------------- +Having created a color theme, share it in the spirit of Open Source. +Make it available for download, or alternatively send it to us at: -Having created a color theme, share it in the spirit of Open Source. Make it -available for download, or alternatively send it to us at: + support@gothenburgbitfactory.org - support@gothenburgbitfactory.org - -We will list (and attribute) your theme on the Timewarrior support pages, where -you will find other themes and extensions. - ---- +We will list (and attribute) your theme on the Timewarrior support pages, where you will find other themes and extensions. diff --git a/ext/README b/ext/README index 211a8f72..63ebddd2 100644 --- a/ext/README +++ b/ext/README @@ -1,18 +1,15 @@ -Timewarrior Extensions -====================== +# Timewarrior Extensions -debug.py - This is a debug extension that simply echoes back everything it sees in its - input. It's useful for debugging to see how the command line affects what an - extension sees. This will likely be removed before release. +## debug.py + This is a debug extension that simply echoes back everything it sees in its input. + It's useful for debugging to see how the command line affects what an extension sees. + This will likely be removed before release. -on-modify.timewarrior +## on-modify.timewarrior This is a Taskwarrior hook script that will integrate Timewarrior. -csv.py - This extension exports the data in CSV format, with a variable number of tag - fields. +## csv.py + This extension exports the data in CSV format, with a variable number of tag fields. -totals.py +## totals.py Sample extension report that shows totals by tag. -