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

[Stefano Sabatini]

On date Sunday 2012-11-25 23:32:20 +0100, Alexander Strasser encoded:
> 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.

Updated, I'm also mentioning protocols.

>   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.

I don't object but:
1. the doc is meant for programmers, so we're talking about
sophisticated users which usually already knows what a container
format is.
2. I don't know how to implement it specifically, suggestions are
welcome.

> > + 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.

Yes, a dedicated document (ffmpeg-protocols) is in my todo.

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

Thanks for helping with this effort.
-- 
FFmpeg = Forgiving and Formidable Mystic Patchable Erudite Genius
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0006-doc-add-libavformat.texi-and-ffmpeg-formats.texi-fil.patch
Type: text/x-diff
Size: 6521 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121126/0af68b80/attachment.bin>