[CSS] Rake: Hack CSS Paths

Add to `Rakefile` new `HackCssPath()` function to strip
the `css/` prefix from CSS file paths within PMLC generated
HTML files, in order to force stylesheets test docs of the
`:css` task to use the CSS files created by Sass, instead of
their copies created by PMLC within the `css/` subfolder.

This hack allows us to benefit from full CSS-to-Sass debugging
when inspecting the test documents in Chrome browser via the
Dev Tools.

For more info on this fix, see: pml-lang/pml-companion#93

Rakefile

@@ -1,4 +1,4 @@
-=begin "Rakefile" v0.2.2 | 2022/11/14 | by Tristano Ajmone
+=begin "Rakefile" v0.2.3 | 2022/11/15 | by Tristano Ajmone
 ================================================================================
 * * *  W A R N I N G  * * *  Due to breaking changes in PMLC 3.0.0 CLI options,
 the following tasks no longer work and were temporarily removed from the default
@@ -93,6 +93,69 @@ def pandoc2json(source_file)
   end
 end
 
+def HackCssPath(html_file)
+  # ----------------------------------------------------------------------------
+  # Tweak the CSS file paths in the target 'html_file' document to enforce the
+  # actual CSS files generated by Sass instead of their copies in the 'css/'
+  # subfolder created by PMLC.
+  #
+  # The hack allows users to debug stylesheets via the browser Dev Tools, thanks
+  # to the '.css.map' generated by Sass, which browsers like Chrome can use to
+  # trace each style back to its '.scss' source.
+  #
+  # As of PMLC 3.1.0 this is the only workaround, since the new '--CSS_files'
+  # option will always copy the target stylesheets into a 'css/' subfolder:
+  #
+  #   https://github.com/pml-lang/pml-companion/issues/94
+  # ----------------------------------------------------------------------------
+  TaskHeader("Hack CSS Path: #{html_file}")
+  src_dir = html_file.pathmap("%d")
+  src_fname = html_file.pathmap("%f")
+  cd "#{$repo_root}/#{src_dir}"
+  tmp_fname = src_fname.ext('tmp')
+  tmp_file = File.open(tmp_fname, mode: "w")
+  begin
+    fixing_completed = false
+    fixes_cnt = 0
+    line_cnt = 1
+    File.readlines(src_fname).each do |line|
+      unless fixing_completed
+        if line.match(/^\s*<link rel="stylesheet" href="css\//)
+          line = line.gsub('href="css/', 'href="')
+          puts "  L.#{line_cnt}: #{line}"
+          fixes_cnt += 1
+        elsif fixes_cnt > 0
+          # Since CSS links by PMLC are grouped together we stop looking for
+          # further substitutions when no more consecutive matches are found.
+          fixing_completed = true
+          puts "Total CSS paths fixed: #{fixes_cnt}"
+        end
+      end
+      line_cnt += 1
+      tmp_file.puts line
+    end
+    tmp_file.close
+    if fixes_cnt > 0 # Replace original file with new one
+      begin
+        File.rename(tmp_fname, src_fname)
+      rescue Exception => e
+        rake_msg = "Renaming New HTML doc with Hacked CSS Path failed:\n#{html_file}"
+        PrintTaskFailureMessage(rake_msg, e.message)
+      end
+    else # Just Delete temp file!
+      puts "No CSS paths had to be fixed in this file."
+      File.delete(tmp_fname)
+    end
+  rescue Exception => e
+    rake_msg = "Deleting temporary CSS Path hacking file failed:\n#{html_file}"
+    PrintTaskFailureMessage(rake_msg, e.message)
+    # Abort Rake execution with error description:
+    raise rake_msg
+  ensure
+    cd $repo_root, verbose: false
+  end
+end
+
 # ==============================================================================
 # -------------------------------{  T A S K S  }--------------------------------
 # ==============================================================================
@@ -320,6 +383,10 @@ CSS_FOLDERS.each do |dir|
         css_list += f.pathmap("%f") + ','
       end
       sh "pmlc p2h -o #{t.name.pathmap("%f")} -css #{css_list} ../../#{t.source}"
+      # Remove the 'css/' prefix from CSS paths in generated HTML doc so we can
+      # use the original CSS files generated by Sass instead of their copies
+      # created by PMLC (see HackCssPath() comments for more info):
+      HackCssPath(t.name)
       cd $repo_root, verbose: false
     end
   end
@@ -330,8 +397,7 @@ end
 file 'stylesheets/css__default/pml-default.css' => 'stylesheets/pml-default.css'
 file 'stylesheets/css__default/pml-print-default.css' => 'stylesheets/pml-print-default.css'
 
-
-# Build Test Docs within their source folder
+# Build Test Docs within their source folder:
 
 CSS_DOCS_PML.each do |pml_doc|
   html_doc = pml_doc.ext('.html')

stylesheets/README.md

@@ -83,10 +83,9 @@ Currently, it's just intended for study and comparison with other custom CSS fil
 
 Any `*.pml` document inside the [`/src-docs/`][src-docs/] folder will be converted to HTML into each and every `css__*/` stylesheet folder using the CSS files found within the latter, so that each stylesheet can be tested using the same documents.
 
-> **NOTE** — The generated HTML documents won't use the CSS files generated from Sass directly, but instead link to a copy which PMLC creates within the `css/` subfolder (See [Issue #93]).
-> For this reason, whenever the Sass sources are modified, all the HTML sample documents need to be rebuild too.
-> Rake automatically takes care of all this, so this note is just a warning in case you're planning to manually build the stylesheets via Sass.
-
+> **NOTE** — The PMLC output HTML documents are post-processed by our `Rakefile` to eliminate the `css/` prefix in CSS paths in order to use the original CSS files generated by Sass, instead of their copies which PMLC creates within the `css/` subfolder (see [Issue #93]).
+>
+> This hackish workaround allows us to keep to CSS stylesheets together with the Sass-generated `.css.map` files and benefit from full CSS-to-Sass debugging when inspecting the test documents in the browser Dev Tools (tested with Chrome browser) — a feature which we definitely _can't_ do without in this type of project.
 
 Rake will track any changes to the test documents sources, along with their assets (in [`/_shared/`][_shared/]) and update any file tasks as required.