Variable: org-duration-format

org-duration-format is a customizable variable defined in org-duration.el.gz.

Value

(("d")
 (special . h:mm))

Documentation

Format definition for a duration.

The value can be set to, respectively, the symbols h:mm:ss or h:mm, which means a duration is expressed as, respectively, a "H:MM:SS" or "H:MM" string.

Alternatively, the value can be a list of entries following the pattern:

  (UNIT . REQUIRED?)

UNIT is a unit string, as defined in org-duration-units. The time duration is formatted using only the time components that are specified here.

Units with a zero value are skipped, unless REQUIRED? is non-nil. In that case, the unit is always used.

The list can also contain one of the following special entries:

  (special . h:mm)
  (special . h:mm:ss)

    Units shorter than an hour are ignored. The hours and
    minutes part of the duration is expressed unconditionally
    with H:MM, or H:MM:SS, pattern.

  (special . PRECISION)

    A duration is expressed with a single unit, PRECISION being
    the number of decimal places to show. The unit chosen is the
    first one required or with a non-zero integer part. If there
    is no such unit, the smallest one is used.

Eventually, if the list contains the symbol compact, the duration is expressed in a compact form, without any white space between units.

For example,

   (("d" . nil) ("h" . t) ("min" . t))

means a duration longer than a day is expressed in days, hours and minutes, whereas a duration shorter than a day is always expressed in hours and minutes, even when shorter than an hour.

On the other hand, the value

  (("d" . nil) ("min" . nil))

means a duration longer than a day is expressed in days and minutes, whereas a duration shorter than a day is expressed entirely in minutes, even when longer than an hour.

The following format

  (("d" . nil) (special . h:mm))

means that any duration longer than a day is expressed with both a "d" unit and a "H:MM" part, whereas a duration shorter than a day is expressed only as a "H:MM" string.

Eventually,

  (("d" . nil) ("h" . nil) (special . 2))

expresses a duration longer than a day as a decimal number, with a 2-digits fractional part, of "d" unit. A duration shorter than a day uses "h" unit instead.

This variable was added, or its default value changed, in Org version
9.1.

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-duration.el.gz
(defcustom org-duration-format '(("d" . nil) (special . h:mm))
  "Format definition for a duration.

The value can be set to, respectively, the symbols `h:mm:ss' or
`h:mm', which means a duration is expressed as, respectively,
a \"H:MM:SS\" or \"H:MM\" string.

Alternatively, the value can be a list of entries following the
pattern:

  (UNIT . REQUIRED?)

UNIT is a unit string, as defined in `org-duration-units'.  The
time duration is formatted using only the time components that
are specified here.

Units with a zero value are skipped, unless REQUIRED? is non-nil.
In that case, the unit is always used.

The list can also contain one of the following special entries:

  (special . h:mm)
  (special . h:mm:ss)

    Units shorter than an hour are ignored.  The hours and
    minutes part of the duration is expressed unconditionally
    with H:MM, or H:MM:SS, pattern.

  (special . PRECISION)

    A duration is expressed with a single unit, PRECISION being
    the number of decimal places to show.  The unit chosen is the
    first one required or with a non-zero integer part.  If there
    is no such unit, the smallest one is used.

Eventually, if the list contains the symbol `compact', the
duration is expressed in a compact form, without any white space
between units.

For example,

   ((\"d\" . nil) (\"h\" . t) (\"min\" . t))

means a duration longer than a day is expressed in days, hours
and minutes, whereas a duration shorter than a day is always
expressed in hours and minutes, even when shorter than an hour.

On the other hand, the value

  ((\"d\" . nil) (\"min\" . nil))

means a duration longer than a day is expressed in days and
minutes, whereas a duration shorter than a day is expressed
entirely in minutes, even when longer than an hour.

The following format

  ((\"d\" . nil) (special . h:mm))

means that any duration longer than a day is expressed with both
a \"d\" unit and a \"H:MM\" part, whereas a duration shorter than
a day is expressed only as a \"H:MM\" string.

Eventually,

  ((\"d\" . nil) (\"h\" . nil) (special . 2))

expresses a duration longer than a day as a decimal number, with
a 2-digits fractional part, of \"d\" unit.  A duration shorter
than a day uses \"h\" unit instead."
  :group 'org-time
  :group 'org-clock
  :package-version '(Org . "9.1")
  :type '(choice
	  (const :tag "Use H:MM" h:mm)
	  (const :tag "Use H:MM:SS" h:mm:ss)
	  (repeat :tag "Use units"
		  (choice
		   (cons :tag "Use units"
			 (string :tag "Unit")
			 (choice (const :tag "Skip when zero" nil)
				 (const :tag "Always used" t)))
		   (cons :tag "Use a single decimal unit"
			 (const special)
			 (integer :tag "Number of decimals"))
		   (cons :tag "Use both units and H:MM"
			 (const special)
			 (const h:mm))
		   (cons :tag "Use both units and H:MM:SS"
			 (const special)
			 (const h:mm:ss))
		   (const :tag "Use compact form" compact)))))