all lists on lists.proxmox.com
 help / color / mirror / Atom feed
* [pve-devel] [PATCH pve-docs] fix #4554: Elaborated on the purpose of different output formats
@ 2025-02-10 10:30 Alexander Abraham
  2025-02-10 10:44 ` Maximiliano Sandoval
  0 siblings, 1 reply; 3+ messages in thread
From: Alexander Abraham @ 2025-02-10 10:30 UTC (permalink / raw)
  To: pve-devel; +Cc: 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


^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [pve-devel] [PATCH pve-docs] fix #4554: Elaborated on the purpose of different output formats
  2025-02-10 10:30 [pve-devel] [PATCH pve-docs] fix #4554: Elaborated on the purpose of different output formats Alexander Abraham
@ 2025-02-10 10:44 ` Maximiliano Sandoval
  2025-02-10 10:53   ` Roland privat via pve-devel
  0 siblings, 1 reply; 3+ messages in thread
From: Maximiliano Sandoval @ 2025-02-10 10:44 UTC (permalink / raw)
  To: Proxmox VE development discussion; +Cc: Alexander Abraham


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


^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [pve-devel] [PATCH pve-docs] fix #4554: Elaborated on the purpose of different output formats
  2025-02-10 10:44 ` Maximiliano Sandoval
@ 2025-02-10 10:53   ` Roland privat via pve-devel
  0 siblings, 0 replies; 3+ messages in thread
From: Roland privat via pve-devel @ 2025-02-10 10:53 UTC (permalink / raw)
  To: Proxmox VE development discussion; +Cc: Roland privat, Alexander Abraham

[-- 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

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2025-02-10 11:00 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2025-02-10 10:30 [pve-devel] [PATCH pve-docs] fix #4554: Elaborated on the purpose of different output formats Alexander Abraham
2025-02-10 10:44 ` Maximiliano Sandoval
2025-02-10 10:53   ` Roland privat via pve-devel

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal