Re: [PATCH 2/4] docs: Improve grammar, formatting in Video4Linux

Hanne-Lotta Mäenpää
2025-05-21T15:12:15Z

Hello,

On 5/18/25 11:08, Jonathan Corbet wrote:
> Thanks for working to improve our documentation!
>
> Hanne-Lotta Mäenpää <hannelotta@gmail.com> writes:
>
>> Fix typos, punctuation and improve grammar and formatting
>> in documentation for Video4Linux (V4L).
>>
>> Signed-off-by: Hanne-Lotta Mäenpää <hannelotta@gmail.com>
>> ---
>> .../userspace-api/media/v4l/biblio.rst | 8 ++---
>> .../media/v4l/dev-sliced-vbi.rst | 4 +--
>> .../media/v4l/ext-ctrls-fm-rx.rst | 15 ++++------
>> .../media/v4l/ext-ctrls-fm-tx.rst | 29 +++++++------------
>> .../media/v4l/pixfmt-srggb12p.rst | 4 +--
>> .../media/v4l/pixfmt-srggb14p.rst | 2 +-
>> 6 files changed, 25 insertions(+), 37 deletions(-)
>>
>> diff --git a/Documentation/userspace-api/media/v4l/biblio.rst b/Documentation/userspace-api/media/v4l/biblio.rst
>> index 35674eeae20d..c3f7c466e287 100644
>> --- a/Documentation/userspace-api/media/v4l/biblio.rst
>> +++ b/Documentation/userspace-api/media/v4l/biblio.rst
>> @@ -53,7 +53,7 @@ ISO 13818-1
>>
>> :title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology --- Generic coding of moving pictures and associated audio information: Systems"
>>
>> -:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch)
>> +:author: International Telecommunication Union (http://www.itu.ch), International Organization for Standardization (http://www.iso.ch)
>
> Please do not "fix" the use of either British or American spellings;
> both are explicitly just fine for kernel docs.

Okay, good to know. The ISO name is spelled in two different ways on
this documentation page:

https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/biblio.html

Making them consistent with the official English spelling, which is
mentioned on ISO's website, was my reason to change this.

At any rate, I can leave this change out of the patch.

>
>> .. _mpeg2part2:
>>
>> @@ -63,7 +63,7 @@ ISO 13818-2
>>
>> :title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology --- Generic coding of moving pictures and associated audio information: Video"
>>
>> -:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch)
>> +:author: International Telecommunication Union (http://www.itu.ch), International Organization for Standardization (http://www.iso.ch)
>>
>> .. _itu470:
>>
>> @@ -131,7 +131,7 @@ ITU H.265/HEVC
>>
>> :title: ITU-T Rec. H.265 | ISO/IEC 23008-2 "High Efficiency Video Coding"
>>
>> -:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch)
>> +:author: International Telecommunication Union (http://www.itu.ch), International Organization for Standardization (http://www.iso.ch)
>>
>> .. _jfif:
>>
>> @@ -150,7 +150,7 @@ ITU-T.81
>> ========
>>
>>
>> -:title: ITU-T Recommendation T.81 "Information Technology --- Digital Compression and Coding of Continous-Tone Still Images --- Requirements and Guidelines"
>> +:title: ITU-T Recommendation T.81 "Information Technology --- Digital Compression and Coding of Continuous-Tone Still Images --- Requirements and Guidelines"
>>
>> :author: International Telecommunication Union (http://www.itu.int)
>>
>> diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst
>> index 42cdb0a9f786..96e0e85a822c 100644
>> --- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst
>> +++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst
>> @@ -48,7 +48,7 @@ capabilities, and they may support :ref:`control` ioctls.
>> The :ref:`video standard <standard>` ioctls provide information vital
>> to program a sliced VBI device, therefore must be supported.
>>
>> -.. _sliced-vbi-format-negotitation:
>> +.. _sliced-vbi-format-negotiation:
>>
>> Sliced VBI Format Negotiation
>> =============================
>> @@ -377,7 +377,7 @@ Sliced VBI Data in MPEG Streams
>>
>> If a device can produce an MPEG output stream, it may be capable of
>> providing
>> -:ref:`negotiated sliced VBI services <sliced-vbi-format-negotitation>`
>> +:ref:`negotiated sliced VBI services <sliced-vbi-format-negotiation>`
>> as data embedded in the MPEG stream. Users or applications control this
>> sliced VBI data insertion with the
>> :ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
>> diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst
>> index b6cfc0e823d2..565157709911 100644
>> --- a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst
>> +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst
>> @@ -35,7 +35,7 @@ FM_RX Control IDs
>> description of the correct character encoding for Programme Service
>> name strings. Also from RDS specification, PS is usually a single
>> eight character text. However, it is also possible to find receivers
>> - which can scroll strings sized as 8 x N characters. So, this control
>> + which can scroll strings sized as 8 x N characters. Therefore this control
>
> This kind of change just seems like churn that isn't really improving
> the content?

The content is good already. Here, it is a bit more formal to use the
word therefore, since this is technical documentation, and the word so
is considered more appropriate for informal contexts.

I can leave this change out of the patch series.

>
>> must be configured with steps of 8 characters. The result is it must
>> always contain a string with size multiple of 8.
>>
>> @@ -49,7 +49,7 @@ FM_RX Control IDs
>> Radio Text strings depends on which RDS Block is being used to
>> transmit it, either 32 (2A block) or 64 (2B block). However, it is
>> also possible to find receivers which can scroll strings sized as 32
>> - x N or 64 x N characters. So, this control must be configured with
>> + x N or 64 x N characters. Therefore this control must be configured with
>> steps of 32 or 64 characters. The result is it must always contain a
>> string with size multiple of 32 or 64.
>>
>> @@ -64,17 +64,12 @@ FM_RX Control IDs
>> broadcasts speech. If the transmitter doesn't make this distinction,
>> then it will be set.
>>
>> -``V4L2_CID_TUNE_DEEMPHASIS``
>> - (enum)
>> -
>> -enum v4l2_deemphasis -
>> +``V4L2_CID_TUNE_DEEMPHASIS (enum)``
>> Configures the de-emphasis value for reception. A de-emphasis filter
>> is applied to the broadcast to accentuate the high audio
>> frequencies. Depending on the region, a time constant of either 50
>> - or 75 useconds is used. The enum v4l2_deemphasis defines possible
>> - values for de-emphasis. Here they are:
>> -
>> -
>> + or 75 microseconds is used. The enum v4l2_deemphasis defines possible
>> + values for de-emphasis. They are:
>>
>> .. flat-table::
>> :header-rows: 0
>> diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst
>> index 04c997c9a4c3..aa509039bd27 100644
>> --- a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst
>> +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst
>> @@ -41,7 +41,7 @@ FM_TX Control IDs
>> description of the correct character encoding for Programme Service
>> name strings. Also from RDS specification, PS is usually a single
>> eight character text. However, it is also possible to find receivers
>> - which can scroll strings sized as 8 x N characters. So, this control
>> + which can scroll strings sized as 8 x N characters. Therefore this control
>> must be configured with steps of 8 characters. The result is it must
>> always contain a string with size multiple of 8.
>>
>> @@ -55,7 +55,7 @@ FM_TX Control IDs
>> E of :ref:`iec62106`. The length of Radio Text strings depends on
>> which RDS Block is being used to transmit it, either 32 (2A block)
>> or 64 (2B block). However, it is also possible to find receivers
>> - which can scroll strings sized as 32 x N or 64 x N characters. So,
>> + which can scroll strings sized as 32 x N or 64 x N characters. Therefore
>> this control must be configured with steps of 32 or 64 characters.
>> The result is it must always contain a string with size multiple of
>> 32 or 64.
>> @@ -94,8 +94,8 @@ FM_TX Control IDs
>>
>> ``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)``
>> The alternate frequencies in kHz units. The RDS standard allows for
>> - up to 25 frequencies to be defined. Drivers may support fewer
>> - frequencies so check the array size.
>> + up to 25 frequencies to be defined. Because drivers may support fewer
>> + frequencies, check the array size.
>
> Here too, I'm not sure I see the value in this kind of change.

Similar reason here regarding formal wording.

Again, I can send in a version 2 without this change.

>
> Thanks,
>
> jon

Thank you for reviewing so quickly!

Best regards,

Hanne-Lotta Mäenpää