From 9719de8ea3a88f2968378ff213202737dc9f3dda Mon Sep 17 00:00:00 2001
From: Lukas Fleischer <calcurse@cryptocrack.de>
Date: Wed, 23 May 2012 02:04:59 +0200
Subject: Document extended format specifiers

Add documentation for extended format specifiers (which were introduced
in 68b26ff85415ee687b082fbd5150de58cdce0935) to the man page and the
manual. Add a note about strftime()-style extended formats for
"%(start)" and "%(end)".

Signed-off-by: Lukas Fleischer <calcurse@cryptocrack.de>
---
 doc/calcurse.1.txt | 25 +++++++++++++++++++++++++
 doc/manual.txt     | 25 +++++++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/doc/calcurse.1.txt b/doc/calcurse.1.txt
index 70049c7..6768088 100644
--- a/doc/calcurse.1.txt
+++ b/doc/calcurse.1.txt
@@ -256,6 +256,31 @@ Examples
 *`calcurse -t --format-todo '(%p) %m\n'`*::
   List all todo items and put parentheses around the priority specifiers.
 
+Extended format specifiers
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Extended format specifiers can be used if you want to specify advanced
+formatting options. Extended specifiers are introduced by *%(* and are
+terminated by a closing parenthesis (*)*). The following list includes all
+short specifiers and corresponding long options:
+
+* *s*: *(start)*
+* *S*: *(start:epoch)*
+* *d*: *(duration)*
+* *e*: *(end)*
+* *E*: *(end:epoch)*
+* *m*: *(message)*
+* *n*: *(noteid)*
+* *N*: *(note)*
+* *p*: *(priority)*
+
+The *(start)* and *(end)* specifiers support strftime()-style extended
+formatting options that can be used for fine-grained formatting. Additionally,
+the special formats *epoch* (which is equivalent to *(start:%s)* or *(end:%s)*)
+and *default* (which is mostly equivalent to *(start:%H:%M)* or *(end:%H:%M)*
+but displays *..:..* if the item doesn't start/end at the current day) are
+supported.
+
 Notes
 -----
 
diff --git a/doc/manual.txt b/doc/manual.txt
index 50ee0f9..80993cf 100644
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -366,6 +366,31 @@ Examples
 `calcurse -t --format-todo '(%p) %m\n'`::
   List all todo items and put parentheses around the priority specifiers.
 
+Extended format specifiers
+++++++++++++++++++++++++++
+
+Extended format specifiers can be used if you want to specify advanced
+formatting options. Extended specifiers are introduced by `%(` and are
+terminated by a closing parenthesis (`)`). The following list includes all
+short specifiers and corresponding long options:
+
+* `s`: `(start)`
+* `S`: `(start:epoch)`
+* `d`: `(duration)`
+* `e`: `(end)`
+* `E`: `(end:epoch)`
+* `m`: `(message)`
+* `n`: `(noteid)`
+* `N`: `(note)`
+* `p`: `(priority)`
+
+The `(start)` and `(end)` specifiers support strftime()-style extended
+formatting options that can be used for fine-grained formatting. Additionally,
+the special formats `epoch` (which is equivalent to `(start:%s)` or `(end:%s)`)
+and `default` (which is mostly equivalent to `(start:%H:%M)` or `(end:%H:%M)`
+but displays `..:..` if the item doesn't start/end at the current day) are
+supported.
+
 [[basics_invocation_variable]]
 Environment variable for i18n
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-- 
cgit v1.2.3-70-g09d2