Transition from Markdown to AsciiDoc

.gitignore

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

Makefile

@@ -1,59 +1,51 @@
 
 EPOCH_TEST_COMMIT	:= 78e6667ae2d67aad100b28ee9580b41b7a24e667
-OUTPUT_DIRNAME		?= output/
+OUTPUT_DIRNAME		?= output
 DOC_FILENAME		?= oci-runtime-spec
-DOCKER			?= $(shell command -v docker 2>/dev/null)
-PANDOC			?= $(shell command -v pandoc 2>/dev/null)
-ifeq "$(strip $(PANDOC))" ''
-	ifneq "$(strip $(DOCKER))" ''
-		PANDOC = $(DOCKER) run \
-			-it \
-			--rm \
-			-v $(shell pwd)/:/input/:ro \
-			-v $(shell pwd)/$(OUTPUT_DIRNAME)/:/$(OUTPUT_DIRNAME)/ \
-			-u $(shell id -u) \
-			vbatts/pandoc
-		PANDOC_SRC := /input/
-		PANDOC_DST := /
-	endif
-endif
+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 := \
-	version.md \
-	README.md \
-	code-of-conduct.md \
-	principles.md \
-	style.md \
-	ROADMAP.md \
-	implementations.md \
-	project.md \
-	bundle.md \
-	runtime.md \
-	runtime-linux.md \
-	config.md \
-	config-linux.md \
-	config-solaris.md \
-	glossary.md
+DOC_FILES := $(wildcard *.asc)
 
 default: docs
 
 .PHONY: docs
 docs: $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html
 
-ifeq "$(strip $(PANDOC))" ''
-$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html:
-	$(error cannot build $@ without either pandoc or docker)
+ifeq "$(strip $(A2X) $(DBLATEX))" ''
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf:
+	$(error cannot build $@ without a2x and dblatex)
 else
-$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES)
-	mkdir -p $(OUTPUT_DIRNAME)/ && \
-	$(PANDOC) -f markdown_github -t latex -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES) asciidoc-dblatex.sty
+	mkdir -p $(OUTPUT_DIRNAME)
+	$(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
 
+ifeq "$(strip $(A2X))" ''
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).html:
+	$(error cannot build $@ without a2x)
+else
 $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(DOC_FILES)
-	mkdir -p $(OUTPUT_DIRNAME)/ && \
-	$(PANDOC) -f markdown_github -t html5 -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
+	mkdir -p $(OUTPUT_DIRNAME)
+	$(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
 
@@ -105,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
 

README.md

@@ -23,37 +23,6 @@ Table of Contents
     - [Windows-specific Configuration](config-windows.md)
 - [Glossary](glossary.md)
 
-In the specifications in the above table of contents, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997).
-
-The keywords "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified].
-
-An implementation is not compliant for a given CPU architecture if it fails to satisfy one or more of the MUST, REQUIRED, or SHALL requirements for the protocols it implements.
-An implementation is compliant for a given CPU architecture if it satisfies all the MUST, REQUIRED, and SHALL requirements for the protocols it implements.
-
-Protocols defined by this specification are:
-* Linux containers: [runtime.md](runtime.md), [config.md](config.md), [config-linux.md](config-linux.md), and [runtime-linux.md](runtime-linux.md).
-* Solaris containers: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md).
-* Windows containers: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md).
-
-# Use Cases
-
-To provide context for users the following section gives example use cases for each part of the spec.
-
-#### Application Bundle Builders
-
-Application bundle builders can create a [bundle](bundle.md) directory that includes all of the files required for launching an application as a container.
-The bundle contains an OCI [configuration file](config.md) where the builder can specify host-independent details such as [which executable to launch](config.md#process-configuration) and host-specific settings such as [mount](config.md#mounts) locations, [hook](config.md#hooks) paths, Linux [namespaces](config-linux.md#namespaces) and [cgroups](config-linux.md#control-groups).
-Because the configuration includes host-specific settings, application bundle directories copied between two hosts may require configuration adjustments.
-
-#### Hook Developers
-
-[Hook](config.md#hooks) developers can extend the functionality of an OCI-compliant runtime by hooking into a container's lifecycle with an external application.
-Example use cases include sophisticated network configuration, volume garbage collection, etc.
-
-#### Runtime Developers
-
-Runtime developers can build runtime implementations that run OCI-compliant bundles and container configuration, containing low-level OS and host specific details, on a particular platform.
-
 # Releases
 
 There is a loose [Road Map](./ROADMAP.md).

asciidoc.conf

@@ -0,0 +1,11 @@
+# http://asciidoc.org/faq.html#_how_do_i_number_all_paragraphs
+
+[paragraph]
+{counter2:paracounter}
+{set2:pid:{id?{id}}{id!_para-{paracounter}}}
+{title#}<formalpara id="{pid}"{role? role="{role}"} xreflabel="¶"><title>{title}</title><para>
+{title%}<simpara id="{pid}"{role? role="{role}"} xreflabel="¶">
+|
+{title%}<superscript><xref linkend="{pid}" /></superscript></simpara>
+{title#}<superscript><xref linkend="{pid}" /></superscript></para></formalpara>
+{empty}

bundle.md → bundle.asc

@@ -1,22 +1,24 @@
-# Filesystem Bundle
+[[bundle,bundle]]
+Filesystem Bundle
+-----------------
 
-## Container Format
+:os-x-bundle: http://en.wikipedia.org/wiki/Bundle_%28OS_X%29
 
-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*.
+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-bundle}[OS X application bundles] for a similar use of the term _bundle_.
 
 The definition of a bundle is only concerned with how a container, and its configuration data, are stored on a local filesystem so that it can be consumed by a compliant runtime.
 
 A Standard Container bundle contains all the information needed to load and run a container.
 This MUST include the following artifacts:
 
 1. `config.json`: contains configuration data.
-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.
+   This REQUIRED file MUST reside in the root of the bundle directory and MUST be named `config.json`.
+   See <<config>> for more details.
 
 2. 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.
+   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.
 
 While these artifacts MUST all be present in a single directory on the local filesystem, that directory itself is not part of the bundle.
-In other words, a tar archive of a *bundle* will have these artifacts at the root of the archive, not nested within a top-level directory.
+In other words, a tar archive of a _bundle_ will have these artifacts at the root of the archive, not nested within a top-level directory.