[flac-dev] [Cellar] FLAC Markdown

[Dave Rice]

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 <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 here https://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
> 
> 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)

Dave Rice
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.xiph.org/pipermail/flac-dev/attachments/20170512/bb9aa545/attachment.html>