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

[Alexander Strasser]

On 2020-08-21 14:35 +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.

IMHO it's the right thing to do.


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

I would prefer Markdown or similar text like formats.

Writing HTML by hand isn't so nice and reading the source is also
a bit harder because of the tag syntax.


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

Would be an option. My experience withe pandoc is a bit dated, but
it was working fine back then.

IIRC the major advantage is, that it supports many output formats.

When we have settled on a source format, we could maybe compare
some alternatives.


> 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.
>
>
> (4 certainly depends on 2, because texinfo is nos suited for that use;
> and probably in part on 1.)

If we can efficiently embed it, that would cool. Even for CLI apps
too.


  Alexander