Subject: [Cellar] the next FFV1 draft

From: Dave Rice <[email-masked]>
Date: Mon, 2 Jan 2017 11:03:39 -0500

Hi all,

I notice that the current draft of the FFV1 specification [1] expires in less than a week (January 8, 2017). I suggest that we submit a new revision before that expiration. Currently the GitHub repo for FFV1’s specification [2] has over 20 commits since the current -00 draft so it’s timely anyhow to post a new version.

There’s two pull requests that are works in progress and could use review:
https://github.com/FFmpeg/FFV1/pull/31/files includes expanded documentation on the colorspaces used in FFV1
https://github.com/FFmpeg/FFV1/pull/29 is an attempt to add a narrative explanation to accompany information about FFV1’s structural components that are currently documented in codeblocks without narratives.

Here’s some of my suggestions on what small efforts we could take to improve the document for the next version:

Review spacing and formatting in the codeblocks. There’s some discussion on this in a related pull request at https://github.com/FFmpeg/FFV1/pull/25.

Note and integrate forward-references into the document. There’s several places where an FFV1 term is introduced and used before it is defined. We now have section headers throughout the document so it should be easier to add forward-references.

Review capitalization of terms. I started some of this in https://github.com/FFmpeg/FFV1/pull/32/commits, but there’s other terms used in the document which have inconsistent capitalization, such as 'frame' vs 'Frame'.

Identify terms that are used though undefined and should have local definitions.

Suggestions on short-term goals? Volunteers?

Also I see that RFC7996 [3] was published last month which defines how to use SVG within RFCs. Could this be a reasonable method for handling the complex math of the FFV1 specification (currently in LaTeX) within an RFC? There are some LaTeX to SVG convertors available online.

Best Regards,
Dave Rice

[1] https://tools.ietf.org/html/draft-niedermayer-cellar-ffv1-00
[2] https://github.com/FFmpeg/FFV1/commits/master
[3] https://tools.ietf.org/html/rfc7996

---

From: Jerome Martinez <[email-masked]>
Date: Tue, 3 Jan 2017 17:23:38 +0100

Le 02/01/2017 à 17:03, Dave Rice a écrit :
> [...]

 From my point of view this is slightly redundant with the "General" 
section.
I like the way it is put in the spec with this PR but I think that the 
redundant content should be removed from the General section.
I added some other less significant comments in the PR directly.

> https://github.com/FFmpeg/FFV1/pull/29 is an attempt to add a narrative explanation to accompany information about FFV1’s structural components that are currently documented in codeblocks without n…

I am not convinced that it is useful, I think that the "C like" approach 
is enough, and if there is a need of more detail for a "block" it should 
be in the corresponding paragraph.
"A `Slice` is a spatially distinct region of a `Frame` that is encoded 
separately from any other region of that `Frame`." is a good 
introduction, at the right place.
"A `Slice` is comprised the following four components in this storage 
order: (...)" is redundant with the "C-like" code, and there is a risk 
of error when we update. better to have only one place for a piece of 
information.

> Review capitalization of terms. I started some of this in https://github.com/FFmpeg/FFV1/pull/32/commits, but there’s other terms used in the document which have inconsistent capitalization, such a…

+1

> Suggestions on short-term goals? Volunteers?

I see less and less things to add to the specs. I plan to do another 
review code vs specs this week and see what is missing, and beside what 
you suggest I would like to have comments from others about what is 
considered as missing.

> Also I see that RFC7996 [3] was published last month which defines how to use SVG within RFCs. Could this be a reasonable method for handling the complex math of the FFV1 specification (currently i…

I don't see a better method until MathML is accepted and supported by 
tools, so +1.

Jérôme

---

From: Dave Rice <[email-masked]>
Date: Sat, 7 Jan 2017 15:31:31 -0500

> On Jan 3, 2017, at 11:23 AM, Jerome Martinez <[email-masked]> wrote:
> 
> From my point of view this is slightly redundant with the "General" section.
> I like the way it is put in the spec with this PR but I think that the redundant content should be removed from the General section.

The redundancy is removed and the pull request on colorspace definitions is updated at https://github.com/FFmpeg/FFV1/pull/31.

> I am not convinced that it is useful, I think that the "C like" approach is enough, and if there is a need of more detail for a "block" it should be in the corresponding paragraph.
> "A `Slice` is a spatially distinct region of a `Frame` that is encoded separately from any other region of that `Frame`." is a good introduction, at the right place.
> "A `Slice` is comprised the following four components in this storage order: (...)" is redundant with the "C-like" code, and there is a risk of error when we update. better to have only one place for a piece of information.

This PR is closed and a new issue is opened at https://github.com/FFmpeg/FFV1/issues/35 to give a paragraph to describe how FFV1 structures are defined in codeblocks.

>> Review capitalization of terms. I started some of this in https://github.com/FFmpeg/FFV1/pull/32/commits, but there’s other terms used in the document which have inconsistent capitalization, such…

+1 though still needs a volunteer.

> I see less and less things to add to the specs. I plan to do another review code vs specs this week and see what is missing, and beside what you suggest I would like to have comments from others about what is considered as missing.

New pull requests are here for review: https://github.com/FFmpeg/FFV1/pulls. These:
- add definitions for several functions within the document
- add a few more citations
- describe assignment operators a bit more verbosely
- define the NumBytes value

Along the way I opened a few more issues at https://github.com/FFmpeg/FFV1/issues where a few things aren’t defined or cited.

> I don't see a better method until MathML is accepted and supported by tools, so +1.

Adjusting the mmark and xml2rfc process to incorporate SVG equations seems harder than I hoped. Currently mmark produces xml2rfc version 2 but we’ll have to update to xml2rfc version 3 to use the recent SVG parts of RFC7996. My attempts here did not work well. I get the impression that although xml2rfc version 3 is now officially defined, there aren’t yet updates to the xml2rfc tools to allow those new features to be used. Any advice?

Dave Rice