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

[Alexander Strasser]

On 2020-08-21 15:02 +0200, Jean-Baptiste Kempf wrote:
>
>
> On Fri, 21 Aug 2020, at 14:35, Nicolas George wrote:
> > 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.
>
> Use Markdown.
> It's defined, spec'd and used in all OSS projects. It's supported by most editors and most source repositories.

It's specs are ambiguous and thus there is a wide range of differing
behavior in the numerous implementations.

So if we decide for Markdown it might make sense to document which
spec to follow or which things not to do. Also documenting which
extensions are allowed if any, would be a good thing.

Otherwise I have had good experience with Markdown. I wrote almost
all documents, that needed more than plain text in Markdown for the
last 2 years.

Indeed it is widely supported by web source-code browsers, which is
a nice bonus to also get rendered documents while browsing the source
tree online.


  Alexander