[Bundle] Adds anchor tags for headings and bullets #612
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| # <a name="filesystemBundle" />Filesystem Bundle | ||
|
|
||
| ## <a name="containerFormat" />Container Format | ||
|
|
||
| This section defines a format for encoding a container as a *filesystem bundle* - a set of files organized in a certain way, and containing all the necessary data and metadata for any compliant runtime to perform all standard operations against it. | ||
| See also [OS X application bundles](http://en.wikipedia.org/wiki/Bundle_%28OS_X%29) for a similar use of the term *bundle*. | ||
|
|
@@ -10,11 +10,11 @@ The definition of a bundle is only concerned with how a container, and its confi | |
| A Standard Container bundle contains all the information needed to load and run a container. | ||
| This MUST include the following artifacts: | ||
|
|
||
| 1. <a name="containerFormat01" />`config.json`: contains configuration data. | ||
|
There was a problem hiding this comment. These anchors look good to me, although I think we should stick to the lowercase, hyphenated form that GitHub and Pandoc are using already for headers. In that case, the name here would be There was a problem hiding this comment. Does it make sense to actually not be hyphenated so we can distinguish them from github/pandoc anchors? There was a problem hiding this comment.
If we're going to anchor everything independently of GitHub / Pandoc, I'd rather just use a language that adds anchors for us (#615). If we stick with Markdown, I'd rather use the GitHub / Pandoc anchors where they're generated, and only add occasional manual anchors where needed. If you're worried about conflicts between manual and auto-generated anchors, I think having a consistent fragment style is more important. Just chose anchor names that are unlikely to be autogenerated from slugs. |
||
| This REQUIRED file MUST reside in the root of the bundle directory and MUST be named `config.json`. | ||
| See [`config.json`](config.md) for more details. | ||
|
|
||
| 2. <a name="containerFormat02" />A directory representing the root filesystem of the container. | ||
| While the name of this REQUIRED directory may be arbitrary, users should consider using a conventional name, such as `rootfs`. | ||
| This directory MUST be referenced from within the `config.json` file. | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think we need to add anchors to the headers, since both GitHub and Pandoc agree on the auto-generated
container-formatanchor (and likewise for other headers):There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The proposed PR separates the anchor tag from the header text.
This follows the recommendation from the Open API Initiative (formerly Swagger) which.
I'm hesitant to use the auto-generated anchor links from GitHub since we might change the header text (ex: adding section numbers like "4.1 Container Format" and that would change the auto-generated anchor links.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think link stability is a major issue, because folks referencing the spec should be pinning their reference to a particular version (like this). If we change the header later on, that link (pinned to v1.0.0-rc2) will still work. Even if you do attempt to provide a stable anchor between spec releases, sometimes the section will go away, or get moved to a different file, or be split into two sections, or whatever. In all of those cases the old unpinned link will no longer work regardless of any attempt at freezing the anchor. Do we really expect lots of churn in header text but minimal churn in the section or file structure?
That said, if folks do expect significant churn in header text and are happy to nip that in the bud by adding these headers to all of our existing sections, more power to 'em ;).