[PATCH v2] [media] doc-rst: Don't use captions for examples

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxxxxxxxx>
---
 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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux