[FFmpeg-devel] [PATCH] doc: add libavformat.texi and ffmpeg-formats.texi files

[Alexander Strasser]

Hi Stefano,

Stefano Sabatini wrote:
> ---
>  doc/Makefile            |    3 +-
>  doc/ffmpeg-formats.texi |  161 +++++++++++++++++++++++++++++++++++++++++++++++
>  doc/libavformat.texi    |   37 +++++++++++
>  3 files changed, 200 insertions(+), 1 deletion(-)
>  create mode 100644 doc/ffmpeg-formats.texi
>  create mode 100644 doc/libavformat.texi
[...]
> diff --git a/doc/libavformat.texi b/doc/libavformat.texi
> new file mode 100644
> index 0000000..6a8a67e
> --- /dev/null
> +++ b/doc/libavformat.texi
> @@ -0,0 +1,37 @@
> +\input texinfo @c -*- texinfo -*-
> +
> + at settitle Libavformat Documentation
> + at titlepage
> + at center @titlefont{Libavformat Documentation}
> + at end titlepage
> +
> + at top
> +
> + at contents
> +
> + at chapter Description
> + at c man begin DESCRIPTION
> +
> +The libavformat library provides a generic muxing/demuxing framework
> +form multimedia container formats, and provides several muxer and
> +demuxers.

  This seems to condensed and contains a few errors.

  What about:
  The libavformat library provides a generic framework for multiplexing
  and demultiplexing (muxing and demuxing) audio, video and subtitle
  streams. It encompasses multiple muxers and demuxers for multimedia
  container formats.

  Comments from native English speakers welcome.

  We might consider decorating the lib introductions with names of
popular and supported formats. Not sure if it is wise to do so.
Would be probably better to reference the dedicated docs that
document the codecs and container formats. I know it is in see-also
section already but IMHO it would make sense to place a hint in
the description as it is an important question the reader will
have on her mind when reading the description.

> + at c man end DESCRIPTION
> +
> + at ignore
> +
> + at setfilename libavformat
> + at settitle multimedia muxing and demuxing library
> +
> + at c man begin SEEALSO
> +ffmpeg(1), ffplay(1), ffprobe(1), ffserver(1), libavutil(3),
> +libavcodec(3), ffmpeg-formats(1)
> + at c man end
> +
> + at c man begin AUTHORS
> +See Git history (git://source.ffmpeg.org/ffmpeg)
> + at c man end
> +
> + at end ignore
> +
> + at bye
> -- 
> 1.7.9.5

  Can be used as a start, but the description is still lacking
e.g. R/W protocols.

  Thank you for constantly working your way through the documentation.
I do think it is an important and often neglected point!

  Alexander