runtime: Transition from Markdown to AsciiDoc

There's a bit of hoop-jumping here for syntax highlighting.  asciidoc
(the command) can generate highted HTML (and the source-highlighter
line in oci-runtime-spec.asc sets it up to use Pygments).  However,
asciidoc's direct HTML output does not support xref default captions
[1].  asciidoc's DocBook output, on the other hand, *does* support
default captions [1].  Unfortunately, in this case asciidoc punts the
syntax highlighting to DocBook as well, passing through a
programlisting tag [2,3].  Unfortunately, syntax highlighting there
depends on an XSLTHL extension module which is only implemented in
Java [4,5], and that's not worth the trouble ;).

Highlighting is a bit easier for the PDF output, because while
asciidoc is still delegating to DocBook, DocBook is in turn delegating
to LaTeX and listings.  Listings v1.6 doesn't support JavaScript or
JSON, but it does support Python [6], and Python's dict, list, string,
and number syntax is very close to JSON's object, array, string, and
number syntax.  To setup that mapping, we copy the usual
asciidoc-dblatex.sty from the system, add a json -> python alias, and
tell dblatex to use our amended style.

Also bump the section numbering depth back up to DocBook's default 8
[7].  For some reason, the default a2x output seems to set this to 2.
And bump the number of ToC levels up from two to four [8].

An anchor's default captions [9] seem to be treated literally without
further parsing.  So [[created,`created`]] will lead to references
like a regularly-styled "`created`" instead of the intended monospace
"created".  Monospace isn't worth jumping through lots of hoops for
though, so I've just left the backticks off and leaned on the link
highlighting to set the should-be-literals off from surrounding text.

The [[create,create]] anchors avoid auto-generated captions like:

  Section 5.4.2, "Create"

because we usually use those references as stand-ins for an invokable
command (e.g. `funC create ...`).

[1]: http://asciidoc.org/userguide.html#_xref
[2]: http://asciidoc.org/source-highlight-filter.html#_docbook_outputs
[3]: http://docbook.org/tdg/en/html/programlisting.html
[4]: http://docbook.sourceforge.net/release/xsl/1.79.1/doc/html/highlight.source.html
[5]: https://sourceforge.net/p/xslthl/wiki/Home/
[6]: http://mirrors.ctan.org/macros/latex/contrib/listings/listings.pdf#page=13
[7]: http://docbook.sourceforge.net/release/xsl/1.79.1/doc/html/section.autolabel.max.depth.html
[8]: http://asciidoc.org/faq.html#_the_asciidoc_toclevels_attribute_does_not_work_with_docbook_outputs_why
[9]: http://asciidoc.org/userguide.html#X30
     anchor

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

.gitignore

@@ -1,4 +1,5 @@
 output
 schema/validate
+asciidoc-dblatex-json.sty
 code-of-conduct.md
 version.md

Makefile

@@ -4,6 +4,7 @@ OUTPUT_DIRNAME		?= output
 DOC_FILENAME		?= oci-runtime-spec
 A2X			?= $(shell command -v a2x 2>/dev/null)
 DBLATEX			?= $(shell command -v dblatex 2>/dev/null)
+DBLATEX_DIR		?= /usr/share/asciidoc/dblatex
 
 # These docs are in an order that determines how they show up in the PDF/HTML docs.
 DOC_FILES := $(wildcard *.asc)
@@ -17,9 +18,13 @@ ifeq "$(strip $(A2X) $(DBLATEX))" ''
 $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf:
 	$(error cannot build $@ without a2x and dblatex)
 else
-$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES)
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES) asciidoc-dblatex.sty
 	mkdir -p $(OUTPUT_DIRNAME)
-	$(A2X) -f pdf --no-xmllint $(ASCIIDOC_SRC)$(DOC_FILENAME).asc
+	$(A2X) -f pdf --no-xmllint \
+		--xsltproc-opts '--stringparam section.autolabel.max.depth 8' \
+		--dblatex-opts '-s $(ASCIIDOC_SRC)asciidoc-dblatex.sty' \
+		--dblatex-opts '--param toc.section.depth=4' \
+		$(ASCIIDOC_SRC)$(DOC_FILENAME).asc
 	mv $(ASCIIDOC_SRC)$(DOC_FILENAME).pdf $@
 endif
 
@@ -29,9 +34,18 @@ $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html:
 else
 $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(DOC_FILES)
 	mkdir -p $(OUTPUT_DIRNAME)
-	$(A2X) -f xhtml --no-xmllint -D $(OUTPUT_DIRNAME) $(ASCIIDOC_SRC)$(DOC_FILENAME).asc
+	$(A2X) -f xhtml --no-xmllint \
+		--xsltproc-opts '--stringparam section.autolabel.max.depth 8' \
+		--xsltproc-opts '--stringparam toc.section.depth 4' \
+		-D $(OUTPUT_DIRNAME) \
+		$(ASCIIDOC_SRC)$(DOC_FILENAME).asc
 endif
 
+asciidoc-dblatex.sty: $(DBLATEX_DIR)/asciidoc-dblatex.sty
+	cp $< $@
+	echo '\usepackage{listings}' >>$@
+	echo '\lstalias{json}{python}' >>$@
+
 code-of-conduct.md:
 	curl -o $@ https://raw.githubusercontent.com/opencontainers/tob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md
 
@@ -83,5 +97,5 @@ endif
 .PHONY: clean
 clean:
 	rm -rf $(OUTPUT_DIRNAME) *~
-	rm -f code-of-conduct.md version.md
+	rm -f asciidoc-dblatex-json.sty code-of-conduct.md version.md
 

config-windows.md renamed to config-windows.asc

@@ -19,3 +19,5 @@ include::definitions.asc[]
 include::protocols.asc[]
 
 include::bundle.asc[]
+
+include::runtime.asc[]

oci-runtime-spec.asc

@@ -3,6 +3,6 @@ Protocols
 
 Protocols defined by this specification are:
 
-* Linux containers: `<<runtime>>`, `<<runtime-linux>>`, `<<config>>`, and `<<config-linux>>`.
-* Solaris containers: `<<runtime>>`, `<<config>>`, and `<<config-solaris>>`.
-* Windows containers: `<<runtime>>`, `<<config>>`, and `<<config-windows>>`.
+* Linux containers: <<runtime>>, `<<runtime-linux>>`, `<<config>>`, and `<<config-linux>>`.
+* Solaris containers: <<runtime>>, `<<config>>`, and `<<config-solaris>>`.
+* Windows containers: <<runtime>>, `<<config>>`, and `<<config-windows>>`.

protocols.asc

@@ -0,0 +1,190 @@
+[[runtime]]
+Runtime and Lifecycle
+---------------------
+
+:implementation-testing: https://github.com/opencontainers/runtime-spec/blob/master/implementations.md#testing--tools
+
+Scope of a Container
+~~~~~~~~~~~~~~~~~~~~
+
+Barring access control concerns, the entity using a runtime to create a container MUST be able to use the operations defined in this specification against that same container.
+Whether other entities using the same, or other, instance of the runtime can see that container is out of scope of this specification.
+
+[[state]]
+State
+^^^^^
+
+The state of a container MUST include, at least, the following properties:
+
+[[ociVersion-state,ociVersion]]
+`ociVersion`::
+  (string) is the OCI specification version `<<ociVersion-config,used when creating the container>>`.
+
+[[id,id]] `id`::
+  (string) is the container's ID.
+  This MUST be unique across all containers on this host.
+  There is no requirement that it be unique across hosts.
+
+[[status,status]] `status`::
+  (string) is the runtime state of the container.
+  The value MAY be one of:
++
+--
+[[created,created]] `created`:::
+  The container has been created but the user-specified code has not yet been executed.
+
+[[running,running]] `running`:::
+  The container has been created and the user-specified code is running.
+
+[[stopped,stopped]] `stopped`:::
+  The container has been created and the user-specified code has been executed but is no longer running.
+
+Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above.
+--
+
+[[pid,pid]] `pid`::
+  (int) is the ID of the container process, as seen by the host.
+
+[[bundlePath,bundlePath]] `bundlePath`::
+  (string) is the absolute path to the container's bundle directory.
+  This is provided so that consumers can find the container's configuration and root filesystem on the host.
+
+[[state-annotations,state annotations]] `annotations`::
+  (map) contains the list of annotations associated with the container.
+  If no annotations were provided then this property MAY either be absent or an empty map.
+
+When serialized in JSON, the format MUST adhere to the following pattern:
+
+[source,json]
+{
+    "ociVersion": "0.2.0",
+    "id": "oci-container1",
+    "status": "running",
+    "pid": 4422,
+    "bundlePath": "/containers/redis",
+    "annotations": {
+        "myKey": "myValue"
+    }
+}
+
+See <<state-operation>> for information on retrieving the state of a container.
+
+Lifecycle
+~~~~~~~~~
+
+The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist.
+
+. [[lifecycle-create-call, step 1]]
+  OCI compliant runtime's <<create>> command is invoked with a reference to the location of the bundle and a unique identifier.
+
+. [[lifecycle-create,step 2]]
+  The container's runtime environment MUST be created according to the configuration in `<<config>>`.
+  If the runtime is unable to create the environment specified in the `<<config>>`, it MUST generate an error.
+  While the resources requested in the `<<config>>` MUST be created, the user-specified code (from `<<process>>`) MUST NOT be run at this time.
+  Any updates to `<<config>>` after this step MUST NOT affect the container.
+
+. [[lifecycle-pre-start,step 3]]
+  Once the container is created additional actions MAY be performed based on the features the runtime chooses to support.
+  However, some actions might only be available based on the current state of the container (e.g. only available while it is started).
+
+. [[lifecycle-start,step 4]]
+  Runtime's <<start>> command is invoked with the unique identifier of the container.
+  The runtime MUST run the user-specified code, as specified by `<<process>>`.
+
+. [[lifecycle-exit,step 5]]
+  The container's process is stopped.
+  This MAY happen due to them erroring out, exiting, crashing or the runtime's <<kill>> operation being invoked.
+
+
+. [[lifecycle-delete,step 6]]
+  Runtime's <<delete>> command is invoked with the unique identifier of the container.
+  The container MUST be destroyed by undoing the steps performed during create phase (<<lifecycle-create>>).
+
+Errors
+~~~~~~
+
+In cases where the specified operation generates an error, this specification does not mandate how, or even if, that error is returned or exposed to the user of an implementation.
+Unless otherwise stated, generating an error MUST leave the state of the environment as if the operation were never attempted - modulo any possible trivial ancillary changes such as logging.
+
+Operations
+~~~~~~~~~~
+
+OCI compliant runtimes MUST support the following operations, unless the operation is not supported by the base operating system.
+
+[NOTE]
+These operations are not specifying any command line APIs, and the parameters are inputs for general operations.
+
+[[state-operation]]
+[caption="foo bar"]
+State
+^^^^^
+
+`state <container-id>`
+
+This operation MUST generate an error if it is not provided the ID of a container.
+Attempting to query a container that does not exist MUST generate an error.
+This operation MUST return the state of a container as specified in <<state>>.
+
+[[create,create]]
+Create
+^^^^^^
+
+`create <container-id> <path-to-bundle>`
+
+This operation MUST generate an error if it is not provided a path to the bundle and the container ID to associate with the container.
+If the ID provided is not unique across all containers within the scope of the runtime, or is not valid in any other way, the implementation MUST generate an error and a new container MUST NOT be created.
+Using the data in `<<config,config.json>>`, this operation MUST create a new container.
+This means that all of the resources associated with the container MUST be created, however, the user-specified code MUST NOT be run at this time.
+If the runtime cannot create the container as specified in `<<config,config.json>>`, it MUST generate an error and a new container MUST NOT be created.
+
+Upon successful completion of this operation the <<status>> property of this container MUST be <<created>>.
+
+The runtime MAY validate `config.json` against this spec, either generically or with respect to the local system capabilities, before creating the container (<<lifecycle-create>>).
+Runtime callers who are interested in pre-create validation can run {implementation-testing}[bundle-validation tools] before invoking the create operation.
+
+Any changes made to the `<<config>>` after this operation will not have an effect on the container.
+
+[[start,start]]
+Start
+^^^^^
+
+`start <container-id>`
+
+This operation MUST generate an error if it is not provided the container ID.
+Attempting to start a container that does not exist MUST generate an error.
+Attempting to start an already started container MUST have no effect on the container and MUST generate an error.
+This operation MUST run the user-specified code as specified by `<<process>>`.
+
+Upon successful completion of this operation the <<status>> property of this container MUST be <<running>>.
+
+[[kill,kill]]
+Kill
+^^^^
+
+`kill <container-id> <signal>`
+
+This operation MUST generate an error if it is not provided the container ID.
+Attempting to send a signal to a container that is not running MUST have no effect on the container and MUST generate an error.
+This operation MUST send the specified signal to the process in the container.
+
+When the process in the container is stopped, irrespective of it being as a result of a `kill` operation or any other reason, the <<status>> property of this container MUST be <<stopped>>.
+
+[[delete,delete]]
+Delete
+^^^^^^
+
+`delete <container-id>`
+
+This operation MUST generate an error if it is not provided the container ID.
+Attempting to delete a container that does not exist MUST generate an error.
+Attempting to delete a container whose process is still running MUST generate an error.
+Deleting a container MUST delete the resources that were created during <<lifecycle-create>>.
+Note that resources associated with the container, but not created by this container, MUST NOT be deleted.
+Once a container is deleted its ID MAY be used by a subsequent container.
+
+[[runtime-hooks]]
+Hooks
+^^^^^
+
+Many of the operations specified in this specification have "hooks" that allow for additional actions to be taken before or after each operation.
+See `<<hooks>>` for more information.