From 547e00b42e154ed8e890c0b08076ff8a5c3eb778 Mon Sep 17 00:00:00 2001 From: Vincent Batts Date: Thu, 17 Mar 2016 01:26:12 +0000 Subject: [PATCH 1/2] *.md: normalize the "example" anchors Signed-off-by: Vincent Batts --- config.md | 16 +++++++++------- runtime.md | 8 ++++++-- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/config.md b/config.md index 3201dbb5d..78a688c65 100644 --- a/config.md +++ b/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" : { diff --git a/runtime.md b/runtime.md index 1f60fb2b3..07d534b33 100644 --- a/runtime.md +++ b/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. From 7dbab778ede51550d3569f0e72d8aa39289a682b Mon Sep 17 00:00:00 2001 From: Vincent Batts Date: Thu, 17 Mar 2016 02:31:09 +0000 Subject: [PATCH 2/2] style: add a section on examples addressing: * anchoring * content of example Signed-off-by: Vincent Batts --- style.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/style.md b/style.md index bac693aae..fc501cfc0 100644 --- a/style.md +++ b/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