[flac-dev] [Cellar] FLAC Markdown

[Brian Willoughby]

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>