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

[Nicolas George]

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

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.

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.

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

But apparently the consensus is for something simpler. Although Markdown
can contain HTML, so we still have the issue.

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

I downloaded the static binary from the site, unpacked it takes 112 Mo,
that is big, but not monstrous. On a Debian oldstable (I need to
upgrade!) where nothing related was installed, I get liblua5.1-0
libluajit-5.1-2 libluajit-5.1-common pandoc pandoc-data and "After this
operation, 72.6 MB of additional disk space will be used.", which
matches the size of the static binary without citeproc.

One of the benefits of pandoc is that it is possible to write a custom
writer, we can use that to generate the C files for inclusion in the
library. Otherwise, we would have another build-dependency, a language
interpreter to write the conversion, unless somebody intends to
implement it in C.

Regards,

-- 
  Nicolas George
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20200821/b307e1fa/attachment.sig>