Merge pull request #348 from vbatts/anchor-examples

Anchor examples

Author: Mrunal Patel

config.md

@@ -15,7 +15,7 @@ The OpenContainer spec follows semantic versioning and retains forward and backw
 For example, if an implementation is compliant with version 1.0.1 of the spec, it is compatible with the complete 1.x series.
 NOTE that there is no guarantee for forward or backward compatibility for version 0.x.
 
-*Example*
+### Example
 
 ```json
     "ociVersion": "0.1.0"
@@ -28,7 +28,7 @@ Each container has exactly one *root filesystem*, specified in the *root* object
 * **`path`** (string, required) Specifies the path to the root filesystem for the container, relative to the path where the manifest is. A directory MUST exist at the relative path declared by the field.
 * **`readonly`** (bool, optional) If true then the root filesystem MUST be read-only inside the container. Defaults to false.
 
-*Example*
+### Example
 
 ```json
 "root": {
@@ -48,7 +48,7 @@ The parameters are similar to the ones in [the Linux mount system call](http://m
 * **`source`** (string, required) a device name, but can also be a directory name or a dummy. Windows, the volume name that is the target of the mount point. \\?\Volume\{GUID}\ (on Windows source is called target)
 * **`options`** (list of strings, optional) in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab).
 
-### Linux Example
+### Example (Linux)
 
 ```json
 "mounts": [
@@ -67,7 +67,7 @@ The parameters are similar to the ones in [the Linux mount system call](http://m
 ]
 ```
 
-### Windows Example
+### Example (Windows)
 
 ```json
 "mounts": [
@@ -118,7 +118,7 @@ For Linux-based systems the user structure has the following fields:
 
 _Note: symbolic name for uid and gid, such as uname and gname respectively, are left to upper levels to derive (i.e. `/etc/passwd` parsing, NSS, etc)_
 
-*Example (Linux)*
+### Example (Linux)
 
 ```json
 "process": {
@@ -159,7 +159,7 @@ _Note: symbolic name for uid and gid, such as uname and gname respectively, are
 
 * **`hostname`** (string, optional) as it is accessible to processes running inside.  On Linux, you can only set this if your bundle creates a new [UTS namespace][uts-namespace].
 
-*Example*
+### Example
 
 ```json
 "hostname": "mrsdalloway"
@@ -170,6 +170,8 @@ _Note: symbolic name for uid and gid, such as uname and gname respectively, are
 * **`os`** (string, required) specifies the operating system family this image must run on. Values for os must be in the list specified by the Go Language document for [`$GOOS`](https://golang.org/doc/install/source#environment).
 * **`arch`** (string, required) specifies the instruction set for which the binaries in the image have been compiled. Values for arch must be in the list specified by the Go Language document for [`$GOARCH`](https://golang.org/doc/install/source#environment).
 
+### Example
+
 ```json
 "platform": {
     "os": "linux",
@@ -216,7 +218,7 @@ The post-stop hooks are called after the container process is stopped.
 Cleanup or debugging could be performed in such a hook.
 If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
 
-*Example*
+### Example
 
 ```json
     "hooks" : {

runtime.md

@@ -20,6 +20,7 @@ This allows the hooks to perform cleanup and teardown logic after the runtime de
 This is provided so that consumers can find the container's configuration and root filesystem on the host.
 
 When serialized in JSON, the format MUST adhere to the following pattern:
+
 ```json
 {
     "ociVersion": "0.2.0",
@@ -99,8 +100,10 @@ The JSON describing the new process MUST adhere to the [Process configuration](c
 This operation MUST create a new process within the scope of the container.
 If the container is not running then this operation MUST have no effect on the container and MUST generate an error.
 Executing this operation multiple times MUST result in a new process each time.
-Example:
-```
+
+#### Example
+
+```json
 {
     "terminal": true,
     "user": {
@@ -118,6 +121,7 @@ Example:
     "cwd": "...",
 }
 ```
+
 This specification does not mandate the name of this JSON file.
 See the specification of the `config.json` file for the definition of these fields.
 The stopping, or exiting, of these secondary process MUST have no effect on the state of the container.

style.md

@@ -21,6 +21,70 @@ The redundancy reduction from removing the namespacing prefix is not useful enou
 So we have a consistent way to identify unset values ([source][optional-pointer]).
 The exceptions are entries where the Go default for the type is a no-op in the spec, in which case `omitempty` is sufficient and no pointer is needed (sources [here][no-pointer-for-slices], [here][no-pointer-for-boolean], and [here][pointer-when-updates-require-changes]).
 
+## Examples
+
+### Anchoring
+
+For any given section that provides a notable example, it is ideal to have it denoted with [markdown headers][markdown-headers].
+The level of header should be such that it is a subheader of the header it is an example of.
+
+#### Example
+
+```markdown
+## Some Topic
+
+### Some Subheader
+
+#### Further Subheader
+
+##### Example
+
+To use Further Subheader, ...
+
+### Example
+
+To use Some Topic, ...
+
+```
+
+### Content
+
+Where necessary, the values in the example can be empty or unset, but accommodate with comments regarding this intention.
+
+Where feasible, the content and values used in an example should convey the fullest use of the data structures concerned.
+Most commonly onlookers will intend to copy-and-paste a "working example".
+If the intention of the example is to be a fully utilized example, rather than a copy-and-paste example, perhaps add a comment as such.
+
+```markdown
+### Example
+```
+```json
+{
+    "foo": null,
+    "bar": ""
+}
+```
+
+**vs.**
+
+```markdown
+### Example
+
+Following is a fully populated example (not necessarily for copy/paste use)
+```
+```json
+{
+    "foo": [
+        1,
+        2,
+        3
+    ],
+    "bar": "waffles",
+    "bif": {
+        "baz": "potatoes"
+    }
+}
+```
 
 [capabilities]: config-linux.md#capabilities
 [class-id]: config-linux.md#network
@@ -30,3 +94,4 @@ The exceptions are entries where the Go default for the type is a no-op in the s
 [no-pointer-for-slices]: https://github.com/opencontainers/runtime-spec/pull/316/files#r50782982
 [optional-pointer]: https://github.com/opencontainers/runtime-spec/pull/233#discussion_r47829711
 [pointer-when-updates-require-changes]: https://github.com/opencontainers/runtime-spec/pull/317/files#r50932706
+[markdown-headers]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#headings