[FFmpeg-trac] #6950(documentation:closed): image2 demuxer documentation deficiencies

[FFmpeg]

#6950: image2 demuxer documentation deficiencies
-------------------------------------+-------------------------------------
             Reporter:  jdlh         |                    Owner:
                 Type:  defect       |                   Status:  closed
             Priority:  normal       |                Component:
              Version:  unspecified  |  documentation
             Keywords:               |               Resolution:  invalid
             Blocking:               |               Blocked By:
Analyzed by developer:  0            |  Reproduced by developer:  0
-------------------------------------+-------------------------------------

Comment (by jdlh):

 This response shows one of the reasons why the ffmpeg project has poor
 documentation. This ticket points out deficiencies in the documentation.
 The developer's response does not refute the deficiencies. It does not
 improve the actual documentation. Yet the developer closes the ticket.
 Thus the project will lose visibility that this part of the documentation
 is deficient.

 To respond to cehoyos' comments one by one:

 "The ticket is invalid since it claims to report more than one issue." The
 deficiency is with one contiguous part of the documentation, in
 doc/demuxers.txi, lines 329:462. The deficiency has multiple aspects. The
 efficient way to fix it is to improve that section of documentation,
 addressing all the aspects at once.  Thus I think a single ticket is
 appropriate.

 However, if it's ''really'' important to have one ticket for each aspect,
 I can break this ticket into multiple tickets. I have low confidence that
 those tickets will be respected any better.

 Problem 1: "It also doesn't mention that the image2 demuxer does not
 support apng files." All this does is say there is a further deficiency.
 It does not refute the claim that the lack of mention of GIF is a
 deficiency.  A ticket should stay open to track the deficiency, namely the
 variance in image2 behaviour by formats and file extensions.

 Problem 2: "No other demuxer support %d but %d does not imply image2, file
 suffixes do. It is not part of the API which file suffixes imply the
 image2 demuxer, we try to update the list whenever we become aware of new
 use-cases (but we have removed file suffixes from the list in the past,
 for example gif)."  This does not refute the claim that the documentation
 is deficient. It just suggests a better explanation for the documentation
 to include. A ticket should stay open to track the deficiency, namely when
 and how the nature of the input makes explicitly specifying `-f image2`
 optional.

 Problem 3: "But you did not provide a use-case where -f image2 was
 needed…" This does not refute the claim that the examples are missing an
 important class of usage. At the very least, one of the existing examples
 should have `-f image2` added, and there should be text added to the
 examples without `-f image2` pointing out that it is options for those
 examples.

 "it will be difficult (or actually impossible) to add examples for every
 possible use-case." This ticket does not call for "every possible use-
 case", just for doing better than the examples do now.  Don't exaggerate.

--
Ticket URL: <https://trac.ffmpeg.org/ticket/6950#comment:2>
FFmpeg <https://ffmpeg.org>
FFmpeg issue tracker