Re: [PATCH] docs: correct trailer `key_value_separator` description

From: Brian Lyles <brianmlyles@gmail.com>
Date: Mar 18, 2024, 04:49 UTC
Message-ID: <17bdc28ea2b88503.70b1dd9aae081c6e.203dcd72f6563036@zivdesk>
In-Reply-To: <owly1q8a4qhh.fsf@fine.c.googlers.com>

Hi Linus

On Sat, Mar 16, 2024 at 1:53 AM Linus Arver <linusa@google.com> wrote:

> Nit: This line was modified to have " each" at the end. If you did that
> on the next line, then this diff could have been a touch smaller.

Sure -- it looks like this was a result of applying a different hard-wrap width than the previous author, perhaps? I thought it more prudent to wrap to a consistent length than to be overly concerned about the diff given that it was already a fairly trivial patch. That said, I'm not seeing a recommended wrap width for doc files documented anywhere either. Is there a documented guideline to follow here, both in terms of preferred wrap width as well as when it might be appropriate to stray from it for reasons such as this?

Show 7 quoted lines

> It's probably not worth re-rolling, but a small suggestion I have is to
> simplify the language a bit to reduce repetition, like so:
> 
>     ** 'key_value_separator=<sep>': specify the separator between
>        the key and value of each trailer. Defaults to ": ". Otherwise it
>        shares the same semantics as 'separator=<sep>' above.
>

I do prefer the simplified language. I had initially aimed to simply correct the inaccuracy, but I think that it probably *is* worth a quick re-roll to make this simplification. I will send that out shortly.

-- 
Thank you,
Brian Lyles