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

[Nicolas George]

Clement Boesch (12020-08-22):
> AVOption.help and AVFilter.description (as well as AVCodec.description
> etc) do contain redundant information with the documentation.

There is truth in what you say, but I disagree this is really redundant:
AVOption.help and AV*.description are supposed to be very short, while
the text in the documentation is supposed to be descriptive, with
explanations.

> Additionally, we sometimes document manually the default, all the
> constants, sometimes the ranges, which are already held within the
> AVOption.

I agree, the default value and constants can, to an extents, be
generated automatically.

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

This is exactly what we are talking about, except for two details:

- We cannot extend AVOption.help without causing an ABI and API break,
  but we can create a new more generic system and keep .help only as a
  small supplement and for compatibility.

- C source files are not the place for lengthy text.

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

If the documentation is embedded in the library, then clearly there
sould be an API to present it. And we could use it to build the static
documentation. It would not work for cross-compilation, though.

Another option is to have a FATE tests that checks the consistency of
the documentation with the options. I think this better, because
although redundancy without check leads to inconsistency, redundancy
with checks helps make sure we write what we mean and we mean what we
write.

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

I read "simple and comprehensive", I automatically translate
"oversimplification".

The distinction between reference and explanations on one side and
tutorials and how-to guides on the other side makes sense. On the other
hand, there is a continuum between tutorials and how-tos, and a
continuum between reference and explanations.

> To clarify just a little here: the non technical documentation would be
> written manually outside of the code, just like currently (except we would
> strip out all the redundant info with the tech doc).

The documentation for components, which is the bulk of the documentation
and what we are discussing now, is "reference", with just enough of
"explanation" to make it self-contained without overlapping with
transverse documentation.

I agree that it belongs with each component. But again, a C source file
is not the place for this, mixing syntaxes is rarely a good idea. Which
is exactly why I suggest to have a parallel structure $lib/$component.c
+ $lib/doc/$component.md.

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/20200822/14a5deb4/attachment.sig>