From 508a8bd7f8b8925766b3a074241fde09c8fb35d8 Mon Sep 17 00:00:00 2001
From: Dietmar Maurer <dietmar@proxmox.com>
Date: Fri, 27 Jul 2018 09:54:44 +0200
Subject: [PATCH] output-format.adoc: documentation for output format options

---
 gen-output-format-opts.pl | 13 +++++++++++++
 output-format-opts.adoc   | 20 ++++++++++++++++++++
 output-format.adoc        | 23 +++++++++++++++++++++++
 3 files changed, 56 insertions(+)
 create mode 100755 gen-output-format-opts.pl
 create mode 100644 output-format-opts.adoc
 create mode 100644 output-format.adoc

diff --git a/gen-output-format-opts.pl b/gen-output-format-opts.pl
new file mode 100755
index 0000000..69e78a0
--- /dev/null
+++ b/gen-output-format-opts.pl
@@ -0,0 +1,13 @@
+#!/usr/bin/perl
+
+use lib '.';
+use strict;
+use warnings;
+use PVE::JSONSchema;
+use PVE::RESTHandler;
+
+my $prop = $PVE::RESTHandler::standard_output_options;
+
+my $data = PVE::RESTHandler::dump_properties($prop, 'asciidoc', 'config');
+
+print $data;
diff --git a/output-format-opts.adoc b/output-format-opts.adoc
new file mode 100644
index 0000000..fad02c3
--- /dev/null
+++ b/output-format-opts.adoc
@@ -0,0 +1,20 @@
+`human-readable`: `<boolean>` ('default =' `1`)::
+
+Call output rendering functions to produce human readable text.
+
+`noborder`: `<boolean>` ('default =' `1`)::
+
+Do not draw borders (for 'text' format).
+
+`noheader`: `<boolean>` ('default =' `1`)::
+
+Do not show column headers (for 'text' format).
+
+`output-format`: `<json | json-pretty | text | yaml>` ('default =' `text`)::
+
+Output format.
+
+`quiet`: `<boolean>` ::
+
+Suppress printing results.
+
diff --git a/output-format.adoc b/output-format.adoc
new file mode 100644
index 0000000..41c437b
--- /dev/null
+++ b/output-format.adoc
@@ -0,0 +1,23 @@
+ifndef::manvolnum[]
+Output format otions `[FORMAT_OPTIONS]`
+---------------------------------------
+endif::manvolnum[]
+ifdef::manvolnum[]
+FORMAT_OPTIONS
+--------------
+endif::manvolnum[]
+
+It is possible to specify the output format using the
+`--outout-format` parameter. The default format 'text' uses ASCII-art
+to draw nice borders around tables. It additionally transforms some
+values into human-readable text, for example:
+
+- Unix epoch is displayed as ISO 8601 date string.
+- Durations are displayed as week/day/hour/miniute/secound count, i.e `1d 5h`.
+- Byte sizes value include units (`B`, `KiB`, `MiB`, `GiB`, `TiB`, `PiB`).
+- Fractions are display as percentage, i.e. 1.0 is displayed as 100%.
+
+You can also completely suppress output using option `--quiet`.
+
+
+include::output-format-opts.adoc[]
-- 
2.39.2