[flac-dev] [Cellar] FLAC Markdown

Dave Rice
Mon, 22 May 2017 18:06:29 -0000

> 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
<mailto: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
<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
<https://xiph.org/flac/format.html> and the markdown rendition being
worked on at https://github.com/privatezero/flac_markdown/blob/master/flac.md
<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
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.xiph.org/pipermail/flac-dev/attachments/20170522/22d8aa8e/attachment.html>