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

[Clément Bœsch]

On Fri, Aug 21, 2020 at 11:40:20PM +0200, Nicolas George wrote:
> Clement Boesch (12020-08-21):
> > 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.
> 
> I do not understand what you mean, especially about "document twice".
> 

AVOption.help and AVFilter.description (as well as AVCodec.description
etc) do contain redundant information with the documentation.
Additionally, we sometimes document manually the default, all the
constants, sometimes the ranges, which are already held within the
AVOption.

So yes I'd rather have the AVOption.help extended to contain more and have
a tool which is basically `ffmpeg -h filter=xxx` in the choosen markup.

> In my mind, if we want to make the doc part of the library, there is a
> step during compilation where all the $SRCDIR/libav*/doc/*.texi or
> $SRCDIR/libav*/doc/*.md are converted into $BUILDDIR/libav*/doc/*.c or
> one single C file whatever is more convenient, and then compiled into
> the library. There is never any duplication in the source tree, the doc
> is written once and only once.

I meant the other way around: you have a gen-doc.c which you compile and
link against the library, which generates the .md (integration within the
make is easy).

> 
> How would you include the documentation in the C source file directly?
> Write directly the structures:
> 
> static const AVDocumentation doc = {
>     .name = "scale",
>     .title = "scaling and pixel format conversion filter",
>     .description = "Scale (resize) the input video, using the libswscale"
>     " library.\nThe scale filter forces the output display aspect ratio"
>     " to be the same of the input, by changing the output sample aspect"
>     " ratio. ...";
> };
> 
> Or in Doxygen? Or in something like Doxygen that we invent ourselves?
> None of them feels convenient. Or did I completely misunderstand you.
> 

Yes, for long documentations might be annoying (and we also need to wrap
it with NULL_IF_CONFIG_SMALL).

But I think we have it wrong with the documentation approach. What is
currently described within the code corresponds to the "technical
documentation". While all the extra information on the filters may enter
within the "explanation" and "tutorial" realm. This means that we could
have a filter documentation that starts with the technical documentation
(generated from the code) followed by all the "extra" detailed info on the
filter themselves.

It might get clumsy but at least we wouldn't have to paraphrase with a
different formatting every single option, and miss half of them on a
regular basis.

You may want to read https://documentation.divio.com/ to understand better
the separation I'm making.

> > > 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? ...)
> 
> That's why I did not say "HTML" but "a small basic subset of HTML": we
> answer these questions as we want, and we make a pre-commit hook to
> enforce the rules.

Yeah well, I guess I have PTSD from the dealing with SubRip. Nevertheless,
I believe markdown, asciidoc etc are much more expressive text wise.

[...]

-- 
Clément B.