#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 _______________________________________________ FFmpeg-trac mailing list FFmpeg-trac@avcodec.org http://ffmpeg.org/mailman/listinfo/ffmpeg-trac