Rename option COLOR_ENCODING to OUTPUT_FORMAT

Author: drdv

Makefile

@@ -4,15 +4,18 @@ TEST_RECIPES_DIR := $(TEST_DIR)/recipes
 
 TESTS := $(notdir $(wildcard $(TEST_RECIPES_DIR)/*))
 
-## if set, debug info is generated in an org file
-DEBUG :=
-
 ## Supported awk variants:
 AWK := awk
 AWK_FLAGS :=
 AWK_BIN := $(TEST_DIR)/bin
 SUPPORTED_AWK_VARIANTS := awk mawk nawk bawk wak goawk
 
+## {ansi, html}
+OUTPUT_FORMAT :=
+
+## if set, debug info is generated in an org file
+DEBUG :=
+
 ## if set, the expected value of a test recipe is updated
 ## e.g., `make test-default UPDATE_RECIPE=1`
 UPDATE_RECIPE :=
@@ -33,7 +36,7 @@ help: TESTS_SUB := <L:1,M:1>$$(TESTS):test-:$(wordlist 1,5,$(subst test-,,$(TEST
 help: VFLAGS := -v SUB='$(TESTS_SUB);$(AWK_SUB)' \
 	-v DEBUG=$(DEBUG) \
 	-v COLOR_BACKTICKS=33 \
-	-v COLOR_ENCODING=$(COLOR_ENCODING)
+	-v OUTPUT_FORMAT=$(OUTPUT_FORMAT)
 help: $(AWK_BIN)/$(AWK)
 	@$< $(VFLAGS) $(AWK_FLAGS) -f makefile-doc.awk $(MAKEFILE_LIST)
 

README.md

@@ -95,6 +95,7 @@ value"](https://www.gnu.org/software/make/manual/html_node/Simple-Assignment.htm
 The following options can be passed to `awk` using `-v option=value` (possible values
 are given in `{...}`, `(.)` shows the default)
 
++ `OUTPUT_FORMAT`: `{(ANSI), HTML}`
 + `DEBUG`: `{(0), 1}` output debug info (in an org-mode format)
 + `DEBUG_FILE`: debug info file
 + `SUB`: see [Substitutions](#substitutions)
@@ -106,7 +107,6 @@ are given in `{...}`, `(.)` shows the default)
 * `OFFSET`: `{0, 1, (2), ...}` number of spaces to offset docs from anchors
 * `CONNECTED`: `{0, (1)}` ignore docs followed by an empty line
 + Colors:
-  + `COLOR_ENCODING`: `{(ANSI), HTML}`
   + `COLOR_DEFAULT`: (`34`: blue) for anchors whose docs start with `##`
   + `COLOR_ATTENTION`: (`31`: red) for anchors whose docs start with `##!`
   + `COLOR_DEPRECATED`: (`33`: yellow) for anchors whose docs start with `##%`

makefile-doc.awk

@@ -10,6 +10,7 @@
 #   awk [-v option=value] -f makefile-doc.awk [Makefile ...]
 #
 # Options (possible values are given in {...}, (.) is the default):
+#   + OUTPUT_FORMAT: {(ANSI), HTML}
 #   + DEBUG: {(0), 1} output debug info (in an org-mode format)
 #   + DEBUG_FILE: debug info file
 #   + SUB: see below
@@ -33,7 +34,6 @@
 #      * ##@ section (displayed in COLOR_SECTION)
 #
 # Color codes (https://en.wikipedia.org/wiki/ANSI_escape_code):
-#   + COLOR_ENCODING: {(ANSI), HTML}
 #   * COLOR_DEFAULT: (34) blue
 #   * COLOR_ATTENTION: (31) red
 #   * COLOR_DEPRECATED: (33) yellow
@@ -42,7 +42,7 @@
 #   * COLOR_BACKTICKS: (0) disabled -- used for text in backticks in docs
 #
 #   Colors are specified using the parameter in ANSI escape codes, e.g., the parameter
-#   for blue is the 34 in `\033[34m`. When the COLOR_ENCODING is HTML, colors are
+#   for blue is the 34 in `\033[34m`. When the OUTPUT_FORMAT is HTML, colors are
 #   controlled using the class attribute e.g., the value for blue is "ansi34" etc.
 #
 # SUB:
@@ -583,9 +583,9 @@ function strip_start_end_spaces(string) {
 }
 
 function define_color(parameter) {
-  if (COLOR_ENCODING == "ANSI") {
+  if (OUTPUT_FORMAT == "ANSI") {
     return "\033[" parameter "m"
-  } else if (COLOR_ENCODING == "HTML") {
+  } else if (OUTPUT_FORMAT == "HTML") {
     if (parameter) {
       return "<span class=\"ansi" parameter "\">"
     } else {
@@ -596,10 +596,10 @@ function define_color(parameter) {
 
 # Updates global variables: COLOR_*, HTML_*
 function initialize_colors() {
-  COLOR_ENCODING = COLOR_ENCODING == "" ? "ANSI" : toupper(COLOR_ENCODING)
-  if (COLOR_ENCODING != "ANSI" && COLOR_ENCODING != "HTML") {
-    print("Ignorring invalid COLOR_ENCODING: " COLOR_ENCODING " (using ANSI instead).")
-    COLOR_ENCODING = "ANSI"
+  OUTPUT_FORMAT = OUTPUT_FORMAT == "" ? "ANSI" : toupper(OUTPUT_FORMAT)
+  if (OUTPUT_FORMAT != "ANSI" && OUTPUT_FORMAT != "HTML") {
+    print("Ignorring invalid OUTPUT_FORMAT: " OUTPUT_FORMAT " (using ANSI instead).")
+    OUTPUT_FORMAT = "ANSI"
   }
   COLOR_DEFAULT_CODE = define_color(COLOR_DEFAULT == "" ? 34 : COLOR_DEFAULT)
   COLOR_ATTENTION_CODE = define_color(COLOR_ATTENTION == "" ? 31 : COLOR_ATTENTION)
@@ -612,7 +612,7 @@ function initialize_colors() {
 
   COLOR_RESET_CODE = define_color(0)
 
-  if (COLOR_ENCODING == "HTML") {
+  if (OUTPUT_FORMAT == "HTML") {
     HTML_CLOSE_PRE = "</pre>"
     HTML_STYLE_AND_OPEN_PRE = "<head>\n  <style type=\"text/css\">\n    .ansi31 { color: #d70000; }\n    .ansi32 { color: #5f8700; }\n    .ansi33 { color: #af8700; }\n    .ansi34 { color: #0087ff; }\n    .ansi35 { color: #af005f; }\n  </style>\n</head>\n<pre>"
   }
@@ -640,7 +640,7 @@ function print_help() {
     printf "  DEPRECATED ([bool] show deprecated anchors): %s\n", DEPRECATED
     printf "  OFFSET (offset of docs from anchors): %s\n", OFFSET
     printf "  CONNECTED (ignore docs followed by an empty line): %s\n", CONNECTED
-    printf "  COLOR_ENCODING: %s\n", COLOR_ENCODING
+    printf "  OUTPUT_FORMAT: %s\n", OUTPUT_FORMAT
     printf "  COLOR_: "
     printf "%sDEFAULT%s, ", COLOR_DEFAULT_CODE, COLOR_RESET_CODE
     printf "%sATTENTION%s, ", COLOR_ATTENTION_CODE, COLOR_RESET_CODE
@@ -1058,7 +1058,7 @@ END {
   debug(DEBUG_INDENT_STACK " extracted_sub_params")
   debug_indent_down()
 
-  if (COLOR_ENCODING == "HTML") {
+  if (OUTPUT_FORMAT == "HTML") {
     print(HTML_STYLE_AND_OPEN_PRE)
   }
 
@@ -1101,7 +1101,7 @@ END {
     }
   }
 
-  if (COLOR_ENCODING == "HTML") {
+  if (OUTPUT_FORMAT == "HTML") {
     print(HTML_CLOSE_PRE)
   }
 

test/Makefile.inc

@@ -4,7 +4,7 @@ PADDING =
 HEADER =
 DEPRECATED =
 COLOR_BACKTICKS =
-COLOR_ENCODING =
+OUTPUT_FORMAT =
 
 AWK := awk
 AWK_FLAGS :=
@@ -20,7 +20,7 @@ help:
 		-v CONNECTED=$(CONNECTED) \
 		-v DEPRECATED=$(DEPRECATED) \
 		-v COLOR_BACKTICKS=$(COLOR_BACKTICKS) \
-		-v COLOR_ENCODING=$(COLOR_ENCODING) \
+		-v OUTPUT_FORMAT=$(OUTPUT_FORMAT) \
 		-f ../makefile-doc.awk $(MAKEFILE_LIST)
 
 test-10: ##% some target

test/recipes/test-html

@@ -1,4 +1,4 @@
--v COLOR_ENCODING=html test/Makefile
+-v OUTPUT_FORMAT=html test/Makefile
 <span class="ansi35">[test/Makefile] redefined docs of target: test-3</span>
 <span class="ansi35">[test/Makefile] redefined docs of target: test-14</span>
 <head>