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 <d...@dericed.com> wrote: > > On May 12, 2017, at 1:05 PM, Dave Rice <d...@dericed.com> wrote: > > Hi all, > And cc'ing flac-dev. > > On May 10, 2017, at 12:15 PM, Dave Rice <d...@dericed.com> wrote: > > Hi Andrew, > > On May 10, 2017, at 11:19 AM, Andrew James Weaver <we...@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 > cel...@ietf.org > https://www.ietf.org/mailman/listinfo/cellar > > -- Andrew Weaver, MLIS American Archive of Public Broadcasting National Digital Stewardship Resident @ CUNY TV we...@uw.edu
_______________________________________________ flac-dev mailing list flac-dev@xiph.org http://lists.xiph.org/mailman/listinfo/flac-dev
