Hacking markdown and Makefile cleanup

- Remove/replace stale references from hacking doc.
- Add spacing for markdown.
- Add code block language for syntax highlighting.
- Remove leading "$ " from commands without output.
- Move links to end.
- Switch to automatically generated help in Makefile.

Signed-off-by: Brandon Mitchell <[email protected]>

Author: sudo-bmitch

HACKING.md

@@ -9,96 +9,97 @@ This guide contains instructions for building artifacts contained in this reposi
 This spec includes several Go packages, and a command line tool considered to be a reference implementation of the OCI image specification.
 
 Prerequisites:
+
 * Go - current release only, earlier releases are not supported
 * make
 
 The following make targets are relevant for any work involving the Go packages.
 
 ### Linting
 
-The included Go source code is being examined for any linting violations not included in the standard Go compiler. Linting is done using [gometalinter](https://github.com/alecthomas/gometalinter).
+The included Go source code is being examined for any linting violations not included in the standard Go compiler.
+Linting is done using [golangci-lint][golangci-lint].
 
 Invocation:
-```
-$ make lint
+
+```shell
+make lint
 ```
 
 ### Tests
 
 This target executes all Go based tests.
 
 Invocation:
-```
-$ make test
-$ make validate-examples
-```
-
-### Virtual schema http/FileSystem
-
-The `schema` validator uses a virtual [http/FileSystem](https://golang.org/pkg/net/http/#FileSystem) to load the JSON schema files for validating OCI images and/or manifests.
-The virtual filesystem is generated using the `esc` tool and compiled into consumers of the `schema` package so the JSON schema files don't have to be distributed along with and consumer binaries.
 
-Whenever changes are being done in any of the `schema/*.json` files, one must refresh the generated virtual filesystem.
-Otherwise schema changes will not be visible inside `schema` consumers.
-
-Prerequisites:
-* [esc](https://github.com/mjibson/esc)
-
-Invocation:
-```
-$ make schema-fs
+```shell
+make test
+make validate-examples
 ```
 
 ### JSON schema formatting
 
 This target auto-formats all JSON files in the `schema` directory using the `jq` tool.
 
 Prerequisites:
-* [jq](https://stedolan.github.io/jq/) >=1.5
+
+* [jq][jq] >=1.5
 
 Invocation:
-```
-$ make fmt
+
+```shell
+make fmt
 ```
 
 ### OCI image specification PDF/HTML documentation files
 
 This target generates a PDF/HTML version of the OCI image specification.
 
 Prerequisites:
-* [Docker](https://www.docker.com/)
+
+* [Docker][docker]
 
 Invocation:
-```
-$ make docs
+
+```shell
+make docs
 ```
 
 ### License header check
 
 This target checks if the source code includes necessary headers.
 
 Invocation:
-```
-$ make check-license
+
+```shell
+make check-license
 ```
 
 ### Clean build artifacts
 
 This target cleans all generated/compiled artifacts.
 
 Invocation:
-```
-$ make clean
+
+```shell
+make clean
 ```
 
 ### Create PNG images from dot files
 
 This target generates PNG image files from DOT source files in the `img` directory.
 
 Prerequisites:
-* [graphviz](https://www.graphviz.org/)
+
+* [graphviz][graphviz]
 
 Invocation:
+
+```shell
+make img/media-types.png
 ```
-$ make img/media-types.png
-```
+
+[docker]: https://www.docker.com/
+[golangci-lint]: https://github.com/golangci/golangci-lint
+[graphviz]: https://www.graphviz.org/
+[jq]: https://stedolan.github.io/jq/

Makefile

@@ -41,25 +41,16 @@ DOC_FILES := \
 FIGURE_FILES := \
 	img/media-types.png
 
-TOOLS := esc gitvalidation 
+TOOLS := gitvalidation 
 
 default: check-license lint test
 
-help:
-	@echo "Usage: make <target>"
-	@echo
-	@echo " * 'docs' - produce document in the $(OUTPUT_DIRNAME) directory"
-	@echo " * 'fmt' - format the json with indentation"
-	@echo " * 'validate-examples' - validate the examples in the specification markdown files"
-	@echo " * 'check-license' - check license headers in source files"
-	@echo " * 'lint' - Execute the source code linter"
-	@echo " * 'test' - Execute the unit tests"
-	@echo " * 'img/*.png' - Generate PNG from dot file"
-
-fmt:
+.PHONY: fmt
+fmt: ## format the json with indentation
 	for i in schema/*.json ; do jq --indent 2 -M . "$${i}" > xx && cat xx > "$${i}" && rm xx ; done
 
-docs: $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html
+.PHONY: docs
+docs: $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html ## generate a PDF/HTML version of the OCI image specification
 
 ifeq "$(strip $(PANDOC))" ''
 $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES) $(FIGURE_FILES)
@@ -80,25 +71,29 @@ endif
 header.html: .tool/genheader.go specs-go/version.go
 	go run .tool/genheader.go > $@
 
-validate-examples: schema/schema.go
+.PHONY: validate-examples
+validate-examples: schema/schema.go ## validate examples in the specification markdown files
 	go test -run TestValidate ./schema
 
-check-license:
+.PHONY: check-license
+check-license: ## check license headers in source files
 	@echo "checking license headers"
 	@./.tool/check-license
 
-lint: .install.lint
+.PHONY: lint
+lint: .install.lint ## lint check of Go files using golangci-lint
 	@echo "checking lint"
 	@GO111MODULE=on $(GOPATH)/bin/golangci-lint run
 
-test: schema/fs.go
+.PHONY: test
+test: ## run the unit tests
 	go test -race -cover $(shell go list ./... | grep -v /vendor/)
 
-img/%.png: img/%.dot
+img/%.png: img/%.dot ## generate PNG from dot file
 	dot -Tpng $^ > $@
 
-
 # When this is running in GitHub, it will only check the commit range
+.PHONY: .gitvalidation
 .gitvalidation:
 	@which git-validation > /dev/null 2>/dev/null || (echo "ERROR: git-validation not found. Consider 'make install.tools' target" && false)
 ifdef GITHUB_SHA
@@ -107,29 +102,24 @@ else
 	$(GOPATH)/bin/git-validation -v -run DCO,short-subject,dangling-whitespace -range $(EPOCH_TEST_COMMIT)..HEAD
 endif
 
+.PHONY: .install.tools
 install.tools: $(TOOLS:%=.install.%)
 
+.PHONY: .install.lint
 .install.lint:
 	case "$$(go env GOVERSION)" in \
 	go1.18.*)	go install github.com/golangci/golangci-lint/cmd/[email protected];; \
 	*) go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest;; \
 	esac
 
+.PHONY: .install.gitvalidation
 .install.gitvalidation:
 	go install github.com/vbatts/git-validation@latest
 
-clean:
+.PHONY: clean
+clean: ## clean all generated and compiled artifacts
 	rm -rf *~ $(OUTPUT_DIRNAME) header.html
 
-.PHONY: \
-	$(TOOLS:%=.install.%) \
-	validate-examples \
-	check-license \
-	clean \
-	lint \
-	install.tools \
-	docs \
-	test \
-	.gitvalidation \
-	schema/fs.go \
-	schema-fs
+.PHONY: help
+help: # Display help
+	@awk -F ':|##' '/^[^\t].+?:.*?##/ { printf "\033[36m%-30s\033[0m %s\n", $$1, $$NF }' $(MAKEFILE_LIST)