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

[Alexander Strasser]

Hi Jim!

On 2020-08-22 14:09 -0700, Jim DeLaHunt wrote:
> On  Fri Aug 21 15:35:38 EEST 2020,  Nicolas George wrote:
> > 1. What would you think about putting the documentation for
> >     libavfilter/vf_foobar.c into libavfilter/doc/vf_foobar.texi …
> > 2. What would you think about switching from texinfo to a small basic
> >     subset of HTML for new documentation? …
> > 3. What would you think about using pandoc for processing the
> >     documentation? …
> > 4. What would you think about including the documentation for components
> >     into the libraries? …
>
> I can see the merit of breaking a huge doc file into per-component files,
> especially if they are easier to relate to the corresponding source code. I
> can see that some kind of Markdown might be easier to write than Texinfo
> syntax.
>
> But let me ask a high-level question: what is the goal which these changes
> will serve? How does this the result of this work make the FFmpeg project
> better?

Don't know what Nicolas had in mind in particular. So maybe he
can improve the answer to this question.

For me it is modularization of the documentation source files and
changing the source language to something simpler and more widely
understood than texinfo.

Also it seems at least Clement and me want to get rid of the
partially duplicated documentation that currently resides in the
C sources and in the texinfo sources.


> Over on ffmpeg-user, there has been an interesting discussion[1] about
> FFmpeg's documentation, and what improvements people would like to
> see[1][2][3][4]. There are quite a few suggestions[4]. A few  points seem
> worth highlighting here:

In short I would say in that regard it doesn't change that much,
but rather makes things easier.

A minor hurdle could arise if we decide to do these changes, but
can't do the migration quickly in big steps and thus would have
the two systems for documentation in place for some time.


> 1. There is consensus that cross-links are a valuable tool. They help
> achieve both full description and brevity. So, it seems to me that excellent
> cross-link tools are an important feature we should look for in any
> documentation markup language. How does the markup define a link target? How
> does that link target map to a URL? Can that URL stay consistent as the
> surrounding doc changes? How does the markup define a link source?  Does the
> doc compiler handle those links well? Will those links stay intact as the
> surrounding doc changes? Can that link markup be derived from doc in C code?

In Markdown you write the URL directly and I would assume we would
use relative URLs almost anywhere. So things should be manageable,
but of course if some path/name changing restructuring is happening
you must also fix all places that link to it.

Anyway there is still quite a bit to be decided here technically,
e.g. for generating the combined HTMLs and transforming links.


> 2. There are a number of people volunteering to write documentation. If
> "recruiting more writers" is a goal, how do these changes make that goal
> easier or harder?

Rather easier because of the more common markup language, but I wrote
above that a possible transition period might also complicate things
a little.


> 3. A number (but not all) of the volunteers identified the git workflow as a
> perceived obstacle.  How do these changes make that crossing that obstacle
> easier or harder?

That won't be really affected, though having the docs modularized
usually makes concurrent work easier assuming you won't all work
on e.g. the same filter at the same time.


> I don't have strong feelings about this specific proposal. I do think that
> attention to high-level goals for FFmpeg documentation would add a lot of
> value to the project.

It should make it easier to implement more high level documentation
goals, by implementing solid foundations to build on and strengthening
especially the reference documentation.


Best regards,
  Alexander


> Cheers,
>      —Jim DeLaHunt
>
> [1] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049718.html
>
> [2] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049668.html
>
> [3] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049702.html
>
> [4] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049744.html