[libcamera-devel] [PATCH 1/5] Documentation: Fix typos and wrong rST syntax for literals
Laurent Pinchart
laurent.pinchart at ideasonboard.com
Fri Mar 19 00:52:38 CET 2021
Hi Nicolas,
Thank you for the patch.
On Thu, Mar 18, 2021 at 06:09:47AM +0100, Sebastian Fricke wrote:
> On 17.03.2021 16:28, Nícolas F. R. A. Prado wrote:
> > Fix some typos and some literals using ` instead of ``.
>
> Thank you for the patch.
> This looks good, I only found a single change that goes against our
> coding style guidelines. With that fixed..
>
> Reviewed-by: Sebastian Fricke <sebastian.fricke at posteo.net>
> >
> > Signed-off-by: Nícolas F. R. A. Prado <nfraprado at collabora.com>
> > ---
> > Documentation/environment_variables.rst | 21 ++++++++++----------
> > Documentation/guides/introduction.rst | 2 +-
> > Documentation/guides/pipeline-handler.rst | 13 ++++++------
> > Documentation/sensor_driver_requirements.rst | 12 +++++------
> > README.rst | 6 +++---
> > 5 files changed, 27 insertions(+), 27 deletions(-)
> >
> > diff --git a/Documentation/environment_variables.rst b/Documentation/environment_variables.rst
> > index 01294d79b9a8..e482c98e5f30 100644
> > --- a/Documentation/environment_variables.rst
> > +++ b/Documentation/environment_variables.rst
> > @@ -35,10 +35,11 @@ Further details
> > Notes about debugging
> > ~~~~~~~~~~~~~~~~~~~~~
> >
> > -The environment variables `LIBCAMERA_LOG_FILE` and `LIBCAMERA_LOG_LEVELS` are
> > -used to modify the destination and verbosity of messages provided by libcamera.
> > +The environment variables ``LIBCAMERA_LOG_FILE`` and ``LIBCAMERA_LOG_LEVELS``
> > +are used to modify the destination and verbosity of messages provided by
> > +libcamera.
> >
> > -The `LIBCAMERA_LOG_LEVELS` variable accepts a comma-separated list of
> > +The ``LIBCAMERA_LOG_LEVELS`` variable accepts a comma-separated list of
> > 'category:level' pairs.
> >
> > The `level <#log-levels>`__ part is mandatory and can either be specified by
> > @@ -61,8 +62,8 @@ within a local environment:
> > LIBCAMERA_LOG_LEVELS=0 \
> > cam --list
> >
> > -Enable full debug output for the categories `Camera` and `V4L2` within a global
> > -environment:
> > +Enable full debug output for the categories ``Camera`` and ``V4L2`` within a
> > +global environment:
> >
> > .. code:: bash
> >
> > @@ -100,10 +101,10 @@ There are two available macros used to assign a category name to a part of the
> > libcamera codebase:
> >
> > LOG_DEFINE_CATEGORY
> > - This macro is required, in order to use the `LOGC` macro for a particular
> > + This macro is required, in order to use the ``LOGC`` macro for a particular
> > category. It can only be used once for each category. If you want to create
> > log messages within multiple compilation units for the same category utilize
> > - the `LOG_DECLARE_CATEGORY` macro, in every file except the definition file.
> > + the ``LOG_DECLARE_CATEGORY`` macro, in every file except the definition file.
> > LOG_DECLARE_CATEGORY
> > Used for sharing an already defined category between multiple separate
> > compilation units.
> > @@ -118,7 +119,7 @@ IPA modules use configuration files to store parameters. The format and
> > contents of the configuration files is specific to the IPA module. They usually
> > contain tuning parameters for the algorithms, in JSON format.
> >
> > -The `LIBCAMERA_IPA_CONFIG_PATH` variable can be used to specify custom
> > +The ``LIBCAMERA_IPA_CONFIG_PATH`` variable can be used to specify custom
> > storage locations to search for those configuration files.
> >
> > `Examples <https://git.libcamera.org/libcamera/libcamera.git/tree/src/ipa/raspberrypi/data>`__
> > @@ -130,5 +131,5 @@ In order to locate the correct IPA module for your hardware, libcamera gathers
> > existing IPA modules from multiple locations. The default locations for this
> > operation are the installed system path (for example on Debian:
> > ``/usr/local/x86_64-pc-linux-gnu/libcamera``) and the build directory.
> > -With the `LIBCAMERA_IPA_MODULE_PATH`, you can specify a non-default
> > -location to search for IPA modules.
> > +With the ``LIBCAMERA_IPA_MODULE_PATH``, you can specify a non-default location
> > +to search for IPA modules.
> > diff --git a/Documentation/guides/introduction.rst b/Documentation/guides/introduction.rst
> > index f34d2cf7cbdc..d3a42a23fa8c 100644
> > --- a/Documentation/guides/introduction.rst
> > +++ b/Documentation/guides/introduction.rst
> > @@ -119,7 +119,7 @@ V4L2 Compatibility Layer
> > V4L2 compatibility is achieved through a shared library that traps all
> > accesses to camera devices and routes them to libcamera to emulate high-level
> > V4L2 camera devices. It is injected in a process address space through
> > - `LD_PRELOAD` and is completely transparent for applications.
> > + ``LD_PRELOAD`` and is completely transparent for applications.
> >
> > The compatibility layer exposes camera device features on a best-effort basis,
> > and aims for the level of features traditionally available from a UVC camera
> > diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst
> > index f4a31d3c9588..43783ec32afa 100644
> > --- a/Documentation/guides/pipeline-handler.rst
> > +++ b/Documentation/guides/pipeline-handler.rst
> > @@ -177,7 +177,7 @@ configuring a build directory.
> > .. _Meson build configuration: https://mesonbuild.com/Configuring-a-build-directory.html
> >
> > To add the new pipeline handler to this list of options, add its directory name
> > -to the libcamera build options in the top level _meson_options.txt_.
> > +to the libcamera build options in the top level ``meson_options.txt``.
> >
> > .. code-block:: none
> >
> > @@ -777,8 +777,7 @@ implementation.
> >
> > .. code-block:: cpp
> >
> > - std::map<V4L2PixelFormat, std::vector<SizeRange>> v4l2Formats =
> > - data->video_->formats();
> > + std::map<V4L2PixelFormat, std::vector<SizeRange>> v4l2Formats = data->video_->formats();
>
> We generally try to keep the 80 column limit for the code as well as the
> documentation. This line is now 91 columns long.
>
> Quote:
> ```
> * 2 "Breaking Long Lines" striving to fit code within 80 columns and
> accepting up to 120 columns when necessary
> ```
> I am not sure if this should be declared necessary.
I'll update this to
std::map<V4L2PixelFormat, std::vector<SizeRange>> v4l2Formats =
data->video_->formats();
> > std::map<PixelFormat, std::vector<SizeRange>> deviceFormats;
> > std::transform(v4l2Formats.begin(), v4l2Formats.end(),
> > std::inserter(deviceFormats, deviceFormats.begin()),
> > @@ -1027,7 +1026,7 @@ Initializing device controls
> > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > Pipeline handlers can optionally initialize the video devices and camera sensor
> > -controls at system configuration time, to make sure to make sure they are
> > +controls at system configuration time, to make sure they are
And I'll reflow this paragraph.
> > defaulted to sane values. Handling of device controls is again performed using
> > the libcamera `controls framework`_.
> >
> > @@ -1240,7 +1239,7 @@ Replace the stubbed contents of ``queueRequestDevice`` with the following:
> > << "Attempt to queue request with invalid stream";
> >
> > return -ENOENT;
> > - }
> > + }
> >
> > int ret = data->video_->queueBuffer(buffer);
> > if (ret < 0)
> > @@ -1396,7 +1395,7 @@ delivered to applications in the same order as they have been submitted.
> > .. _connecting: http://libcamera.org/api-html/classlibcamera_1_1Signal.html#aa04db72d5b3091ffbb4920565aeed382
> >
> > Returning to the ``int VividCameraData::init()`` method, add the following above
> > -the closing ``return 0;`` to connects the pipeline handler ``bufferReady``
> > +the closing ``return 0;`` to connect the pipeline handler ``bufferReady``
> > method to the V4L2 device buffer signal.
> >
> > .. code-block:: cpp
> > @@ -1428,7 +1427,7 @@ code-base.
> > Testing a pipeline handler
> > ~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > -Once you've built the pipeline handler, we ca rebuild the code base, and test
> > +Once you've built the pipeline handler, we can rebuild the code base, and test
> > capture through the pipeline through both of the cam and qcam utilities.
> >
> > .. code-block:: shell
> > diff --git a/Documentation/sensor_driver_requirements.rst b/Documentation/sensor_driver_requirements.rst
> > index 17841ddda5f5..3e800c8e9c13 100644
> > --- a/Documentation/sensor_driver_requirements.rst
> > +++ b/Documentation/sensor_driver_requirements.rst
> > @@ -34,13 +34,13 @@ For RAW sensors, the sensor driver shall support the following V4L2 controls:
> > .. _V4L2_CID_PIXEL_RATE: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-image-process.html
> > .. _V4L2_CID_VBLANK: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-image-source.html
> >
> > -While V4L2 doesn't specify a unit for the `EXPOSURE` control, libcamera requires
> > -it to be expressed as a number of image lines. Camera sensor drivers that do not
> > -comply with this requirement will need to be adapted or will produce incorrect
> > -results.
> > +While V4L2 doesn't specify a unit for the ``EXPOSURE`` control, libcamera
> > +requires it to be expressed as a number of image lines. Camera sensor drivers
> > +that do not comply with this requirement will need to be adapted or will produce
> > +incorrect results.
> >
> > -The `HBLANK`, `PIXEL_RATE` and `VBLANK` controls are used to compute the sensor
> > -output timings.
> > +The ``HBLANK``, ``PIXEL_RATE`` and ``VBLANK`` controls are used to compute the
> > +sensor output timings.
> >
> > Optional Requirements
> > ---------------------
> > diff --git a/README.rst b/README.rst
> > index b48455ab4e67..427dbe9cd798 100644
> > --- a/README.rst
> > +++ b/README.rst
> > @@ -95,9 +95,9 @@ GStreamer can find it.
> >
> > export GST_PLUGIN_PATH=$(pwd)/build/src/gstreamer
> >
> > -The debugging tool `gst-launch-1.0` can be used to construct and pipeline and test
> > -it. The following pipeline will stream from the camera named "Camera 1" onto the
> > -default video display element on your system.
> > +The debugging tool ``gst-launch-1.0`` can be used to construct and pipeline and
s/construct and pipeline/construct a pipeline/
Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> > +test it. The following pipeline will stream from the camera named "Camera 1"
> > +onto the default video display element on your system.
> >
> > .. code::
> >
--
Regards,
Laurent Pinchart
More information about the libcamera-devel
mailing list