merged the latest changes (grammar & style fix) and pre-latest changes (C & old…

merged the latest changes (grammar & style fix) and pre-latest changes (C & old Python interface and relocated short descriptions). Also, made some additional corrections

modules/highgui/doc/reading_and_writing_images_and_video.rst

@@ -3,17 +3,13 @@ Reading and Writing Images and Video
 
 .. highlight:: cpp
 
-.. index:: imdecode
-
-.. _imdecode:
-
 imdecode
 ------------
-.. ocv:function:: Mat imdecode( InputArray buf,  int flags )
+Reads an image from a buffer in memory.
 
-    Reads an image from a buffer in the memory.
+.. ocv:function:: Mat imdecode( InputArray buf,  int flags )
 
-    :param buf: Input array of a vector of bytes.
+    :param buf: Input array of vector of bytes.
 
     :param flags: The same flags as in  :ocv:func:`imread` .
     
@@ -23,15 +19,11 @@ If the buffer is too short or contains invalid data, the empty matrix is returne
 See
 :ocv:func:`imread` for the list of supported formats and flags description.
 
-.. index:: imencode
-
-.. _imencode:
-
 imencode
 ------------
-.. ocv:function:: bool imencode( const string& ext, InputArray img, vector<uchar>& buf, const vector<int>& params=vector<int>())
+Encodes an image into a memory buffer.
 
-    Encodes an image into a memory buffer.
+.. ocv:function:: bool imencode( const string& ext, InputArray img, vector<uchar>& buf, const vector<int>& params=vector<int>())
 
     :param ext: File extension that defines the output format.
 
@@ -45,59 +37,51 @@ The function compresses the image and stores it in the memory buffer that is res
 See
 :ocv:func:`imwrite` for the list of supported formats and flags description.
 
-.. index:: imread
-
-.. _imread:
-
 imread
 ----------
-.. ocv:function:: Mat imread( const string& filename, int flags=1 )
+Loads an image from a file.
 
-    Loads an image from a file.
+.. ocv:function:: Mat imread( const string& filename, int flags=1 )
 
-    :param filename: Name of a file to be loaded.
+    :param filename: Name of file to be loaded.
 
     :param flags: Flags specifying the color type of a loaded image:
 
-        * **>0**  Load a 3-channel color image.
+        * **>0**  Return a 3-channel color image
 
-        * **=0** Load a grayscale image.
+        * **=0**  Return a grayscale image
 
-        * **<0** Load the image as is. Note that in the current implementation the alpha channel, if any, is stripped from the output image. For example, a 4-channel RGBA image is loaded as RGB if  :math:`flags\ge0` .
+        * **<0**  Return the loaded image as is. Note that in the current implementation the alpha channel, if any, is stripped from the output image. For example, a 4-channel RGBA image is loaded as RGB if  :math:`flags\ge0` .
 
-The function ``imread`` loads an image from the specified file and returns it. If the image cannot be read (because of a missing file, improper permissions, unsupported or invalid format), the function returns an empty matrix ( ``Mat::data==NULL`` ). Currently, the following file formats are supported:
+The function ``imread`` loads an image from the specified file and returns it. If the image cannot be read (because of missing file, improper permissions, unsupported or invalid format), the function returns an empty matrix ( ``Mat::data==NULL`` ). Currently, the following file formats are supported:
 
  * Windows bitmaps - ``*.bmp, *.dib`` (always supported)
 
- * JPEG files - ``*.jpeg, *.jpg, *.jpe`` (see the *Notes* below)
+ * JPEG files - ``*.jpeg, *.jpg, *.jpe`` (see the *Notes* section)
 
- * JPEG 2000 files - ``*.jp2`` (see the *Notes* below)
+ * JPEG 2000 files - ``*.jp2`` (see the *Notes* section)
 
- * Portable Network Graphics - ``*.png`` (see the *Notes* below)
+ * Portable Network Graphics - ``*.png`` (see the *Notes* section)
 
  * Portable image format - ``*.pbm, *.pgm, *.ppm``     (always supported)
 
  * Sun rasters - ``*.sr, *.ras``     (always supported)
 
- * TIFF files - ``*.tiff, *.tif`` (see the *Notes* below)
+ * TIFF files - ``*.tiff, *.tif`` (see the *Notes* section)
 
 .. note::
 
     * The function determines the type of an image by the content, not by the file extension.
 
-	* On Microsoft Windows* OS and MacOSX*, the codecs shipped with an OpenCV image ( ``libjpeg``, ``libpng``, ``libtiff``, and ``libjasper``) are used by default. So, OpenCV can always read JPEGs, PNGs, and TIFFs. On MacOSX, there is also an option to use native MacOSX image readers. But beware that currently these native image loaders give images with different pixel values because of the color management embedded into MacOSX.
-
-	* On Linux*, BSD flavors and other Unix-like open-source operating systems, OpenCV looks for codecs supplied with an OS image. Install the relevant packages (do not forget the development files, for example, ``libjpeg-dev``, in Debian* and Ubuntu*) to get the codec support or turn on the ``OPENCV_BUILD_3RDPARTY_LIBS`` flag in CMake.
+    * On Microsoft Windows* OS and MacOSX*, the codecs shipped with an OpenCV image (libjpeg, libpng, libtiff, and libjasper) are used by default. So, OpenCV can always read JPEGs, PNGs, and TIFFs. On MacOSX, there is also an option to use native MacOSX image readers. But beware that currently these native image loaders give images with different pixel values because of the color management embedded into MacOSX.
 
-.. index:: imwrite
-
-.. _imwrite:
+    * On Linux*, BSD flavors and other Unix-like open-source operating systems, OpenCV looks for codecs supplied with an OS image. Install the relevant packages (do not forget the development files, for example, "libjpeg-dev", in Debian* and Ubuntu*) to get the codec support or turn on the ``OPENCV_BUILD_3RDPARTY_LIBS`` flag in CMake.
 
 imwrite
 -----------
-.. ocv:function:: bool imwrite( const string& filename, InputArray img, const vector<int>& params=vector<int>())
+Saves an image to a specified file.
 
-    Saves an image to a specified file.
+.. ocv:function:: bool imwrite( const string& filename, InputArray img, const vector<int>& params=vector<int>())
 
     :param filename: Name of the file.
 
@@ -116,15 +100,11 @@ The function ``imwrite`` saves the image to the specified file. The image format
 :ocv:func:`Mat::convertTo` , and
 :ocv:func:`cvtColor` to convert it before saving. Or, use the universal XML I/O functions to save the image to XML or YAML format.
 
-.. index:: VideoCapture
-
-.. _VideoCapture:
-
 VideoCapture
 ------------
 .. ocv:class:: VideoCapture
 
-Class for video capturing from video files or cameras. ::
+Class for video capturing from video files or cameras ::
 
     class VideoCapture
     {
@@ -172,7 +152,7 @@ Class for video capturing from video files or cameras. ::
     };
 
 
-The class provides C++ video capturing API. Use the class as follows: ::
+The class provides C++ video capturing API. Here is how the class can be used: ::
 
     #include "cv.h"
     #include "highgui.h"
@@ -202,35 +182,30 @@ The class provides C++ video capturing API. Use the class as follows: ::
     }
 
 
-.. index:: VideoCapture::VideoCapture
-
-.. _VideoCapture::VideoCapture:
-
 VideoCapture::VideoCapture
 ------------------------------
+VideoCapture constructors.
+
 .. ocv:function:: VideoCapture::VideoCapture()
 
 .. ocv:function:: VideoCapture::VideoCapture(const string& filename)
 
 .. ocv:function:: VideoCapture::VideoCapture(int device)
 
-	Provides VideoCapture constructors.
-
-    :param filename: Name of an opened video file.
+    :param filename: name of the opened video file
 
-    :param device: ID of an opened video capturing device (a camera index).
+    :param device: id of the opened video capturing device (i.e. a camera index).
 
-.. index:: VideoCapture::get
-
-.. _VideoCapture::get:
 
 VideoCapture::get
 ---------------------
+Returns the specified ``VideoCapture`` property 
+
 .. ocv:function:: double VideoCapture::get(int property_id)
 
     :param property_id: Property identifier. It can be one of the following:
 
-        * **CV_CAP_PROP_POS_MSEC** Current position of the film in milliseconds or video capture timestamp.
+        * **CV_CAP_PROP_POS_MSEC** Current position of the video file in milliseconds or video capture timestamp.
 
         * **CV_CAP_PROP_POS_FRAMES** 0-based index of the frame to be decoded/captured next.
 
@@ -264,26 +239,22 @@ VideoCapture::get
 
         * **CV_CAP_PROP_CONVERT_RGB** Boolean flags indicating whether images should be converted to RGB.
 
-        * **CV_CAP_PROP_WHITE_BALANCE** Currently not supported.
-
-        * **CV_CAP_PROP_RECTIFICATION** TOWRITE (Note: only supported by DC1394 v 2.x backend currently)
-
+        * **CV_CAP_PROP_WHITE_BALANCE** Currently not supported
 
-.. note:: When querying a property that is not supported by the backend used by the ``VideoCapture`` class, value 0 is returned.
+        * **CV_CAP_PROP_RECTIFICATION** Rectification flag for stereo cameras (note: only supported by DC1394 v 2.x backend currently)
 
-.. index:: VideoCapture::set
 
-.. _VideoCapture::set:
+**Note**: When querying a property that is not supported by the backend used by the ``VideoCapture`` class, value 0 is returned.
 
 VideoCapture::set
 ---------------------
-.. ocv:function:: bool VideoCapture::set(int property_id, double value)
+Sets a property in the ``VideoCapture``.
 
-    Sets a property in the VideoCapture backend.
+.. ocv:function:: bool VideoCapture::set(int property_id, double value)
 
     :param property_id: Property identifier. It can be one of the following:
 
-        * **CV_CAP_PROP_POS_MSEC** Current position of the film in milliseconds or video capture timestamp.
+        * **CV_CAP_PROP_POS_MSEC** Current position of the video file in milliseconds.
 
         * **CV_CAP_PROP_POS_FRAMES** 0-based index of the frame to be decoded/captured next.
 
@@ -317,18 +288,12 @@ VideoCapture::set
 
         * **CV_CAP_PROP_CONVERT_RGB** Boolean flags indicating whether images should be converted to RGB.
 
-        * **CV_CAP_PROP_WHITE_BALANCE** Currently not supported
+        * **CV_CAP_PROP_WHITE_BALANCE** Currently unsupported
 
-        * **CV_CAP_PROP_RECTIFICATION** TOWRITE (Note: only supported by DC1394 v 2.x backend currently)
+        * **CV_CAP_PROP_RECTIFICATION** Rectification flag for stereo cameras (note: only supported by DC1394 v 2.x backend currently)
 
     :param value: Value of the property.
 
-
-
-.. index:: VideoWriter
-
-.. _VideoWriter:
-
 VideoWriter
 -----------
 .. ocv:class:: VideoWriter
@@ -366,5 +331,6 @@ Video writer class. ::
         ...
     };
 
+For more detailed description see http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoWriter
 ..