On Fri Aug 21 15:35:38 EEST 2020, Nicolas George wrote: > 1. What would you think about putting the documentation for > libavfilter/vf_foobar.c into libavfilter/doc/vf_foobar.texi … > 2. What would you think about switching from texinfo to a small basic > subset of HTML for new documentation? … > 3. What would you think about using pandoc for processing the > documentation? … > 4. What would you think about including the documentation for components > into the libraries? …
I can see the merit of breaking a huge doc file into per-component files, especially if they are easier to relate to the corresponding source code. I can see that some kind of Markdown might be easier to write than Texinfo syntax.
But let me ask a high-level question: what is the goal which these changes will serve? How does this the result of this work make the FFmpeg project better?
Over on ffmpeg-user, there has been an interesting discussion[1] about FFmpeg's documentation, and what improvements people would like to see[1][2][3][4]. There are quite a few suggestions[4]. A few points seem worth highlighting here:
1. There is consensus that cross-links are a valuable tool. They help achieve both full description and brevity. So, it seems to me that excellent cross-link tools are an important feature we should look for in any documentation markup language. How does the markup define a link target? How does that link target map to a URL? Can that URL stay consistent as the surrounding doc changes? How does the markup define a link source? Does the doc compiler handle those links well? Will those links stay intact as the surrounding doc changes? Can that link markup be derived from doc in C code?
2. There are a number of people volunteering to write documentation. If "recruiting more writers" is a goal, how do these changes make that goal easier or harder?
3. A number (but not all) of the volunteers identified the git workflow as a perceived obstacle. How do these changes make that crossing that obstacle easier or harder?
I don't have strong feelings about this specific proposal. I do think that attention to high-level goals for FFmpeg documentation would add a lot of value to the project.
Cheers, —Jim DeLaHunt [1] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049718.html [2] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049668.html [3] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049702.html [4] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049744.html _______________________________________________ ffmpeg-devel mailing list ffmpeg-devel@ffmpeg.org https://ffmpeg.org/mailman/listinfo/ffmpeg-devel To unsubscribe, visit link above, or email ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
