Message-ID: <871psml4t7.fsf@trenco.lwn.net>
Date: Sun, 18 May 2025 02:08:04 -0600
From: Jonathan Corbet <corbet@....net>
To: Hanne-Lotta Mäenpää <hannelotta@...il.com>,
 mchehab@...nel.org,
 ribalda@...omium.org, hverkuil@...all.nl, hljunggr@...co.com,
 dave.jiang@...el.com, jgg@...pe.ca, saeedm@...dia.com,
 Jonathan.Cameron@...wei.com, ilpo.jarvinen@...ux.intel.com,
 mario.limonciello@....com, W_Armin@....de, mpearson-lenovo@...ebb.ca
Cc: linux-media@...r.kernel.org, linux-kernel@...r.kernel.org,
 linux-kernel-mentees@...ts.linux.dev, Hanne-Lotta Mäenpää
 <hannelotta@...il.com>
Subject: Re: [PATCH 2/4] docs: Improve grammar, formatting in Video4Linux

Thanks for working to improve our documentation!

Hanne-Lotta Mäenpää <hannelotta@...il.com> writes:

> Fix typos, punctuation and improve grammar and formatting
> in documentation for Video4Linux (V4L).
>
> Signed-off-by: Hanne-Lotta Mäenpää <hannelotta@...il.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.

>  .. _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?

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

Thanks,

jon

Powered by blists - more mailing lists