Re: [PATCH v4 02/15] qapi: expand docs for SEV commands

[Markus Armbruster <armbru@redhat.com>]

Pierrick Bouvier <pierrick.bouvier@linaro.org> writes:

> On 5/27/25 4:26 AM, Markus Armbruster wrote:

[...]

> All good for me.
> The only question that crossed my mind when you asked for those changes previously was: "Why does QAPI has it's own style, and not simply following the QEMU official style?"

Fair question!  It's down to the difference between code and
documentation text.

Humans tend to have trouble following long lines with their eyes (I sure
do).  Typographic manuals suggest to limit columns to roughly 60
characters for exactly that reason[*].

For code, four levels of indentation plus 60 characters of actual text
yields 76.  However, code lines can be awkward to break, and going over
80 can be less bad than an awkward line break.  Use your judgement.

Documentation text, however, tends to be indented much less: 6-10
characters of indentation plus 60 of actual text yields 66-70.  When I
reflowed the entire QAPI schema documentation to stay within that limit
(commit a937b6aa739), not a single line break was awkward.

> In the end, you choose which rules apply to this subsystem, and I have no strong opinion on whether it should be 70, 72 or 80 characters on the line, or if we prefer tabs to spaces (to make some analogy). I just think it's surprising to have a different coding style only here for arbitrary reasons.

I hope you understand my reasons better now :)


[*] https://en.wikipedia.org/wiki/Column_(typography)#Typographic_style