Hello all! (cc-ing the flac-dev list) I would like to give an update as to the recent CELLAR work on the FLAC specification. • Work has been done to make internal and external links more accurate and reliable. • 'Rice Coding' has been clarified as 'Exponential Golomb Coding.' • Clarifications have been made for binary representation. • Typos and other small changes have been fixed for clarity. Lastly, a version 00 release has been made (available at https://github.com/privatezero/flac_markdown/releases) and the draft document has been uploaded to the IETF datatracker ( https://datatracker.ietf.org/doc/draft-xiph-cellar-flac/) All the best! Andrew Weaver On Mon, May 22, 2017 at 11:06 AM, Dave Rice <dave at dericed.com> wrote:> > On May 12, 2017, at 1:05 PM, Dave Rice <dave at dericed.com> wrote: > > Hi all, > And cc'ing flac-dev. > > On May 10, 2017, at 12:15 PM, Dave Rice <dave at dericed.com> wrote: > > Hi Andrew, > > On May 10, 2017, at 11:19 AM, Andrew James Weaver <weevz at uw.edu> wrote: > > Hello all! > > 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. > > Currently that work is living here https://github.com/ > privatezero/flac_markdown. > > > I sent a pull request at https://github.com/privatezero/flac_markdown/ > pull/1, 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: > > [*SUBFRAME\_VERBATIM*](#subframe_verbatim) > > won't render as expected in a plain text RFC, but would simply render to > something like "Section X.X.X". > > In EBML we use markdown such as > > See [the section on `Element Data Size`](#element-data-size) for rules that apply to elements of unknown length. > > so that in the RFC this renders to > > See Section 7 for rules that apply to elements of unknown length. > > and in the markdown it renders to > > See the section on Element Data Size > <https://github.com/Matroska-Org/ebml-specification/blob/master/specification.markdown#element-data-size> > for rules that apply to elements of unknown length. > > > I added some issues to the flac_markdown repository and Andrew addressed > them in https://github.com/privatezero/flac_markdown/pull/7. Most of > these issues pertain to unintended semantic differences between the FLAC > specification as it exists in its original HTML form at > https://xiph.org/flac/format.html and the markdown rendition being worked > on at https://github.com/privatezero/flac_markdown/blob/master/flac.md. > > 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: > - verifying semantic equalness with the html version > - resolving issues that block the mmark/xml2rfc process that generates the > RFC formats of the specification > - add standard RFC boilerplate (abstract, rfc2119, etc) > > > 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 xiph.org site. In order to get the > structural data (such as the tables at the end of https://xiph.org/flac/ > format.html) 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 > https://xiph.org/flac/format.html#frame_header compared to the dissected > version which gives the subcomponents their own subsequent sections at > https://github.com/privatezero/flac_markdown/blob/ > 7a5c21d49d1fda89609ffa9edfca2447c7ca3c5e/flac.md#frame_header. Splitting > out the subcomponents into their own sections also gives space to be more > explicate in defining them, such as https://github.com/ > privatezero/flac_markdown/commit/3aaa5f293102018bd7c41409e79e36f510557d96. > > 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? > > For convenience, here is a rendering of the plain text RFC output of > git-master of the FLAC format repository: https://gist.github.com/dericed/ > 2639d0eed5e064b4dec1399bc8716833. > > 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. > > Best Regards, > Dave Rice > > _______________________________________________ > Cellar mailing list > Cellar at ietf.org > https://www.ietf.org/mailman/listinfo/cellar > >-- Andrew Weaver, MLIS American Archive of Public Broadcasting National Digital Stewardship Resident @ CUNY TV weevz at uw.edu -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.xiph.org/pipermail/flac-dev/attachments/20170605/64f31b3c/attachment.html>
Andrew, I think it is neither Rice Coding nor Exponential Golomb Coding. The one used in FLAC is Golomb-Rice coding, which is almost optimal for the Laplace (exponential) statistical distribution of residuals after modelling. Best regards, Federico On 06/06/2017 0:52, Andrew James Weaver wrote:> Hello all! > (cc-ing the flac-dev list) > > I would like to give an update as to the recent CELLAR work on the > FLAC specification. > > • Work has been done to make internal and external links more accurate > and reliable. > • 'Rice Coding' has been clarified as 'Exponential Golomb Coding.' > • Clarifications have been made for binary representation. > • Typos and other small changes have been fixed for clarity. > > Lastly, a version 00 release has been made (available at > https://github.com/privatezero/flac_markdown/releases) and the draft > document has been uploaded to the IETF datatracker > (https://datatracker.ietf.org/doc/draft-xiph-cellar-flac/) > > All the best! > Andrew Weaver > > On Mon, May 22, 2017 at 11:06 AM, Dave Rice <dave at dericed.com > <mailto:dave at dericed.com>> wrote: > > >> On May 12, 2017, at 1:05 PM, Dave Rice <dave at dericed.com >> <mailto:dave at dericed.com>> wrote: >> >> Hi all, >> And cc'ing flac-dev. >> >>> On May 10, 2017, at 12:15 PM, Dave Rice <dave at dericed.com >>> <mailto:dave at dericed.com>> wrote: >>> >>> Hi Andrew, >>> >>>> On May 10, 2017, at 11:19 AM, Andrew James Weaver <weevz at uw.edu >>>> <mailto:weevz at uw.edu>> wrote: >>>> >>>> Hello all! >>>> >>>> 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. >>>> >>>> Currently that work is living >>>> herehttps://github.com/privatezero/flac_markdown >>>> <https://github.com/privatezero/flac_markdown>. >>> >>> I sent a pull request at >>> https://github.com/privatezero/flac_markdown/pull/1 >>> <https://github.com/privatezero/flac_markdown/pull/1>, 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: >>> >>> [*SUBFRAME\_VERBATIM*](#subframe_verbatim) >>> >>> won't render as expected in a plain text RFC, but would simply >>> render to something like "Section X.X.X". >>> >>> In EBML we use markdown such as >>> See [the section on `Element Data Size`](#element-data-size) for rules that apply to elements of unknown length. >>> so that in the RFC this renders to >>> See Section 7 for rules that apply to elements of unknown length. >>> and in the markdown it renders to >>> >>> Seethe section on|Element Data Size| >>> <https://github.com/Matroska-Org/ebml-specification/blob/master/specification.markdown#element-data-size>for >>> rules that apply to elements of unknown length. >> >> I added some issues to the flac_markdown repository and Andrew >> addressed them >> inhttps://github.com/privatezero/flac_markdown/pull/7 >> <https://github.com/privatezero/flac_markdown/pull/7>. Most of >> these issues pertain to unintended semantic differences between >> the FLAC specification as it exists in its original HTML form at >> https://xiph.org/flac/format.html >> <https://xiph.org/flac/format.html>and the markdown rendition >> being worked on at >> https://github.com/privatezero/flac_markdown/blob/master/flac.md >> <https://github.com/privatezero/flac_markdown/blob/master/flac.md>. >> >> 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: >> - verifying semantic equalness with the html version >> - resolving issues that block the mmark/xml2rfc process that >> generates the RFC formats of the specification >> - add standard RFC boilerplate (abstract, rfc2119, etc) > > 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 xiph.org > <http://xiph.org> site. In order to get the structural data (such > as the tables at the end of https://xiph.org/flac/format.html > <https://xiph.org/flac/format.html>) 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 > https://xiph.org/flac/format.html#frame_header > <https://xiph.org/flac/format.html#frame_header> compared to the > dissected version which gives the subcomponents their own > subsequent sections at > https://github.com/privatezero/flac_markdown/blob/7a5c21d49d1fda89609ffa9edfca2447c7ca3c5e/flac.md#frame_header > <https://github.com/privatezero/flac_markdown/blob/7a5c21d49d1fda89609ffa9edfca2447c7ca3c5e/flac.md#frame_header>. > Splitting out the subcomponents into their own sections also gives > space to be more explicate in defining them, such as > https://github.com/privatezero/flac_markdown/commit/3aaa5f293102018bd7c41409e79e36f510557d96 > <https://github.com/privatezero/flac_markdown/commit/3aaa5f293102018bd7c41409e79e36f510557d96>. > > 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? > > For convenience, here is a rendering of the plain text RFC output > of git-master of the FLAC format repository: > https://gist.github.com/dericed/2639d0eed5e064b4dec1399bc8716833 > <https://gist.github.com/dericed/2639d0eed5e064b4dec1399bc8716833>. > > 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. > > Best Regards, > Dave Rice > > _______________________________________________ > Cellar mailing list > Cellar at ietf.org <mailto:Cellar at ietf.org> > https://www.ietf.org/mailman/listinfo/cellar > <https://www.ietf.org/mailman/listinfo/cellar> > > > > > -- > Andrew Weaver, MLIS > American Archive of Public Broadcasting > National Digital Stewardship Resident @ CUNY TV > weevz at uw.edu <mailto:weevz at uw.edu> > > > _______________________________________________ > flac-dev mailing list > flac-dev at xiph.org > http://lists.xiph.org/mailman/listinfo/flac-dev-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.xiph.org/pipermail/flac-dev/attachments/20170606/f37017ad/attachment-0001.html>
Hi all,> On Jun 5, 2017, at 11:52 PM, Andrew James Weaver <weevz at uw.edu> wrote: > > Hello all! > (cc-ing the flac-dev list) > > I would like to give an update as to the recent CELLAR work on the FLAC specification. > > • Work has been done to make internal and external links more accurate and reliable. > • 'Rice Coding' has been clarified as 'Exponential Golomb Coding.' > • Clarifications have been made for binary representation. > • Typos and other small changes have been fixed for clarity. > > Lastly, a version 00 release has been made (available at https://github.com/privatezero/flac_markdown/releases <https://github.com/privatezero/flac_markdown/releases>) and the draft document has been uploaded to the IETF datatracker (https://datatracker.ietf.org/doc/draft-xiph-cellar-flac/ <https://datatracker.ietf.org/doc/draft-xiph-cellar-flac/>) > > All the best! > Andrew WeaverFrom a review of the markdown and the rendered RFC, I’d like to consider renaming many of the components of FLAC from the ALL_CAPS_WITH_UNDERSCORE_STYLE to `Title Case Names in BackTicks` (which is similar to how local components have been named and referenced in the FFV1 and Matroska documents). Thus “METADATA_BLOCK_HEADER” would be `Metadata Block Header` and expressed with that same case and quoting at each reference. I also suggest that the metadata block types such as “METADATA_BLOCK_STREAMINFO” and “METADATA_BLOCK_APPLICATION” simply be renamed as `Streaminfo Block` and `Application Block` and that each of those components be defined as being a `Metadata Block`. I may send a pull request for this soon but wanted to ask around in case there’s some reason for or advantage of the ALL_CAPS_WITH_UNDERSCORE_STYLE that I’m missing. Best Regards, Dave Rice -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.xiph.org/pipermail/flac-dev/attachments/20170606/343a1482/attachment.html>
Hi Dave, I don't have older FLAC sources handy to check, but I believe that text like METADATA_BLOCK_HEADER was taken literally from the C language header files. These days, I believe that such types have been renamed like FLAC__METADATA_TYPE_HEADER to avoid potential conflicts with libraries outside the FLAC realm. I don't think that the outdated labels should remain, but rather than convert them to human language text, I think it would be a more worthwhile effort to simply update these all-caps labels to match the current source code. That would be slightly more work than your proposal, because you'd have to search for the exact structure names in the latest sources, but it would be infinitely more useful to those who read the spec. It is my opinion that most people who are looking into low-level details like headers and meta data format will all be working with one or both of the C language FLAC or C++ language FLAC++ libraries. I think that's the advantage you're looking for. The FLAC libraries have been ported to all major operating systems as well as many embedded platforms, so this C language is quite prevalent. Brian Willoughby Sound Consulting On Jun 6, 2017, at 5:23 PM, Dave Rice <dave at dericed.com> wrote:> Hi all, > > On Jun 5, 2017, at 11:52 PM, Andrew James Weaver <weevz at uw.edu> wrote: >> Hello all! >> (cc-ing the flac-dev list) >> >> I would like to give an update as to the recent CELLAR work on the FLAC specification. >> >> • Work has been done to make internal and external links more accurate and reliable. >> • 'Rice Coding' has been clarified as 'Exponential Golomb Coding.' >> • Clarifications have been made for binary representation. >> • Typos and other small changes have been fixed for clarity. >> >> Lastly, a version 00 release has been made (available at https://github.com/privatezero/flac_markdown/releases) and the draft document has been uploaded to the IETF datatracker (https://datatracker.ietf.org/doc/draft-xiph-cellar-flac/) > > From a review of the markdown and the rendered RFC, I’d like to consider renaming many of the components of FLAC from the ALL_CAPS_WITH_UNDERSCORE_STYLE to `Title Case Names in BackTicks` (which is similar to how local components have been named and referenced in the FFV1 and Matroska documents). Thus “METADATA_BLOCK_HEADER” would be `Metadata Block Header` and expressed with that same case and quoting at each reference. I also suggest that the metadata block types such as “METADATA_BLOCK_STREAMINFO” and “METADATA_BLOCK_APPLICATION” simply be renamed as `Streaminfo Block` and `Application Block` and that each of those components be defined as being a `Metadata Block`. > > I may send a pull request for this soon but wanted to ask around in case there’s some reason for or advantage of the ALL_CAPS_WITH_UNDERSCORE_STYLE that I’m missing.-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.xiph.org/pipermail/flac-dev/attachments/20170606/71ac8a88/attachment.html>