From eca785450d1c72687817d09259fa7cd33376fafc Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Sun, 25 Apr 2021 21:06:47 -0700 Subject: [PATCH] add caveats to readme and manpage --- CHANGELOG | 3 ++- README.md | 22 ++++++++++++++++------ jc/man/jc.1.gz | Bin 2413 -> 2413 bytes man/jc.1.gz | Bin 2413 -> 2413 bytes templates/readme_template | 22 ++++++++++++++++------ 5 files changed, 34 insertions(+), 13 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 6b2d1df5..09a34a70 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,9 +1,10 @@ jc changelog -20210420 v1.15.3 +20210425 v1.15.3 - Add ufw status command parser tested on linux - Add ufw-appinfo command parser tested on linux - Fix deb package name to conform to standard +- Add Caveats section to readme and manpage 20210418 v1.15.2 - Add systeminfo parser tested on Windows diff --git a/README.md b/README.md index 774d5c4b..7971f582 100644 --- a/README.md +++ b/README.md @@ -62,10 +62,6 @@ The `jc` parsers can also be used as python modules. In this case the output wil ``` Two representations of the data are possible. The default representation uses a strict schema per parser and converts known numbers to int/float JSON values. Certain known values of `None` are converted to JSON `null`, known boolean values are converted, and, in some cases, additional semantic context fields are added. -> Note: Some parsers have calculated epoch timestamp fields added to the output. Unless a timestamp field name has a `_utc` suffix it is considered naive. (i.e. based on the local timezone of the system the `jc` parser was run on). -> -> If a UTC timezone can be detected in the text of the command output, the timestamp will be timezone aware and have a `_utc` suffix on the key name. (e.g. `epoch_utc`) No other timezones are supported for aware timestamps. - To access the raw, pre-processed JSON, use the `-r` cli option or the `raw=True` function parameter in `parse()`. Schemas for each parser can be found at the documentation link beside each parser below. @@ -115,8 +111,6 @@ jc [OPTIONS] COMMAND ``` The JSON output can be compact (default) or pretty formatted with the `-p` option. -> Note: For best results set the `LANG` locale environment variable to `C`. For example, either by setting directly on the command-line: `$ LANG=C date | jc --date`, or by exporting to the environment before running commands: `$ export LANG=C`. - ### Parsers - `--acpi` enables the `acpi` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/acpi)) @@ -232,6 +226,22 @@ Local plugin filenames must be valid python module names, therefore must consist > Note: The application data directory follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) +### Caveats +**Locale:** +For best results set the `LANG` locale environment variable to `C`. For example, either by setting directly on the command-line: +``` +$ LANG=C date | jc --date +``` +or by exporting to the environment before running commands: +``` +$ export LANG=C +``` + +**Timezones:** +Some parsers have calculated epoch timestamp fields added to the output. Unless a timestamp field name has a `_utc` suffix it is considered naive. (i.e. based on the local timezone of the system the `jc` parser was run on). + +If a UTC timezone can be detected in the text of the command output, the timestamp will be timezone aware and have a `_utc`P suffix on the key name. (e.g. `epoch_utc`) No other timezones are supported for aware timestamps. + ## Compatibility Some parsers like `ls`, `ps`, `dig`, etc. will work on any platform. Other parsers that are platform-specific will generate a warning message if they are used on an unsupported platform. To see all parser information, including compatibility, run `jc -ap`. diff --git a/jc/man/jc.1.gz b/jc/man/jc.1.gz index e433338a73ba2862031a26b0d47f537f1f6054dd..e7649408db411859f37259693ce70d782a3e3447 100644 GIT binary patch delta 15 WcmaDW^j3&XzMF$X)@CDHIwt@qDFiIAd^ diff --git a/man/jc.1.gz b/man/jc.1.gz index e433338a73ba2862031a26b0d47f537f1f6054dd..e7649408db411859f37259693ce70d782a3e3447 100644 GIT binary patch delta 15 WcmaDW^j3&XzMF$X)@CDHIwt@qDFiIAd^ diff --git a/templates/readme_template b/templates/readme_template index da61517a..8b94df63 100644 --- a/templates/readme_template +++ b/templates/readme_template @@ -62,10 +62,6 @@ The `jc` parsers can also be used as python modules. In this case the output wil ``` Two representations of the data are possible. The default representation uses a strict schema per parser and converts known numbers to int/float JSON values. Certain known values of `None` are converted to JSON `null`, known boolean values are converted, and, in some cases, additional semantic context fields are added. -> Note: Some parsers have calculated epoch timestamp fields added to the output. Unless a timestamp field name has a `_utc` suffix it is considered naive. (i.e. based on the local timezone of the system the `jc` parser was run on). -> -> If a UTC timezone can be detected in the text of the command output, the timestamp will be timezone aware and have a `_utc` suffix on the key name. (e.g. `epoch_utc`) No other timezones are supported for aware timestamps. - To access the raw, pre-processed JSON, use the `-r` cli option or the `raw=True` function parameter in `parse()`. Schemas for each parser can be found at the documentation link beside each parser below. @@ -115,8 +111,6 @@ jc [OPTIONS] COMMAND ``` The JSON output can be compact (default) or pretty formatted with the `-p` option. -> Note: For best results set the `LANG` locale environment variable to `C`. For example, either by setting directly on the command-line: `$ LANG=C date | jc --date`, or by exporting to the environment before running commands: `$ export LANG=C`. - ### Parsers {% for parser in jc.parsers %} - `{{ parser.argument }}` enables the {{ parser.description }} ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/{{ parser.name }})){% endfor %} @@ -160,6 +154,22 @@ Local plugin filenames must be valid python module names, therefore must consist > Note: The application data directory follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) +### Caveats +**Locale:** +For best results set the `LANG` locale environment variable to `C`. For example, either by setting directly on the command-line: +``` +$ LANG=C date | jc --date +``` +or by exporting to the environment before running commands: +``` +$ export LANG=C +``` + +**Timezones:** +Some parsers have calculated epoch timestamp fields added to the output. Unless a timestamp field name has a `_utc` suffix it is considered naive. (i.e. based on the local timezone of the system the `jc` parser was run on). + +If a UTC timezone can be detected in the text of the command output, the timestamp will be timezone aware and have a `_utc`P suffix on the key name. (e.g. `epoch_utc`) No other timezones are supported for aware timestamps. + ## Compatibility Some parsers like `ls`, `ps`, `dig`, etc. will work on any platform. Other parsers that are platform-specific will generate a warning message if they are used on an unsupported platform. To see all parser information, including compatibility, run `jc -ap`.