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

[Clément Bœsch]

On Fri, Aug 21, 2020 at 02:35:38PM +0200, 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.

The split is probably not a bad idea, but can we discuss having the
documentation within the C code to prevent duplication/redundancy?

We could write a tool to generate the documentation file, or maybe part of
it for a start (the options). Having to document twice leads to many
inconsistencies.

> 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.

Anything but HTML please... It's verbose, there are many different
versions, and it's too lax IMO (capitalized tags or not? do you use ending
slashes for single tags? what are all the indentation rules? ...)

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

Pandoc is great, but it has a haskell dependency, it's actually a pretty
huge distribution. It's not yet to the level of a LaTeX distribution, but
it's still pretty large; here it's about 240M with all its dependencies.

[...]

-- 
Clément B.