diff --git a/docs/custom/cheetah.md b/docs/custom/cheetah.md
index 7ea9146a..c51f48f5 100644
--- a/docs/custom/cheetah.md
+++ b/docs/custom/cheetah.md
@@ -233,7 +233,7 @@ _`obstype`_ is an observation type, such as `barometer`. This type must appear e
_`optional_unit_conversion`_ is an optional unit conversion tag. If provided, the results will be converted into the specified units, otherwise the default units specified in the skin configuration file (in section `[Units][[Groups]]`) will be used. See the section _[Unit conversion options](#unit-conversion-options)_.
-_`optional_rounding`_ allows the results to be rounded to a fixed number of decimal digits. See the section _[Optional rounding](#optional-rounding)_.
+_`optional_rounding`_ allows the results to be rounded to a fixed number of decimal digits. See the section _[Optional rounding options](#optional-rounding-options)_.
_`optional_formatting`_ is a set of optional formatting tags, which control how the value will appear. See the section _[Formatting options](#formatting-options)_ below.
@@ -269,7 +269,7 @@ _`aggregation`_ is an _aggregation type_. If you ask for `$month.outTemp.avg` yo
_`optional_unit_conversion`_ is an optional unit conversion tag. If provided, the results will be converted into the specified units, otherwise the default units specified in the skin configuration file (in section `[Units][[Groups]]`) will be used. See the section _[Unit conversion options](#unit-conversion-options)_.
-_`optional_rounding`_ allows the results to be rounded to a fixed number of decimal digits. See the section _[Optional rounding](#optional-rounding)_
+_`optional_rounding`_ allows the results to be rounded to a fixed number of decimal digits. See the section _[Optional rounding options](#optional-rounding-options)_
_`optional_formatting`_ is a set of optional formatting tags, which control how the value will appear. See the section _[Formatting options](#formatting-options)_ below.
@@ -388,9 +388,9 @@ The _`$optional_ago`_ parameters can be useful for statistics farther in the pas
-## Unit conversion options
+### Unit conversion options
-The tag _`optional_unit_conversion`_ can be used with either current observations or aggregations. If supplied, the results will be converted to the specified units. For example, if you have set `group_pressure` to inches of mercury (`inHg`), then the tag
+The option _`optional_unit_conversion`_ can be used with either current observations or with aggregations. If supplied, the results will be converted to the specified units. For example, if you have set `group_pressure` to inches of mercury (`inHg`), then the tag
Today's average pressure=$day.barometer.avg
@@ -428,30 +428,40 @@ or in degrees C: $day.barometer.min.degree_C
or in foobar units: $day.barometer.min.foobar
-### Optional rounding
+### Option `round()`
The data in the resultant tag can be optionally rounded to a fixed number of decimal digits. This is useful when emitting raw data or JSON strings. It should _not_ be used with formatted data (using a [format string](#format_string) would be a better choice).
-The structure of the tag is
+The structure of the option is
.round(ndigits=None)
where `ndigits` is the number of decimal digits to retain. If `None` (the default), then all digits will be retained.
-## Formatting options
+### Formatting options
-A variety of tags and arguments are available to you to customize the formatting of the final observation value. This table lists the tags:
+A variety of options are available to you to customize the formatting of the final observation value. They can be used whenever a tag results in a [`ValueHelper`](../appendix#ValueHelper), which is almost all the time. This table summarizes the options:
- Optional formatting tag
+ Formatting options
- | Optional formatting tag |
+ Formatting option |
Comment |
| .format(args) |
- Format the value as a string, according to a set of optional args (see below). |
+
+ Format the value as a string, according to a set of optional args
+ (see below).
+ |
+
+
+ | .long_form(args) |
+
+ Format delta times in the "long form", according to a set of optional
+ args (see below).
+ |
| .ordinal_compass |
@@ -460,16 +470,6 @@ A variety of tags and arguments are available to you to customize the formatting
configuration file skin.conf.
-
- | .long_form |
-
- Format delta times in the "long form". A "delta time" is the difference between two times. An
- example is the amount of uptime (difference between start and current time). By default, this will
- be formatted as the number of elapsed seconds (e.g., 45000 seconds). The "long form" breaks the time down into constituent time
- elements (e.g., 12 hours, 30 minutes, 0 seconds).
- |
-
| .json |
@@ -480,14 +480,17 @@ A variety of tags and arguments are available to you to customize the formatting
| .raw |
Return the value "as is", without being converted to a string and without any formatting applied.
This can be useful for doing arithmetic directly within the templates. You must be prepared to deal
- with a potential None value.
+ with a potential value of None.
|
-The first of these tags (.format()) has the formal structure:
+#### Option `.format()`
+
+The results of a tag can be optionally formatted using option `.format()`. It has the formal
+structure:
.format(format_string=None, None_string=None, add_label=True, localize=True)
@@ -502,9 +505,9 @@ Here is the meaning of each of the optional arguments:
| format_string |
- Use the optional string to format the value. If set to None, then an
- appropriate string format from skin.conf will be used.
- |
+ If set, use the supplied string to format the value. Otherwise, if set to None, then
+ an appropriate value from [Units][[StringFormats]]
+ will be used. |
| None_string |
@@ -532,7 +535,87 @@ Here is the meaning of each of the optional arguments:
If you're willing to honor the ordering of the arguments, the argument name can be omitted.
-### Formatting examples
+#### Option `.long_form()`
+
+The option `.long_form()`, can be used to format delta times. A delta time is the
+difference between two times, for example, the amount of uptime (the difference between start up
+and the current time). By default, this will be formatted as the number of elapsed seconds. For
+example, a template with the following
+
+```
+WeeWX has been up $station.uptime
+```
+
+will result in
+
+
+WeeWX has been up 101100 seconds
+
+
+
+The "long form" breaks the time down into constituent time elements. For example,
+
+```
+WeeWX has been up $station.uptime.long_form
+```
+
+results in
+
+
+WeeWX has been up 1 day, 4 hours, 5 minutes
+
+
+The option `.long_form()` has the formal structure
+
+ .long_form(format_string=None, None_string=None)
+
+Here is the meaning of each of the optional arguments:
+
+
+ Optional arguments for .long_form()
+
+
+ | Optional argument |
+ Comment |
+
+
+ | format_string |
+
+ Use the supplied string to format the value.
+ |
+
+
+ | None_string |
+
+ Should the observation value be NONE, then use the supplied
+ string to format the value (typically, something like "N/A").
+ |
+
+
+
+
+The argument `format_string` uses special symbols to represent its constitutent components. Here's
+what they mean:
+
+| Symbol | Meaning |
+|----------------|-----------------------------|
+| `day` | The number of days |
+| `hour` | The number of hours |
+| `minute` | The number of minutes |
+| `second` | The number of seconds |
+| `day_label` | The label used for days |
+| `hour_label` | The label used for hours |
+| `minute_label` | The label used for minutes |
+| `second_label` | The label used for seconds |
+
+Putting this together, the example above could be written
+
+```
+WeeWX has been up $station.uptime.long_form(format_string="%(day)d%(day_label)s, %(hour)d%(hour_label)s, %(minute)d%(minute_label)s")
+```
+
+
+#### Formatting examples
This section gives a number of example tags, and their expected output. The following values are assumed:
@@ -568,6 +651,11 @@ This section gives a number of example tags, and their expected output. The foll
1270250700 |
+
+ |
+ uptime
+ |
+ 101100 seconds |
Here are the examples:
@@ -731,12 +819,36 @@ Here are the examples:
Value in degrees Celsius, rounded to two decimal digits, then converted to a JSON string.
+
+ | $station.uptime |
+ 101100 seconds |
+ str |
+
+ WeeWX uptime.
+ |
+
+
+ | $station.uptime.hour |
+ 28.1 hours |
+ str |
+
+ WeeWX uptime, with unit conversion to hours.
+ |
+
+
+ | $station.uptime.long_form |
+ 1 day, 4 hours, 5 minutes |
+ str |
+
+ WeeWX uptime with "long form" formatting.
+ |
+
+
-Note that the same formatting conventions can be used for aggregation periods, such as `$month`, as well as `$current`.
-### Start, end, and dateTime
+### Start, end, and `dateTime`
While not an observation type, in many ways the time of an observation, `dateTime`, can be treated as one. A tag such as
@@ -760,7 +872,7 @@ produces
09-Jan-2010 12:30
-For _aggregation periods_, such as `$month`, you can request the _start_, _end_, or _length _of the period, by using suffixes `.start`, `.end`, or `.length`, respectively. For example,
+For _aggregation periods_, such as `$month`, you can request the _start_, _end_, or _length_ of the period, by using suffixes `.start`, `.end`, or `.length`, respectively. For example,
The current month runs from $month.start to $month.end and has $month.length.format("%(day)d %(day_label)s").
@@ -788,7 +900,7 @@ The tag `$trend` is available for time trends, such as changes in barometric pre
| `$trend.time_delta` | 10800 secs |
| `$trend.time_delta.hour` | 3 hrs |
-Note how you can explicitly specify a value in the tag itself (2nd row in the table above). If you do not specify a value, then a default time interval, set by option [time_delta](../options_ref/#trend) in the skin configuration file, will be used. This value can be retrieved by using the syntax `$trend.time_delta` (4th row in the table).
+Note how you can explicitly specify a time interval in the tag itself (2nd row in the table above). If you do not specify a value, then a default time interval, set by option [time_delta](../options_ref/#trend) in the skin configuration file, will be used. This value can be retrieved by using the syntax `$trend.time_delta` (4th row in the table).
For example, the template expression