Permalink
Browse files

Rework markdown

- One line per sentence
- Use '#' instead of underline to mark headings
- Consistent indentation
  • Loading branch information...
lauft committed Dec 21, 2018
1 parent 5b073d3 commit 37a3aa0ccf432808216867dd053ed640aa77a9eb
Showing with 116 additions and 156 deletions.
  1. +68 −93 INSTALL
  2. +4 −4 NEWS
  3. +9 −12 doc/holidays/README
  4. +26 −35 doc/themes/README
  5. +9 −12 ext/README
161 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=<path-to-installation-dir> .
$ cmake -DCMAKE_INSTALL_PREFIX=<path-to-installation-dir> .

cmake configuration variables are applied with the -D option and consist of a
<name> and a <value>:
cmake configuration variables are applied with the -D option and consist of a <name> and a <value>:

$ cmake -D<name>=<value> .
$ cmake -D<name>=<value> .

Four more variables can customize the installation process. The following table
lists them and their defaults plus the CMAKE_INSTALL_PREFIX:
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.

Troubleshooting
---------------
Either login to Windows as an Administrator and try the `make install` process again, or reinstall Cygwin under your normal Windows login.

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.
# Troubleshooting

If a build does not succeed, please send the contents of the 'CMakeCache.txt'
and 'CMakeFiles/CMakeOutput.log' files to support@gothenburgbitfactory.org.
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 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.
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 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.
8 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.
@@ -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
@@ -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.
@@ -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.

0 comments on commit 37a3aa0

Please sign in to comment.