[pve-devel] [PATCH pve-docs] fix #4554: Elaborated on the purpose of different output formats

[pve-devel] [PATCH pve-docs] fix #4554: Elaborated on the purpose of different output formats

[Alexander Abraham]

Elaborated on the intended differences between the output
formats "text" and "json" for the "--output-format" option
of the "pvesh" utility.

Signed-off-by: Alexander Abraham <a.abraham@proxmox.com>
---
 output-format.adoc | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/output-format.adoc b/output-format.adoc
index b3eb3c4..cb846ee 100644
--- a/output-format.adoc
+++ b/output-format.adoc
@@ -8,9 +8,15 @@ FORMAT_OPTIONS
 endif::manvolnum[]
 
 It is possible to specify the output format using the
-`--output-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:
+`--output-format` parameter. The default format, 'text', uses ASCII art
+to draw nice borders around tables. Different output formats, such as
+"text" or "json", provide different functionality for different use
+cases. The `text` output format is supposed to present easily-glanceable
+information in a human-readable format. The goal of the `json` output
+is that the output is parseable and processable by different tools.
+
+The `text` output format 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/minute/second count, i.e `1d 5h`.
-- 
2.39.5



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH pve-docs] fix #4554: Elaborated on the purpose of different output formats

[Maximiliano Sandoval]

Some small comments bellow.

Alexander Abraham <a.abraham@proxmox.com> writes:

> Elaborated on the intended differences between the output
> formats "text" and "json" for the "--output-format" option
> of the "pvesh" utility.
>
> Signed-off-by: Alexander Abraham <a.abraham@proxmox.com>
> ---
>  output-format.adoc | 12 +++++++++---
>  1 file changed, 9 insertions(+), 3 deletions(-)
>
> diff --git a/output-format.adoc b/output-format.adoc
> index b3eb3c4..cb846ee 100644
> --- a/output-format.adoc
> +++ b/output-format.adoc
> @@ -8,9 +8,15 @@ FORMAT_OPTIONS
>  endif::manvolnum[]
>
>  It is possible to specify the output format using the
> -`--output-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:
> +`--output-format` parameter. The default format, 'text', uses ASCII art
> +to draw nice borders around tables. Different output formats, such as
> +"text" or "json", provide different functionality for different use
> +cases. The `text` output format is supposed to present easily-glanceable

I am not sure if glanceable is correct. I would suggest to rephrase this.

> +information in a human-readable format. The goal of the `json` output
> +is that the output is parseable and processable by different tools.

This should be "parsable".

> +
> +The `text` output format additionally transforms some values into
> +human-readable text, for example:
>
>  - Unix epoch is displayed as ISO 8601 date string.

"... as a ISO...".

>  - Durations are displayed as week/day/hour/minute/second count, i.e `1d 5h`.

"e.g." or "for example" are more appropriate here.


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH pve-docs] fix #4554: Elaborated on the purpose of different output formats

[Roland privat via pve-devel]

[-- Attachment #1: Type: message/rfc822, Size: 7889 bytes --]

From: Roland privat <devzero@web.de>
To: Proxmox VE development discussion <pve-devel@lists.proxmox.com>
Cc: Alexander Abraham <a.abraham@proxmox.com>
Subject: Re: [pve-devel] [PATCH pve-docs] fix #4554: Elaborated on the purpose of different output formats
Date: Mon, 10 Feb 2025 11:53:53 +0100
Message-ID: <8117A399-60F9-489F-B1E0-095DCF0F0631@web.de>

perhaps it would be useful to mention,  that default output only prints a subset of the available information.

also see https://bugzilla.proxmox.com/show_bug.cgi?id=4554

roland

> Am 10.02.2025 um 11:50 schrieb Maximiliano Sandoval <m.sandoval@proxmox.com>:
> 
> 
> Some small comments bellow.
> 
> Alexander Abraham <a.abraham@proxmox.com> writes:
> 
>> Elaborated on the intended differences between the output
>> formats "text" and "json" for the "--output-format" option
>> of the "pvesh" utility.
>> 
>> Signed-off-by: Alexander Abraham <a.abraham@proxmox.com>
>> ---
>> output-format.adoc | 12 +++++++++---
>> 1 file changed, 9 insertions(+), 3 deletions(-)
>> 
>> diff --git a/output-format.adoc b/output-format.adoc
>> index b3eb3c4..cb846ee 100644
>> --- a/output-format.adoc
>> +++ b/output-format.adoc
>> @@ -8,9 +8,15 @@ FORMAT_OPTIONS
>> endif::manvolnum[]
>> 
>> It is possible to specify the output format using the
>> -`--output-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:
>> +`--output-format` parameter. The default format, 'text', uses ASCII art
>> +to draw nice borders around tables. Different output formats, such as
>> +"text" or "json", provide different functionality for different use
>> +cases. The `text` output format is supposed to present easily-glanceable
> 
> I am not sure if glanceable is correct. I would suggest to rephrase this.
> 
>> +information in a human-readable format. The goal of the `json` output
>> +is that the output is parseable and processable by different tools.
> 
> This should be "parsable".
> 
>> +
>> +The `text` output format additionally transforms some values into
>> +human-readable text, for example:
>> 
>> - Unix epoch is displayed as ISO 8601 date string.
> 
> "... as a ISO...".
> 
>> - Durations are displayed as week/day/hour/minute/second count, i.e `1d 5h`.
> 
> "e.g." or "for example" are more appropriate here.
> 
> 
> _______________________________________________
> pve-devel mailing list
> pve-devel@lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
> 

[-- Attachment #2: Type: text/plain, Size: 160 bytes --]

_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel