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

[Nicolas George]

Alexander Strasser (12020-08-22):
> Wow the discussion gets up to speed quickly :)

Yes, it's nice for once.

> I think we should eradicate the copy in the source files and
> keep the description in the corresponding .md file. We shall
> build a tool that creates supplementary C files from the .md
> files which have conventional symbol names which are referenced
> from the AVFilter.description and  AVOption.help fields. For
> now the generated C files would only contain rather short one
> line plain text strings matching the current practice. These

It can work. If you look at the draft of built-in documentation API I
just sent:
https://ffmpeg.org/pipermail/ffmpeg-devel/2020-August/268544.html
the description for option foo of video filter bar would be in
avdoc_lavfi__vf_bar__opt_foo.title

Unfortunately, it cannot serve as a static initializer, but we can move
it into yet another symbol if necessary.

In any way, it is quite clumsy to write by hand, but we can use macros:

#defined FILTER_NAME vf_scale

    OPTION(width, w_expr, STRING);

... that write that for us. I have felt for a long time that macros
could make options tables much more readable.

> strings can of course be shortened versions extracted from
> the complete version in the .md file. E.g. only take the
> first sentence.

IMHO, we should be doing that automatically. I think, in Markdown:


## scale - Scale the input video size and/or convert the image format.

Scale (resize) the input video, using the libswscale library.

The scale filter forces the output display aspect ratio to be the same
of the input, by changing the output sample aspect ratio.

If the input image format is different from the format requested by
the next filter, the scale filter will convert the input to the
requested format.

### Options

#### width, w - output video width

Set the output video dimension expression. Default value is the input
dimension.


And then we can take what comes after the dash in the title to serve as
a description.

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/20200823/8f0005f0/attachment.sig>