Subject: Re: [Cellar] An attempt at FFV1 specification in RFC form

From: Dave Rice <[email-masked]>
Date: Thu, 7 Jul 2016 02:02:53 -0400

Hi all,

> On Jun 17, 2016, at 1:01 AM, Dave Rice <[email-masked]> wrote:
> 
> Hi all,
> 
> As with the last thread I submitted a pull request [1] to add RFC features to the FFV1 repo. Some comments and questions:
> 
> To get everything to work I had to remove [2] some stray &nbsp; from the markdown. Michael, any reason for those to be there?
> 
> The ffv1 repo already has a Makefile which outputs HTML and PDF versions of the specification and uses metadata tags at the top of the spec to communicate to pandoc which creates the output. Since the metadata for the PDF/HTML is different than that for the RFC, I created a frontmatter file for each of those types. The rfc_frontmatter currently looks like this:
> 
> % Title = "FF Video Codec 1"
> % abbrev = "FFV1"
> % category = "info"
> % docName = ""
> % ipr= "trust200902"
> % area = ""
> % workgroup = "cellar"
> % keyword = [""]
> %
> % [[author]]
> % initials="M."
> % surname="Niedermayer"
> % fullname="Michael Niedermayer"
> 
> As with the other thread, I am not very familiar with using these values. Feedback and corrections are very welcome.
> 
> I did edits to the FFV1 Makefile that were similar to the EBML Makefile [3]. Feedback welcome.
> 
> And here’s an example of the current RFC output from the makefile in this pull request: https://gist.github.com/dericed/882c4ad6f4cc3e16a8104a663964e42c [4].
> 
> There are a few places where the markdown formatting of the FFV1 specification breaks the RFC’s line wrapping. Also the FFV1 specification includes a lot of LaTeX and math which doesn’t render properly in a text based RFC. The equations in here may be a challenge to present accurately in plain text.
> 
> Best Regards,
> Dave Rice
> 
> [1] https://github.com/FFmpeg/FFV1/pull/19
> [2] https://github.com/FFmpeg/FFV1/pull/19/commits/2cbbae19d282f6c440c7986d0d5c5e554c756ae4
> [3] https://github.com/FFmpeg/FFV1/pull/19/commits/8b6b1ef29fb79a40fe135b01cc93eacdf48718aa
> [4] https://gist.github.com/dericed/882c4ad6f4cc3e16a8104a663964e42c

Based on comments received on github, I updated this pull request and added some formatting changes to make the output a bit more acceptable as an rfc text. I uploaded the output of this branch to the tracker here: https://datatracker.ietf.org/doc/draft-niedermayer-cellar-ffv1/.

The draft has many issues:
- LOTS of math in LaTex that is incomprehensible in RFC form (any good LaTex to plain text convertors for math?)
- it is missing a Security Considerations section, Michael?
- the manner of referencing should be updated (we this is built with mmark, see https://github.com/miekg/mmark/wiki/Syntax#citations)
- IMHO the Introduction should be significantly expanded

Best Regards,
Dave Rice

---

From: Ashley Blewer <[email-masked]>
Date: Thu, 7 Jul 2016 08:20:43 -0400

Thanks, Dave!

Equations issue: This reminds me of converting from LyX to Markdown and
struggling to retain the precise mathematic equations in such simple
documentation format. Does anyone else know what common practices are
regarding equations in RFCs?

Ashley

On Thu, Jul 7, 2016 at 2:02 AM, Dave Rice <[email-masked]> wrote:

> > As with the last thread I submitted a pull request [1] to add RFC
> features to the FFV1 repo. Some comments and questions:
> >
> > To get everything to work I had to remove [2] some stray &nbsp; from the
> markdown. Michael, any reason for those to be there?
> >
> > The ffv1 repo already has a Makefile which outputs HTML and PDF versions
> of the specification and uses metadata tags at the top of the spec to
> communicate to pandoc which creates the output. Since the metadata for the
> PDF/HTML is different than that for the RFC, I created a frontmatter file
> for each of those types. The rfc_frontmatter currently looks like this:
> >
> > As with the other thread, I am not very familiar with using these
> values. Feedback and corrections are very welcome.
> >
> > And here’s an example of the current RFC output from the makefile in
> this pull request:
> https://gist.github.com/dericed/882c4ad6f4cc3e16a8104a663964e42c [4].
> >
> > There are a few places where the markdown formatting of the FFV1
> specification breaks the RFC’s line wrapping. Also the FFV1 specification
> includes a lot of LaTeX and math which doesn’t render properly in a text
> based RFC. The equations in here may be a challenge to present accurately
> in plain text.
> >
> > Best Regards,
> > Dave Rice
> >
> > [2]
> https://github.com/FFmpeg/FFV1/pull/19/commits/2cbbae19d282f6c440c7986d0d5c5e554c756ae4
> > [3]
> https://github.com/FFmpeg/FFV1/pull/19/commits/8b6b1ef29fb79a40fe135b01cc93eacdf48718aa
> Based on comments received on github, I updated this pull request and
> added some formatting changes to make the output a bit more acceptable as
> an rfc text. I uploaded the output of this branch to the tracker here:
> https://datatracker.ietf.org/doc/draft-niedermayer-cellar-ffv1/.
>
> - LOTS of math in LaTex that is incomprehensible in RFC form (any good
> LaTex to plain text convertors for math?)

> - the manner of referencing should be updated (we this is built with
> mmark, see https://github.com/miekg/mmark/wiki/Syntax#citations)
> _______________________________________________
> Cellar mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cellar
>