[FFmpeg-user] ffprobe documentation seems mixed up with ffmpeg docs

[Stefano Sabatini]

On date Wednesday 2012-08-08 01:16:39 +0200, Peter B. encoded:
> On 08/07/2012 11:32 PM, Stefano Sabatini wrote:
> > On date Monday 2012-07-30 16:25:29 +0200, Peter B. encoded:
> >> I just wanted to consult the ffprobe documentation [1] and it seems
> >> to be mixed up with parts which actually apply to transcoding using
> >> ffmpeg, rather than what ffprobe does.
> >>
> >> e.g. The example mentioned in the section "Options > AVOptions"
> >> shows using "ffmpeg" for transcoding flac to mp3.
> >>
> >> Other parts of that documentation also seem to actually apply to
> >> ffmpeg rather than ffprobe.
> > Yes that part of the documentation is not very well thought (the
> > author apparently confused ffmpeg/avconv docs with generic
> > tools documentation).
> I've just checked the .texi source and I think the problem is caused a
> number of @includes:
> 

> @include syntax.texi

This describes the syntax used by various (library) components / tools
options.

> @include decoders.texi

Decoders are used by ffprobe (-show_frames requires decoding).

> @include demuxers.texi

Demuxers are used by ffprobe.

> @include protocols.texi

Same for protocols.

> @include indevs.texi

ffprobe can read from input devices.

Also note that ffprobe can read from the lavfi device, which makes
use of filters, so it would make sense to include also filters.texi.
 
> they just point to ffmpeg's documentation files. Therefore the
> misleading/confusing syntax parts in the ffprobe docs.
> What about just removing those includes, as they don't make any sense
> anyway here.

As I explained, the includes are there for a reason. On the other hand
it is not easy to document all the features of ffmpeg in a way which
is possibly useful for documenting both libraries and tools.

For example the various doc/ files which document the various
components (codecs, formats, protocols, filters etc.) make extensive
use of ff* example commands, mostly ffmpeg and ffplay commands, which
will you therefore find in the ffprobe manpage.

> >> How is this text edited? If it's somewhere in the repositories,
> >> could someone (for example: me) propose patches?
> > Yes download FFmpeg source code and check in the doc/ directory,
> > source files are texi (texinfo) files converted to POD/HTML/man pages,
> > website documentation is in synch with the latest FFmpeg git version.

> How would I proceed if I wanted to provide you a patch from my changes?

http://ffmpeg.org/developer.html#Contributing

don't be bothered to read all the stuff, sending a git-format patch
(or simply a diff) should be enough.

Anyway I don't think removing those includes from ffprobe.texi would
be acceptable for the above mentioned reasons.
-- 
ffmpeg-user random tip #24
*Read* the mailing lists rules before posting new messages:
http://www.ffmpeg.org/mailinglists.html