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

[Roland privat]

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 at proxmox.com>:
> 
> 
> Some small comments bellow.
> 
> Alexander Abraham <a.abraham at 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 at 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 at lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
>