[FFmpeg-devel] Documentation: proposed changes in the structure

[Timo Rothenpieler]

On 21.08.2020 14:35, Nicolas George wrote:
> 1. What would you think about putting the documentation for
>     libavfilter/vf_foobar.c into libavfilter/doc/vf_foobar.texi instead
>     of into huge doc/filters.texi (25k lines!)? And same for codecs,
>     formats, etc.
> 
>     We can adopt this for new documentation and move progressively
>     existing components.

That seems long overdue to me.
The current approach to documentation has become very hard to properly 
maintain.

> 
> 2. What would you think about switching from texinfo to a small basic
>     subset of HTML for new documentation?
> 
>     I think most of us are much more familiar with HTML syntax than with
>     texinfo.

Something like Markdown would come to mind. It should have all 
formatting tools one needs for documentation.

> 
> 3. What would you think about using pandoc for processing the
>     documentation?

Seems like a common choice for processing Markdown to me, so would go 
well with Markdown.

> 
> 4. What would you think about including the documentation for components
>     into the libraries? It would allow GUI applications to present it in
>     dialog boxes, like spreadsheets do with their math functions.

Not really any strong opinion there. It'd increase the size of the 
binaries, but if its compressed not by a whole lot, and I can see it 
being useful specially for CLI users.