[flac-dev] [Cellar] FLAC Markdown

[Andrew James Weaver]

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>