spec: split up sections to separate .md files

[SteveLasker]

The distribution spec currently has greater than 4,500 lines. Attempting to find or edit a section becomes a tedious task.

Issue is to break the spec up into logical units, similar to the image-spec.

[vbatts]

👍

…

On Sat, May 11, 2019 at 8:58 PM Steve Lasker ***@***.***> wrote: The distribution spec <https://github.com/opencontainers/distribution-spec/blob/master/spec.md> currently has greater than 4,500 lines. Attempting to find or edit a section becomes a tedious task. Issue is to break the spec up into logical units, similar to the image-spec <https://github.com/opencontainers/image-spec/>. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#62>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAQL2MEXGAMWBJZRRWY4Q3PU5TTRANCNFSM4HMJJBTA> .

[jzelinskie]

As long as the split makes sense; I find that the image spec's layout is suboptimal because it jumps across files and sometimes has cyclic references. On Mon, May 13, 2019 at 8:42 AM Vincent Batts <[email protected]> wrote:

…

👍 On Sat, May 11, 2019 at 8:58 PM Steve Lasker ***@***.***> wrote: > The distribution spec > <https://github.com/opencontainers/distribution-spec/blob/master/spec.md > > currently has greater than 4,500 lines. Attempting to find or edit a > section becomes a tedious task. > > Issue is to break the spec up into logical units, similar to the > image-spec <https://github.com/opencontainers/image-spec/>. > > — > You are receiving this because you are subscribed to this thread. > Reply to this email directly, view it on GitHub > <#62>, or mute > the thread > < https://github.com/notifications/unsubscribe-auth/AAAQL2MEXGAMWBJZRRWY4Q3PU5TTRANCNFSM4HMJJBTA > > . > — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#62?email_source=notifications&email_token=AACT342RA2IPBFANNJBZDBDPVFO35A5CNFSM4HMJJBTKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODVIF6FA#issuecomment-491806484>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AACT34ZYP4H4O7Q2LMWPNG3PVFO35ANCNFSM4HMJJBTA> .

[SteveLasker]

I’ll make a TOC proposal for review, before making a split up PR

[SteveLasker]

As I started to consider a new TOC, I wondered what opinions were on links to the current spec, including anchors.
Before I make a new TOC proposal, would some block is it could break links like: https://github.com/opencontainers/distribution-spec/blob/master/spec.md#initiate-blob-upload
I suppose I could put a list of headings in the footer as forwarders

Link Cross Refernece

Initiate Blob Upload

moved here

[jonjohnsonjr]

As long as the split makes sense; I find that the image spec's layout is suboptimal because it jumps across files and sometimes has cyclic references.

I tend to agree. GitHub's search is... not great, so splitting across pages makes it nearly impossible to find anything. Right now I can just Ctrl+F within the page.

[vbatts]

lets not split up just now. Instead lets look at the reorg #126