[FFmpeg-devel] [PATCH 3/4] doc/muxers: add "Options", "Examples", "Syntax", etc. subsections

Thu Jan 9 12:07:48 CET 2014

On date Wednesday 2014-01-08 21:21:09 -0800, Timothy Gu encoded:
> On Sun, Jan 5, 2014 at 10:46 AM, Stefano Sabatini <stefasab at gmail.com> wrote:
[...] 
> So for <=2 options/examples I don't add new heading.
> 
> Timothy

> From c368f0b9e9a43f794bc2b1751bb3f2430ebca48f Mon Sep 17 00:00:00 2001
> From: Timothy Gu <timothygu99 at gmail.com>
> Date: Wed, 8 Jan 2014 18:30:20 -0800
> Subject: [PATCH 3/4] doc/muxers: add "Options", "Examples", "Syntax", etc.
>  subsections
> 
> More consistent with codec docs.
> 
> Signed-off-by: Timothy Gu <timothygu99 at gmail.com>
> ---
>  doc/muxers.texi | 32 ++++++++++++++++++++++++++++++++
>  1 file changed, 32 insertions(+)
> 
> diff --git a/doc/muxers.texi b/doc/muxers.texi
> index 989cb96..de79989 100644
> --- a/doc/muxers.texi
> +++ b/doc/muxers.texi
> @@ -23,6 +23,8 @@ A description of some of the currently available muxers follows.
>  
>  Audio Interchange File Format muxer.
>  
> + at subsection Options
> +

>  It accepts the following options:

You can drop the introductory line if you add a subsection.

>  @table @option
> @@ -49,6 +51,8 @@ The output of the muxer consists of a single line of the form:
>  CRC=0x at var{CRC}, where @var{CRC} is a hexadecimal number 0-padded to
>  8 digits containing the CRC for all the decoded input frames.
>  
> + at subsection Examples
> +
>  For example to compute the CRC of the input, and store it in the file
>  @file{out.crc}:

If you do this then you should move the reference to framecrc before
this subsection, it doesn't make sense to reference it in the examples
section. Same below.

>  @example
> @@ -89,6 +93,8 @@ packet of the form:
>  @var{CRC} is a hexadecimal number 0-padded to 8 digits containing the
>  CRC of the packet.

> + at subsection Examples
> +
>  For example to compute the CRC of the audio and video frames in
>  @file{INPUT}, converted to raw audio and video packets, and store it
>  in the file @file{out.crc}:
> @@ -132,6 +138,8 @@ packet of the form:
>  @var{MD5} is a hexadecimal number representing the computed MD5 hash
>  for the packet.
>  
> + at subsection Examples
> +
>  For example to compute the MD5 of the audio and video frames in
>  @file{INPUT}, converted to raw audio and video packets, and store it
>  in the file @file{out.md5}:
> @@ -200,6 +208,8 @@ See also the @ref{segment} muxer, which provides a more generic and
>  flexible implementation of a segmenter, and can be used to perform HLS
>  segmentation.
>  
> + at subsection Options
> +
>  This muxer supports the following options:
>  
>  @table @option
> @@ -269,6 +279,8 @@ Image file muxer.
>  
>  The image file muxer writes video frames to image files.
>  

> + at subsection Output File Name Syntax
> +

I don't understand the need for this subsection.

>  The output filenames are specified by a pattern, which can be used to
>  produce sequentially numbered series of files.
>  The pattern may contain the string "%d" or "%0 at var{N}d", this string
> @@ -292,6 +304,8 @@ The pattern "img%%-%d.jpg" will specify a sequence of filenames of the
>  form @file{img%-1.jpg}, @file{img%-2.jpg}, ..., @file{img%-10.jpg},
>  etc.
>  
> + at subsection Examples
> +
>  The following example shows how to use @command{ffmpeg} for creating a
>  sequence of files @file{img-001.jpeg}, @file{img-002.jpeg}, ...,
>  taking one image every second from the input video:
> @@ -354,6 +368,8 @@ Matroska container muxer.
>  
>  This muxer implements the matroska and webm container specs.
>  
> + at subsection Metadata
> +
>  The recognized metadata settings in this muxer are:
>  
>  @table @option
> @@ -411,6 +427,8 @@ For example a 3D WebM clip can be created using the following command line:
>  ffmpeg -i sample_left_right_clip.mpg -an -c:v libvpx -metadata stereo_mode=left_right -y stereo_clip.webm
>  @end example
>  
> + at subsection Options
> +
>  This muxer supports the following options:
>  
>  @table @option
> @@ -475,6 +493,8 @@ very long files (since writing normal MOV/MP4 files stores info about
>  every single packet in memory until the file is closed). The downside
>  is that it is less compatible with other applications.
>  
> + at subsection Options
> +
>  Fragmentation is enabled by setting one of the AVOptions that define
>  how to cut the file into fragments:
>  
> @@ -531,6 +551,8 @@ as fragmented output, thus it is not enabled by default.
>  Add RTP hinting tracks to the output file.
>  @end table
>  
> + at subsection Example
> +
>  Smooth Streaming content can be pushed in real time to a publishing
>  point on IIS with this muxer. Example:
>  @example
> @@ -579,6 +601,8 @@ MPEG transport stream muxer.
>  
>  This muxer implements ISO 13818-1 and part of ETSI EN 300 468.
>  

> + at subsection Options and Metadata

This is pretty arbitrary.

> +
>  The muxer options are:
>  
>  @table @option
> @@ -636,6 +660,8 @@ and @code{service_name}. If they are not set the default for
>  @code{service_provider} is "FFmpeg" and the default for
>  @code{service_name} is "Service01".
>  
> + at subsection Example
> +
>  @example
>  ffmpeg -i file.mpg -c copy \
>       -mpegts_original_network_id 0x1122 \
> @@ -719,6 +745,8 @@ files.
>  See also the @ref{hls} muxer, which provides a more specific
>  implementation for HLS segmentation.
>  
> + at subsection Options
> +
>  The segment muxer supports the following options:
>  
>  @table @option
> @@ -927,6 +955,8 @@ with the tee muxer; encoding can be a very expensive process. It is not
>  useful when using the libavformat API directly because it is then possible
>  to feed the same packets to several muxers directly.
>  

> + at subsection Output File Name Syntax
> +

Again, what problem is this solving? Adding more and more subsections
for short texts is not going to improve readability.

>  The slave outputs are specified in the file name given to the muxer,
>  separated by '|'. If any of the slave name contains the '|' separator,
>  leading or trailing spaces or any special character, it must be
> @@ -962,6 +992,8 @@ specified by a stream specifier. If not specified, this defaults to
>  all the input streams.
>  @end table
>  

> + at subsection Examples
> +

>  Some examples follow.

Drop this.

>  @itemize
>  @item
> -- 
> 1.8.3.2
> 

> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel at ffmpeg.org
> http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

-- 
FFmpeg = Faithless & Fanciful MultiPurpose Ecumenical Ghost