jq files more commented

fadado · Apr 26, 2017 · 93583c8 · 93583c8
1 parent 439419d
commit 93583c8
Show file tree

Hide file tree

Showing 8 changed files with 76 additions and 52 deletions.
diff --git a/docs/config.yaml b/docs/config.yaml
@@ -50,11 +50,8 @@ defaults:
       title-prefix: jqt
       author: *author
       lang: *lang
-
 #     data:
 #       - snippets
-
-# TODO: explore flags here!
 #     flags:
 #       - -msnippets:$(Metadata)/snippets.json
 

diff --git a/docs/make.d/config.make b/docs/make.d/config.make
@@ -57,10 +57,10 @@ endif
 #
 # Create `$(Metadata)/site.json` from `$(Metadata)/config.json`.
 #
-$(Metadata)/site.json: $(Metadata)/config.json make.d/config.make make.d/phase0.jq
+$(Metadata)/site.json: $(Metadata)/config.json make.d/config.make make.d/site.jq
 	$(info ==> $@)
 	@jq --sort-keys				\
-	    --from-file make.d/phase0.jq	\
+	    --from-file make.d/site.jq		\
 	    --arg Version $(Version)		\
 	    --arg Metadata $(Metadata)		\
 	    < $< > $@

diff --git a/docs/make.d/data.make b/docs/make.d/data.make
@@ -66,7 +66,7 @@ define BUILD_JSON
      --arg Target $@				\
      --arg Metadata $(Metadata)			\
      --slurpfile config $(Metadata)/config.json	\
-     --from-file make.d/phase21.jq
+     --from-file make.d/page.jq
 endef
 
 ########################################################################

diff --git a/docs/make.d/phase21.jq → docs/make.d/page.jq b/docs/make.d/phase21.jq → docs/make.d/page.jq
@@ -1,16 +1,22 @@
-# FRONT-MATTER | phase21.jq 
-#   --arg Source s
-#   --arg Target s
-#   --arg Metadata s
-#   --slurpfile config s
+# Called for each source document, from macro BUILD_JSON in created
+# phase2.make, to build the JSON file for each page.
+#
+# input is page front-matter converted to JSON |
+# page.jq 
+#   --arg Source $(Content)/.../PAGE.md
+#   --arg Target $(Metadata)/pages/.../PAGE.json
+#   --arg Metadata $(Metadata)
+#   --slurpfile config $(Metadata)/config.json
 #   > $(Metadata)/pages/PAGE.json
 
 def basename:
     sub("\\.[^/]+$"; "")
 ;
 
 def dir:
-    if test("/") then sub("/[^/]+$"; "/") else "" end
+    if test("/")
+    then sub("/[^/]+$"; "/")
+    else "" end
 ;
 
 def notdir:
@@ -19,44 +25,51 @@ def notdir:
 
 # `$(Metadata)/pages/path/to/page.json` => `path/to/page`
 def page_id:
-    $Target | basename | sub($Metadata+"/pages/"; "")
+    # . as $target
+    basename | sub($Metadata+"/pages/"; "")
 ;
 
 # `$(Metadata)/pages/path/to/page.json` => `(../)+`
 def page_base:
-    ("../" * ((($Target / "/") | length) - 3)) // ""
+    # . as $target
+    ("../" * (((. / "/") | length) - 3)) // ""
 ;
 
 # `$(Metadata)/pages/path/to/page.json` => `page`
 def page_name:
-    $Target | notdir | basename
+    # . as $target
+    notdir | basename
 ;
 
 # `$(Metadata)/pages/path/to/page.json` => `path/to/`
 def page_path:
-    $Target | page_id | dir
+    # . as $obj
+    .id | dir
 ;
 
 # `$(Metadata)/pages/path/to/page.json` => `path/to`
 def page_section:
-    $Target
-    | if test("(?<!/pages)/index.json$") # index but not home page
-      then null
-      else page_path[:-1] end
+    #. as $obj
+    if $Target | test("(?<!/pages)/index.json$") # index but not home page
+    then null
+    else .path[:-1] end
 ;
 
 # derived
 def page_slug:
+    # . as $obj
     .filename + ".html"
 ;
 
 def page_date:
+    # . as $obj
     .filename |
     (capture("^(?<YMD>\\d{4}-\\d{2}-\\d{2})-") | .YMD)
         // ""
 ;
 
 def page_url:
+    # . as $obj
     .path + .slug
 ;
 
@@ -65,30 +78,31 @@ def page_url:
 ########################################################################
 
 def defaults:
-    reduce $config[0].defaults[] as $d
-        ({}; if page_id | test("^"+$d.idprefix)
+    # . as $target
+    page_id as $id
+    | reduce $config[0].defaults[] as $d
+        ({}; if $id | test("^" + $d.idprefix)
              then . + $d.properties
              else . end)
 ;
 
 def properties:
-    {
-        id:       page_id,
+    # . as $target
+    {   id:       page_id,
         base:     page_base,
         filename: page_name,
-        section:  page_section,
-        path:     page_path,
         source:   $Source
     }
-    | .date = page_date # in this order!
-    | .slug = page_slug
-    | .url  = page_url
+    # in the following order!
+    | .path     = page_path
+    | .section  = page_section
+    | .date     = page_date
+    | .slug     = page_slug
+    | .url      = page_url
 ;
 
 . as $front_matter |
-
-# final object 
-defaults + properties + $front_matter 
+$Target | defaults + properties + $front_matter 
 
 #        section  slug
 #        ⊢--^-⊣ ⊢--^----⊣

diff --git a/docs/make.d/phase1.jq b/docs/make.d/phase1.jq
@@ -1,5 +1,8 @@
-# phase1.jq < $(Metadata)/site.json > $(Metadata)/phase1.make
-# 
+# Called from config.make to create auxiliar makefile.
+#
+# phase1.jq
+#   < $(Metadata)/site.json
+#   > $(Metadata)/phase1.make
 
 # Function to cheat vim
 def comment: "# vim:syntax=make";

diff --git a/docs/make.d/phase2.jq b/docs/make.d/phase2.jq
@@ -1,4 +1,6 @@
-# find $(Content) MARKDOWN FILES |
+# Called from data.make to create auxiliar makefile.
+#
+# find $(Content) all MarkDown files |
 # phase2.jq
 #   --arg DF "$$(find $(Data) -name '*.*')"
 #   --arg Content $(Content)
@@ -7,6 +9,7 @@
 #   --arg Metadata $(Metadata)
 #   > $(Metadata)/phase1.make
 
+# Function to cheat vim
 def comment: "# vim:syntax=make";
 
 def dir:
@@ -53,7 +56,6 @@ def mpages($documents):
     | "MetadataPages := " + ($json | join(" ")) + "\n" + mrule
 ;
 
-
 def data($files):
     def d2m($x):
         sub("\\."+$x+"$"; ".json")
@@ -86,6 +88,7 @@ def data($files):
 | mpages($documents) as $MetadataPages
 | data($DF) as $DataFiles
 |
+# print now
 "__phase_2 := 1",
 $DestinationPaths,
 $MetadataPaths,

diff --git a/docs/make.d/phase3.jq b/docs/make.d/phase3.jq
@@ -1,9 +1,13 @@
+# Called from page.make to create auxiliar makefile.
+#
 # phase3.jq
 #   --arg Metadata $(Metadata)
 #   --arg Layouts $(Layouts)
 #   --arg Destination $(Destination)
-#  < $(Metadata)/pages-by-id.json > $(Metadata)/phase3.make
+#   < $(Metadata)/pages-by-id.json
+#   > $(Metadata)/phase3.make
 
+# Function to cheat vim
 def comment: "# vim:syntax=make";
 
 def use:
@@ -12,32 +16,31 @@ def use:
     else "" end
 ;
 
-def flags:
-    if .flags
-    then " " + (.flags | join(" "))
-    else "" end
-;
-
-def layout:
-    " " + $Layouts + "/" + .layout + ".html"
-;
-
 def data:
     if .data
     then " " + (.data | map("-m\(.):$(Metadata)/snippets.json") | join(" "))
     else "" end
 ;
 
+def flags:
+    if .flags
+    then " " + (.flags | join(" "))
+    else "" end
+;
 
 def page:
     " -mpage:" + $Metadata + "/pages/" + .id + ".json"
 ;
 
+def layout:
+    " " + $Layouts + "/" + .layout + ".html"
+;
+
 # makefile rule for HTML page
 def page_rule:
-    $Destination+"/"+.url+": " + .source + " " + layout + use,
+    $Destination+"/"+.url+": " + .source + layout + use,
     "\t$(info ==> $@)",
-    "\t@$(JQT)  -d $< " + data + flags + page + layout + " | $(DETAILS) > $@"
+    "\t@$(JQT)  -d $<" + data + flags + page + layout + " | $(DETAILS) > $@"
 ;
 
 #

diff --git a/docs/make.d/phase0.jq → docs/make.d/site.jq b/docs/make.d/phase0.jq → docs/make.d/site.jq
@@ -1,10 +1,14 @@
-# phase0.jq
+# Called from config.make to adapt user defined configuration.
+#
+# site.jq
 #   --arg Version $(Version)
 #   --arg Metadata $(Metadata)
-#   < $(Metadata)/config.json > $(Metadata)/site.json
+#   < $(Metadata)/config.json
+#   > $(Metadata)/site.json
 
 #
-# Delete `.defaults` and add some new members if not defined
+# Delete `.defaults` and add some new members with default value if not defined
+# in the configuration file.
 #
 del(.defaults)
 + {