Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

glossary: Provide a quick overview of important terms #107

Merged
merged 2 commits into from
Dec 24, 2015
Merged

glossary: Provide a quick overview of important terms #107

merged 2 commits into from
Dec 24, 2015

Commits on Dec 23, 2015

  1. glossary: Provide a quick overview of important terms 

    And link them to the more detailed specification.

Subsection titles for the entries will be obnoxiously spacious, but
the other alternatives seem worse:

a. An HTML definition list (<dl>) would have nice default styling, but
   it's annoying to write raw HTML.  And we would have needed
   something like:

     <dt name="bundle">Bundle</dt>
     <dd>

     A [directory structure](bundle.md) that is...

     </dd>

   to get Markdown-style links in the defintion itself.

b. A Markdown list (* ...) would have reasonable default styling, but
   there's no Markdown syntax for adding anchors to the entries.  And
   a glossary is much less useful if you can't link to a specific
   entry.

Signed-off-by: W. Trevor King <[email protected]>
    @wking
    wking committed Dec 23, 2015
    Configuration menu
    Copy the full SHA
    1873498 View commit details
    Browse the repository at this point in the history

  2. glossary: Specify UTF-8 for all our JSON 

    I wish there was a cleaner reference for what UTF-8 was.  But [1]
seems too glib, and I can't find a more targetted link than just
dropping folks into a Unicode chapter (which is what [1] does):

  The Unicode Standard, Version 6.0, §3.9 D92, §3.10 D95 (2011)

With the current v8.0 (2015-06-17), it's still §3.9 D92 and §3.10 D95.

I'd rather put this normative requirement in the configuration-spec
files, but maintainer consensus was to put it in the glossary [2,3].

[1]: https://en.wikipedia.org/wiki/UTF-8
[2]: opencontainers#146 (comment)
[3]: opencontainers#146 (comment)

Signed-off-by: W. Trevor King <[email protected]>
    @wking
    wking committed Dec 23, 2015
    Configuration menu
    Copy the full SHA
    0f9ec22 View commit details
    Browse the repository at this point in the history