<html><head><meta http-equiv="Content-Type" content="text/html charset=us-ascii"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><br class=""><div><blockquote type="cite" class=""><div class="">On May 12, 2017, at 1:05 PM, Dave Rice <<a href="mailto:dave@dericed.com" class="">dave@dericed.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><span style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">Hi all,</span><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;">And cc'ing flac-dev.</div><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><br class=""><div class=""><blockquote type="cite" class=""><div class="">On May 10, 2017, at 12:15 PM, Dave Rice <<a href="mailto:dave@dericed.com" class="">dave@dericed.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;">Hi Andrew,<div class=""><br class=""><div class=""><blockquote type="cite" class=""><div class="">On May 10, 2017, at 11:19 AM, Andrew James Weaver <<a href="mailto:weevz@uw.edu" class="">weevz@uw.edu</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div dir="ltr" class="">Hello all!<div class=""><br class=""></div><div class="">In a previous discussions on this list about people interested in working on the FLAC standard, I said that I would be willing to start the process of converting the existing standard into Markdown. I am writing to inform the list that I have begun preliminary work on this conversion.</div><div class=""><br class=""></div><div class="">Currently that work is living here<span class="Apple-converted-space"> </span><a href="https://github.com/privatezero/flac_markdown" class="">https://github.com/privatezero/flac_markdown</a>.</div></div></div></blockquote><br class=""></div><div class="">I sent a pull request at <a href="https://github.com/privatezero/flac_markdown/pull/1" class="">https://github.com/privatezero/flac_markdown/pull/1</a>, which starts to add a process to convert the markdown to the RFC format using the same Makefile approach that we use with the FFV1 and EBML markdown files. There's still a lot of inter-document cross-referencing that needs to be adjusted before the Makefile works. For instance current cross-referencing like:</div><div class=""><br class=""></div><div class="">[*SUBFRAME\_VERBATIM*](#subframe_verbatim)</div><div class=""><br class=""></div><div class="">won't render as expected in a plain text RFC, but would simply render to something like "Section X.X.X".</div><div class=""><br class=""></div><div class="">In EBML we use markdown such as</div><div class=""><pre class=""><pre class="">See [the section on `Element Data Size`](#element-data-size) for rules that apply to elements of unknown length.</pre></pre><div class="">so that in the RFC this renders to</div><div class=""><pre class="">See Section 7 for rules that apply to elements of unknown length.</pre><div class="">and in the markdown it renders to</div></div><div class=""><br class=""></div><div class="">See<span class="Apple-converted-space"> </span><a href="https://github.com/Matroska-Org/ebml-specification/blob/master/specification.markdown#element-data-size" class="">the section on<span class="Apple-converted-space"> </span><code class="">Element Data Size</code></a><span class="Apple-converted-space"> </span>for rules that apply to elements of unknown length.</div></div></div></div></div></blockquote><br class=""></div><div class="">I added some issues to the flac_markdown repository and Andrew addressed them in<span class="Apple-converted-space"> </span><a href="https://github.com/privatezero/flac_markdown/pull/7" class="">https://github.com/privatezero/flac_markdown/pull/7</a>. Most of these issues pertain to unintended semantic differences between the FLAC specification as it exists in its original HTML form at <a href="https://xiph.org/flac/format.html" class="">https://xiph.org/flac/format.html</a><span class="Apple-converted-space"> </span>and the markdown rendition being worked on at <a href="https://github.com/privatezero/flac_markdown/blob/master/flac.md" class="">https://github.com/privatezero/flac_markdown/blob/master/flac.md</a>.</div><div class=""><br class=""></div><div class="">Since the recent work focuses on a change of format from HTML to markdown, I suggest that short term goals on the flac specification focus on:</div></div><div style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class="">- verifying semantic equalness with the html version</div><div style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class="">- resolving issues that block the mmark/xml2rfc process that generates the RFC formats of the specification</div><div style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class="">- add standard RFC boilerplate (abstract, rfc2119, etc)</div></div></blockquote><br class=""></div><div>To summarize recent work on the FLAC specification, the document has been adjusted in its new markdown format in order to achieve semantic similarity to the original HTML rendition on the <a href="http://xiph.org" class="">xiph.org</a> site. In order to get the structural data (such as the tables at the end of <a href="https://xiph.org/flac/format.html" class="">https://xiph.org/flac/format.html</a>) to fit in plain text RFC style, the tables were dissected a bit to separate value lists from structural lists. In this way the subcomponents and defined in their own sections instead of the prior strategy of detailing lists and pseudocode within large tables. For instance see the original rendition of the frame header documentation from <a href="https://xiph.org/flac/format.html#frame_header" class="">https://xiph.org/flac/format.html#frame_header</a> compared to the dissected version which gives the subcomponents their own subsequent sections at <a href="https://github.com/privatezero/flac_markdown/blob/7a5c21d49d1fda89609ffa9edfca2447c7ca3c5e/flac.md#frame_header" class="">https://github.com/privatezero/flac_markdown/blob/7a5c21d49d1fda89609ffa9edfca2447c7ca3c5e/flac.md#frame_header</a>. Splitting out the subcomponents into their own sections also gives space to be more explicate in defining them, such as <a href="https://github.com/privatezero/flac_markdown/commit/3aaa5f293102018bd7c41409e79e36f510557d96" class="">https://github.com/privatezero/flac_markdown/commit/3aaa5f293102018bd7c41409e79e36f510557d96</a>.</div><div><br class=""></div><div>Andrew noticed that there are some issues with managing section titles that contain underscores and getting internal sectional citations to work. For instance (#frame-header) will link to `FRAME HEADER` (space) but not `FRAME_HEADER` (underscore). Is there any reason not to swap the all-caps, underscored component names to tilde-quoted, all caps name with spaces rather than underscores?</div><div><br class=""></div><div>For convenience, here is a rendering of the plain text RFC output of git-master of the FLAC format repository: <a href="https://gist.github.com/dericed/2639d0eed5e064b4dec1399bc8716833" class="">https://gist.github.com/dericed/2639d0eed5e064b4dec1399bc8716833</a>.</div><div><br class=""></div><div>I suggest reviews of the current markdown from those familiar with the historical FLAC format specification so that we ensure that the current work is the same in meaning to the original html version of the specification.</div><div><br class=""></div><div>Best Regards,</div><div>Dave Rice</div></body></html>