Re: [FFmpeg-devel] Embedded documentation?

[Nicolas George <george@nsup.org>]

[-- Attachment #1.1: Type: text/plain, Size: 1873 bytes --]

Stefano Sabatini (12023-05-08):
> I think the problem with HTML is that then you need to parse it if you
> want to display it, so I'd tend to rather go with markdown:
> 1. it provides readable raw output
> 2. there are plenty of libraries which can render it to various
> formats (including HTML)

I will reply to this separately.

A lot of your comments are a little premature: I am not ready to start
working on this just now. For starters, it is out of question without
AVWriter being committed, and I am still waiting for somebody who is not
a-priori hostile and who understand strings to look at the code.

But this issue can be discussed now.

I think using Markdown internally would be a huge mistake.

You say “it provides readable raw format”: you seem to be assuming
ffmpeg/ffplay/ffprobe will dump the documentation to the terminal as is
and be done with it, and all other kinds of applications will have to
manage the rest themselves.

Well, this is not the kind of API I want to design. I want an API where
we provide to the applications all its needs to prepare the
documentation for the user, with the data in the most convenient format.

And for that, the internal format needs to be convenient to manage with
a program. A C program specifically.

Markdown is designed to be easy to type and easy to look at by humans.
But that makes it terrible to manage with a program. For starters, its
syntax is highly ambiguous, already with “*” and “**”.

HTML is a much better choice. Note: I am not suggesting the full complex
beast of HTML found on the world-wide-web, with CSS and javascript and
bad syntax and all the crap. I am suggesting a very well-defined subset
of clean HTML. That is much easier to parse than Markdown, with only <
and & acting as special characters.

Regards,

-- 
  Nicolas George

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[-- Attachment #2: Type: text/plain, Size: 251 bytes --]

_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".