[flac-dev] [Cellar] FLAC Markdown

Dave Rice
Fri, 12 May 2017 17:05:42 -0000

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>