Polish docs

Author: drdv

Makefile

@@ -48,8 +48,8 @@ help: VFLAGS := \
 help: $(AWK_BIN)/$(AWK)
 	@$< $(VFLAGS) $(AWK_FLAGS) -f $(MAKEFILE_DOC) $(MAKEFILE_LIST)
 
-.PHONY: test
 ## Run integration tests
+.PHONY: test
 test: $(INTEGRATION_TESTS)
 
 ## Run unit tests
@@ -66,13 +66,13 @@ utest: $(AWK_BIN)/$(AWK) $(MAKEFILE_DOC) $(UNIT_TESTS) $(UNIT_TEST_DIR)/unittest
 		/dev/null
 	@rm /tmp/.makefile-doc-stderr
 
-.PHONY: test-all-awk
 ## Run integration tests with all supported awk variants
+.PHONY: test-all-awk
 test-all:
 	@$(foreach X,$(SUPPORTED_AWK_VARIANTS),$(MAKE) test AWK=$(X);)
 
-.PHONY: utest-all-awk
 ## Run unit tests with all supported awk variants
+.PHONY: utest-all-awk
 utest-all:
 	@$(foreach X,$(SUPPORTED_AWK_VARIANTS),$(MAKE) utest AWK=$(X);)
 
@@ -96,6 +96,7 @@ coverage-utests.html: utest
 
 ## Lint the code using `gawk`
 # Warnings to ignore have been stripped below
+.PHONY: lint
 lint: UNINIT := (|SUB|COLOR_.*|VARS|OFFSET|PADDING|DEPRECATED|RECIPEPREFIX|AWK|\
 				|TARGETS_REGEX|VARIABLES_REGEX|OUTPUT_FORMAT|EXPORT_THEME|UNIT_TEST)
 lint: override AWK := awk
@@ -123,14 +124,13 @@ check-variables:
 clean-bin: ##! Remove all downloaded awk variants
 	@rm -rf $(AWK_BIN)
 
-## Remove coverage reports
 .PHONY: clean
-clean:
+clean: ## Remove coverage reports
 	@rm -f $(COVER_FILE).all $(COVER_FILE).integration $(COVER_FILE).unit \
 			coverage-tests.html coverage-utests.html coverage.html
 
-.PHONY: release
 ##! Create github release at latest tag
+.PHONY: release
 release: LATEST_TAG := $(shell git describe --tags)
 release: RELEASE_NOTES := release_notes.md
 release:
@@ -147,9 +147,9 @@ release:
 ## Recipes:
 ## ---------
 
-# Now we redirect to actual files because making sure that stderr and stdout
+# We redirect to actual files because making sure that stderr and stdout
 # appear in the righ order with all AWK variants (in particular goawk) and on
-# CI was problematic
+# CI was problematic otherwise
 $(INTEGRATION_TESTS): FILE_CMD = /tmp/.makefile-doc_$@_command
 $(INTEGRATION_TESTS): FILE_EXPECTED = /tmp/.makefile-doc_$@_expected
 $(INTEGRATION_TESTS): FILE_ACTUAL = /tmp/.makefile-doc_$@_actual

README.md

@@ -66,7 +66,7 @@ We refer to targets / variables as anchors (for docs/sections).
   color and allows to filter it out, see the `DEPRECATED` flag below).
 
 + Multi-line docs can be added above an anchor, inline docs are ignored when top docs
-  are present. Only the first line in a multi-line doc need to include a token with an
+  are present. Only the first line of a multi-line doc needs to include a token with an
   emphasis (i.e., `##!` or `##%`).
 
 + Sections can be defined using `##@`. All lines in a multi-line section should start
@@ -209,4 +209,5 @@ Execute `make test utest` (this uses the system's default `awk`). To test with a
 + `make test utest AWK=wak`
 + `make test utest AWK=goawk`
 
-You need a standard build environment.
+You need a standard build environment. To compile `nawk` ensure that `bison` is
+installed (`dnf install bison`). For `goawk` you need `golang` (`dnf install golang`).

makefile-doc.awk

@@ -58,8 +58,7 @@
 #   then passing -v SUB='AWK:$(SUPPORTED_AWK_VARIANTS)' would add the values of
 #   SUPPORTED_AWK_VARIANTS to the documentation of the variable AWK. This mechanism is
 #   also useful when documenting targets defined in terms of variables/expressions,
-#   which we might want to rename in addition to adding a list of expanded targets to
-#   the documentation. The format of a single substitution is
+#   which we might want to rename. The format of a single substitution is
 #   [<p1:v1,...>]NAME[:LABEL]:[VALUES]
 #   + NAME is the name of the variable/target to substitute in the documentation
 #   + LABEL is an optional label for renaming the variable/target
@@ -103,11 +102,11 @@
 #         [recipe]
 #
 #     where:
+#       variable assignment: a single variable can be assigned per rule
 #       prerequisits := normal-prerequisites | order-only-prerequisites
 #       inline recipe := [command] [; command ...]
 #       recipe := [command]
 #                 [...]
-#       variable assignment: a single variable can be assigned per rule
 #
 #     with normal-prerequisites and order-only-prerequisites being space separated lists
 #     of target names.
@@ -122,11 +121,10 @@
 #   + Target line: the top-line (the header) of a Makefile rule
 #   + Target name: a (string) label for a target
 #   + Description of a rule: comments starting with ##, ##! or ##% placed above the
-#     target line of a rule or inline. Inline descriptions cannot be placed after an
-#     inline recipe.
+#     target line of a rule or inline. Inline descriptions placed after an inline recipe
+#     are ignored.
 #   + The last rule with a description defines the description of a normal target, while
-#     every double-colon rule with a description defines a double-colon target with a
-#     new ~index.
+#     every double-colon rule with a description defines a new description.
 
 function max(x, y) {
   return (x >= y) ? x : y