Subject: [Cellar] math in IETF specifications

From: Dave Rice <[email-masked]>
Date: Wed, 2 Dec 2015 14:22:49 -0500

Dear IETF lurkers,

The current version of the FFV1 specification includes a lot of latex style mathematical equations to express various aspects of the encoding format. These can be seen in the markdown in locations like this https://github.com/FFmpeg/FFV1/blob/master/ffv1.md#range-binary-values <https://github.com/FFmpeg/FFV1/blob/master/ffv1.md#range-binary-values> and in rendered form in HTML, http://www.ffmpeg.org/~michael/ffv1-markdown/ffv1.html#range-coding-mode <http://www.ffmpeg.org/~michael/ffv1-markdown/ffv1.html#range-coding-mode>, and PDF, http://www.ffmpeg.org/~michael/ffv1-markdown/ffv1.pdf <http://www.ffmpeg.org/~michael/ffv1-markdown/ffv1.pdf>.

I've been investigating to see how other RFC documents integrate latex style mathematical equations but have not found any? If there a recommended manner to include math? Should it be translated into a narrative? Is there a recommended way to render math in a plain text RFC?

Best Regards,
Dave Rice

---

From: Adam Roach <[email-masked]>
Date: Wed, 2 Dec 2015 13:30:33 -0600

On 12/2/15 1:22 PM, Dave Rice wrote:
> Dear IETF lurkers,
>
> The current version of the FFV1 specification includes a lot of latex 
> style mathematical equations to express various aspects of the 
> encoding format. These can be seen in the markdown in locations like 
> this 
> https://github.com/FFmpeg/FFV1/blob/master/ffv1.md#range-binary-values and 
> in rendered form in HTML, 
> http://www.ffmpeg.org/~michael/ffv1-markdown/ffv1.html#range-coding-mode 
> <http://www.ffmpeg.org/%7Emichael/ffv1-markdown/ffv1.html#range-coding-mode>, 
> and PDF, http://www.ffmpeg.org/~michael/ffv1-markdown/ffv1.pdf 
> <http://www.ffmpeg.org/%7Emichael/ffv1-markdown/ffv1.pdf>.
>
> I've been investigating to see how other RFC documents integrate latex 
> style mathematical equations but have not found any? If there a 
> recommended manner to include math? Should it be translated into a 
> narrative? Is there a recommended way to render math in a plain text RFC?
>

There's an effort underway to modernize the RFC format, and the new 
format will allow for significantly better formatting of things like 
mathematical formulae. See:

https://tools.ietf.org/html/draft-flanagan-rfc-framework

and

http://www.rfc-editor.org/rse/format-faq/

It seems quite likely that this work will be reaching completion in 
about the same timeframe as CELLAR is ready to publish its final output.

In the meanwhile, there is precedent for publishing both .txt and .pdf 
versions of documents, with the .txt versions referring to the .pdf for 
information that cannot be rendered in text.

Another approach that has been taken is expression of this kind of 
information in algorithmic formats, using pseudocode or actual 
programming languages.

/a

---

From: "Timothy B. Terriberry" <[email-masked]>
Date: Wed, 02 Dec 2015 11:52:48 -0800

> about the same timeframe as CELLAR is ready to publish its final output.

Given some of our milestone dates, that may be optimistic (or rather, 
the milestones may be optimistic).

>> narrative? Is there a recommended way to render math in a plain text RFC?

RFC 6716 is probably one of the more involved RFCs, mathematically. You 
can see what we did there 
(<https://tools.ietf.org/html/rfc6716#section-4.2.7.5.6> is a good 
example). But mostly this involves a bunch of manual work. It's not 
hard, but let me say I'm looking forward to the upcoming better tooling.

---

From: Adam Roach <[email-masked]>
Date: Wed, 2 Dec 2015 14:04:05 -0600

> the milestones may be optimistic).

You're right. I had "end of 2016" in my head, but that's the *final* 
milestone rather than the *initial* milestone. The RFC format effort 
will probably come too late, in that case.

/a

---

From: Dave Rice <[email-masked]>
Date: Wed, 2 Dec 2015 23:39:09 -0500

Hi Tim,

> On Dec 2, 2015, at 2:52 PM, Timothy B. Terriberry <[email-masked]> wrote:
> 
> Adam Roach wrote:
> Given some of our milestone dates, that may be optimistic (or rather, the milestones may be optimistic).
> 
> RFC 6716 is probably one of the more involved RFCs, mathematically. You can see what we did there (<https://tools.ietf.org/html/rfc6716#section-4.2.7.5.6> is a good example). But mostly this involves a bunch of manual work. It's not hard, but let me say I'm looking forward to the upcoming better tooling.

Thanks, it’s good to see the options in action. Given what is available in the timeline of the project it may be easiest to leave the math in LaTeX form and cite the PDF version for reference. The ASCII Art equations of RFC 6716 are impressive but I’d worry that in this effort that it would compromise legibility. In the current FFV1 LaTeX there are some examples with subscripts of subscripts of subscripts.

Best Regards,
Dave Rice

---

From: "Timothy B. Terriberry" <[email-masked]>
Date: Wed, 02 Dec 2015 20:48:41 -0800

> Thanks, it’s good to see the options in action. Given what is available in the timeline of the project it may be easiest to leave the math in LaTeX form and cite the PDF version for reference. The…

Yes, in 6716 we probably would have done that as C-style arrays (our 
syntax closer to C than traditional mathematical notation, on the 
whole). But doing that conversion for a bunch of existing equations 
would be a lot of work.