* [PATCH v2] [media] doc-rst: Don't use captions for examples
@ 2016-07-10 12:16 Mauro Carvalho Chehab
0 siblings, 0 replies; only message in thread
From: Mauro Carvalho Chehab @ 2016-07-10 12:16 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Linux Media Mailing List,
Mauro Carvalho Chehab, Jonathan Corbet, Markus Heiser, linux-doc
Unfortunately, captions are new on Sphinx for c blocks: it was
added only on version 1.3. Also, it were already bad enough
not being able to auto-numerate them.
So, let's give up and use, instead, titles before the examples.
Not much is lost, and, as a side track, we don't need to
numerate them anymore.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/dvbproperty.rst | 7 ++++++-
Documentation/media/uapi/dvb/examples.rst | 8 ++++----
Documentation/media/uapi/v4l/audio.rst | 8 ++++++--
Documentation/media/uapi/v4l/control.rst | 11 ++++++++---
Documentation/media/uapi/v4l/crop.rst | 17 +++++++++++++----
Documentation/media/uapi/v4l/dev-osd.rst | 3 ++-
Documentation/media/uapi/v4l/dmabuf.rst | 10 +++++++---
Documentation/media/uapi/v4l/mmap.rst | 7 +++++--
Documentation/media/uapi/v4l/selection-api-006.rst | 9 ++++++---
Documentation/media/uapi/v4l/standard.rst | 9 ++++++---
Documentation/media/uapi/v4l/userp.rst | 3 ++-
Documentation/media/uapi/v4l/video.rst | 8 ++++++--
12 files changed, 71 insertions(+), 29 deletions(-)
diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst
index 9b3782c5bb44..3c348e585729 100644
--- a/Documentation/media/uapi/dvb/dvbproperty.rst
+++ b/Documentation/media/uapi/dvb/dvbproperty.rst
@@ -48,8 +48,13 @@ symbol rate of 5.217 Mbauds, those properties should be sent to
- :ref:`DTV_TUNE <DTV-TUNE>`
-The code that would do the above is:
+The code that would that would do the above is show in
+:ref:`dtv-prop-example`.
+.. _dtv-prop-example:
+
+Example: Setting digital TV frontend properties
+===============================================
.. code-block:: c
diff --git a/Documentation/media/uapi/dvb/examples.rst b/Documentation/media/uapi/dvb/examples.rst
index 64e029ecd047..ead3ddf764c0 100644
--- a/Documentation/media/uapi/dvb/examples.rst
+++ b/Documentation/media/uapi/dvb/examples.rst
@@ -17,8 +17,8 @@ updated/recommended examples.
.. _tuning:
-Tuning
-======
+Example: Tuning
+===============
We will start with a generic tuning subroutine that uses the frontend
and SEC, as well as the demux devices. The example is given for QPSK
@@ -238,8 +238,8 @@ switch, and weather conditions this may be necessary.
.. _the_dvr_device:
-The DVR device
-==============
+Example: The DVR device
+========================
The following program code shows how to use the DVR device for
recording.
diff --git a/Documentation/media/uapi/v4l/audio.rst b/Documentation/media/uapi/v4l/audio.rst
index 71502f0bf8bd..47f8334f071e 100644
--- a/Documentation/media/uapi/v4l/audio.rst
+++ b/Documentation/media/uapi/v4l/audio.rst
@@ -54,8 +54,10 @@ in the struct :ref:`v4l2_capability <v4l2-capability>` returned by
the :ref:`VIDIOC_QUERYCAP` ioctl.
+Example: Information about the current audio input
+==================================================
+
.. code-block:: c
- :caption: Example 1.3. Information about the current audio input
struct v4l2_audio audio;
@@ -69,8 +71,10 @@ the :ref:`VIDIOC_QUERYCAP` ioctl.
printf("Current input: %s\\n", audio.name);
+Example: Switching to the first audio input
+===========================================
+
.. code-block:: c
- :caption: Example 1.4. Switching to the first audio input
struct v4l2_audio audio;
diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst
index 6cf218ab36fb..feb55ac14377 100644
--- a/Documentation/media/uapi/v4l/control.rst
+++ b/Documentation/media/uapi/v4l/control.rst
@@ -373,8 +373,10 @@ more menu type controls.
.. _enum_all_controls:
+Example: Enumerating all user controls
+======================================
+
.. code-block:: c
- :caption: Example 1.8. Enumerating all user controls
struct v4l2_queryctrl queryctrl;
@@ -438,8 +440,10 @@ more menu type controls.
}
+Example: Enumerating all user controls (alternative)
+====================================================
+
.. code-block:: c
- :caption: Example 1.9. Enumerating all user controls (alternative)
memset(&queryctrl, 0, sizeof(queryctrl));
@@ -462,9 +466,10 @@ more menu type controls.
exit(EXIT_FAILURE);
}
+Example: Changing controls
+==========================
.. code-block:: c
- :caption: Example 1.10. Changing controls
struct v4l2_queryctrl queryctrl;
struct v4l2_control control;
diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst
index ed43b36c51d8..51b19491c302 100644
--- a/Documentation/media/uapi/v4l/crop.rst
+++ b/Documentation/media/uapi/v4l/crop.rst
@@ -147,8 +147,10 @@ ensure the parameters are suitable before starting I/O.
**NOTE:** on the next two examples, a video capture device is assumed;
change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.
+Example: Resetting the cropping parameters
+==========================================
+
.. code-block:: c
- :caption: Example 1.11. Resetting the cropping parameters
struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
@@ -173,8 +175,11 @@ change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.
exit (EXIT_FAILURE);
}
+
+Example: Simple downscaling
+===========================
+
.. code-block:: c
- :caption: Example 1.12. Simple downscaling
struct v4l2_cropcap cropcap;
struct v4l2_format format;
@@ -199,10 +204,12 @@ change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.
/* We could check the actual image size now, the actual scaling factor
or if the driver can scale at all. */
+Example: Selecting an output area
+=================================
+
**NOTE:** This example assumes an output device.
.. code-block:: c
- :caption: Example 1.13. Selecting an output area
struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
@@ -236,10 +243,12 @@ change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.
exit (EXIT_FAILURE);
}
+Example: Current scaling factor and pixel aspect
+================================================
+
**NOTE:** This example assumes a video capture device.
.. code-block:: c
- :caption: Example 1.14. Current scaling factor and pixel aspect
struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
diff --git a/Documentation/media/uapi/v4l/dev-osd.rst b/Documentation/media/uapi/v4l/dev-osd.rst
index b9b53fd7eb5d..98570cea63a5 100644
--- a/Documentation/media/uapi/v4l/dev-osd.rst
+++ b/Documentation/media/uapi/v4l/dev-osd.rst
@@ -50,9 +50,10 @@ standard. A V4L2 driver may reject attempts to change the video standard
(or any other ioctl which would imply a framebuffer size change) with an
``EBUSY`` error code until all applications closed the framebuffer device.
+Example: Finding a framebuffer device for OSD
+---------------------------------------------
.. code-block:: c
- :caption: Example 4.1. Finding a framebuffer device for OSD
#include <linux/fb.h>
diff --git a/Documentation/media/uapi/v4l/dmabuf.rst b/Documentation/media/uapi/v4l/dmabuf.rst
index 474d8c021507..57917fb98c7a 100644
--- a/Documentation/media/uapi/v4l/dmabuf.rst
+++ b/Documentation/media/uapi/v4l/dmabuf.rst
@@ -37,8 +37,10 @@ driver must be switched into DMABUF I/O mode by calling the
:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type.
+Example: Initiating streaming I/O with DMABUF file descriptors
+==============================================================
+
.. code-block:: c
- :caption: Example 3.4. Initiating streaming I/O with DMABUF file descriptors
struct v4l2_requestbuffers reqbuf;
@@ -62,9 +64,10 @@ buffers, every plane can be associated with a different DMABUF
descriptor. Although buffers are commonly cycled, applications can pass
a different DMABUF descriptor at each :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call.
+Example: Queueing DMABUF using single plane API
+===============================================
.. code-block:: c
- :caption: Example 3.5. Queueing DMABUF using single plane API
int buffer_queue(int v4lfd, int index, int dmafd)
{
@@ -84,9 +87,10 @@ a different DMABUF descriptor at each :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call.
return 0;
}
+Example 3.6. Queueing DMABUF using multi plane API
+==================================================
.. code-block:: c
- :caption: Example 3.6. Queueing DMABUF using multi plane API
int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
{
diff --git a/Documentation/media/uapi/v4l/mmap.rst b/Documentation/media/uapi/v4l/mmap.rst
index f7fe26e7ca43..b01f4486499a 100644
--- a/Documentation/media/uapi/v4l/mmap.rst
+++ b/Documentation/media/uapi/v4l/mmap.rst
@@ -52,9 +52,10 @@ allocated in physical memory, as opposed to virtual memory, which can be
swapped out to disk. Applications should free the buffers as soon as
possible with the :ref:`munmap() <func-munmap>` function.
+Example: Mapping buffers in the single-planar API
+=================================================
.. code-block:: c
- :caption: Example 3.1. Mapping buffers in the single-planar API
struct v4l2_requestbuffers reqbuf;
struct {
@@ -122,8 +123,10 @@ possible with the :ref:`munmap() <func-munmap>` function.
munmap(buffers[i].start, buffers[i].length);
+Example: Mapping buffers in the multi-planar API
+================================================
+
.. code-block:: c
- :caption: Example 3.2. Mapping buffers in the multi-planar API
struct v4l2_requestbuffers reqbuf;
/* Our current format uses 3 planes per buffer */
diff --git a/Documentation/media/uapi/v4l/selection-api-006.rst b/Documentation/media/uapi/v4l/selection-api-006.rst
index b2ac12f2e3d4..67e0e9aed9e8 100644
--- a/Documentation/media/uapi/v4l/selection-api-006.rst
+++ b/Documentation/media/uapi/v4l/selection-api-006.rst
@@ -8,9 +8,10 @@ Examples
``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices; change target to
``V4L2_SEL_TGT_COMPOSE_*`` family to configure composing area)
+Example: Resetting the cropping parameters
+==========================================
.. code-block:: c
- :caption: Example 1.15. Resetting the cropping parameters
struct v4l2_selection sel = {
.type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
@@ -27,9 +28,10 @@ Examples
Setting a composing area on output of size of *at most* half of limit
placed at a center of a display.
+Example: Simple downscaling
+===========================
.. code-block:: c
- :caption: Example 1.16. Simple downscaling
struct v4l2_selection sel = {
.type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
@@ -55,9 +57,10 @@ placed at a center of a display.
A video output device is assumed; change ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
for other devices
+Example: Querying for scaling factors
+=====================================
.. code-block:: c
- :caption: Example 1.17. Querying for scaling factors
struct v4l2_selection compose = {
.type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
diff --git a/Documentation/media/uapi/v4l/standard.rst b/Documentation/media/uapi/v4l/standard.rst
index 538588eef317..529891cf3af2 100644
--- a/Documentation/media/uapi/v4l/standard.rst
+++ b/Documentation/media/uapi/v4l/standard.rst
@@ -64,9 +64,10 @@ Applications can make use of the :ref:`input-capabilities` and
:ref:`output-capabilities` flags to determine whether the video
standard ioctls can be used with the given input or output.
+Example: Information about the current video standard
+=====================================================
.. code-block:: c
- :caption: Example 1.5. Information about the current video standard
v4l2_std_id std_id;
struct v4l2_standard standard;
@@ -100,9 +101,10 @@ standard ioctls can be used with the given input or output.
exit(EXIT_FAILURE);
}
+Example: Listing the video standards supported by the current input
+===================================================================
.. code-block:: c
- :caption: Example 1.6. Listing the video standards supported by the current input
struct v4l2_input input;
struct v4l2_standard standard;
@@ -139,9 +141,10 @@ standard ioctls can be used with the given input or output.
exit(EXIT_FAILURE);
}
+Example: Selecting a new video standard
+=======================================
.. code-block:: c
- :caption: Example 1.7. Selecting a new video standard
struct v4l2_input input;
v4l2_std_id std_id;
diff --git a/Documentation/media/uapi/v4l/userp.rst b/Documentation/media/uapi/v4l/userp.rst
index 2f0002bfbc3f..0871c204dc6c 100644
--- a/Documentation/media/uapi/v4l/userp.rst
+++ b/Documentation/media/uapi/v4l/userp.rst
@@ -26,9 +26,10 @@ No buffers (planes) are allocated beforehand, consequently they are not
indexed and cannot be queried like mapped buffers with the
:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl.
+Example: Initiating streaming I/O with user pointers
+====================================================
.. code-block:: c
- :caption: Example 3.3. Initiating streaming I/O with user pointers
struct v4l2_requestbuffers reqbuf;
diff --git a/Documentation/media/uapi/v4l/video.rst b/Documentation/media/uapi/v4l/video.rst
index e38ebe192614..d3f00715fbc1 100644
--- a/Documentation/media/uapi/v4l/video.rst
+++ b/Documentation/media/uapi/v4l/video.rst
@@ -28,8 +28,10 @@ applications call the :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` and
implement all the input ioctls when the device has one or more inputs,
all the output ioctls when the device has one or more outputs.
+Example: Information about the current video input
+==================================================
+
.. code-block:: c
- :caption: Example 1.1. Information about the current video input
struct v4l2_input input;
int index;
@@ -50,8 +52,10 @@ all the output ioctls when the device has one or more outputs.
printf("Current input: %s\\n", input.name);
+Example: Switching to the first video input
+===========================================
+
.. code-block:: c
- :caption: Example 1.2. Switching to the first video input
int index;
--
2.7.4
^ permalink raw reply related [flat|nested] only message in thread
only message in thread, other threads:[~2016-07-10 12:16 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-07-10 12:16 [PATCH v2] [media] doc-rst: Don't use captions for examples Mauro Carvalho Chehab
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.