cyberweb 0.4.174 → 0.5.225

data/lib/cyberweb/utility_scripts/images_to_html/images_to_html.rb

@@ -0,0 +1,878 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Cyberweb::ImagesToHtml
+#
+# This class can be used to generate a .html file containing all images
+# of a given directory. In order for this to work you have to provide the
+# directory that is to be scanned; if not provided then the current
+# working directory is used. It allows us to quickly display an arbitrary
+# collection of images.
+#
+# The overall design of this class has to remain quite flexible, as
+# quite a few different classes make use of this class here with
+# their own different use cases.
+#
+# The class must be able to:
+#
+#   (1) allow the user to save into a file of his/her choosing
+#   (2) allow the user to designate a specific directory containing
+#       all the images
+#
+# Furthermore, since as of March 2022, the class can also gather
+# video files and then generate a .html file based on this.
+# =========================================================================== #
+# === Cyberweb::ImagesToHtml
+#
+# Specific usage example for this class:
+#
+#   webpage = Cyberweb::ImagesToHtml.new
+#   webpage.set_images(:return_pwd)
+#   webpage.run
+#
+# =========================================================================== #
+# require 'cyberweb/utility_scripts/images_to_html/images_to_html.rb'
+# webpage = Cyberweb::ImagesToHtml.new(ARGV)
+# ============================================================================ #
+require 'cyberweb/base/base.rb'
+
+module Cyberweb
+
+class ImagesToHtml < ::Cyberweb::Base # === Cyberweb::ImagesToHtml
+
+  alias e puts
+
+  require 'html_tags/requires/require_the_html_tags_project.rb'
+  include HtmlTags
+
+  require 'cyberweb/toplevel_methods/misc.rb'
+  require 'cyberweb/toplevel_methods/jquery.rb'
+  require 'cyberweb/html_template/html_template.rb'
+  require 'cyberweb/utility_scripts/images_to_html/misc.rb'
+
+  # ========================================================================= #
+  # === NAMESPACE
+  # ========================================================================= #
+  NAMESPACE = inspect
+
+  # ========================================================================= #
+  # === DEBUG
+  #
+  # Whether we debug this class or not.
+  # ========================================================================= #
+  DEBUG = false
+
+  # ========================================================================= #
+  # === ARRAY_IMAGES
+  # ========================================================================= #
+  ARRAY_IMAGES = %w( jpg png gif ) # All valid image-formats.
+
+  # ========================================================================= #
+  # === INFO_DIRECTORY
+  #
+  # This is the base directory where to store, unless we use Dir.pwd.
+  # ========================================================================= #
+  INFO_DIRECTORY = '/Depot/Information/'
+
+  # ========================================================================= #
+  # === BE_VERBOSE
+  # ========================================================================= #
+  BE_VERBOSE = true
+
+  # ========================================================================= #
+  # === HTML
+  # ========================================================================= #
+  HTML = '.html' # HTML File suffice comes here.
+
+  # ========================================================================= #
+  # === IMG_CSS_STYLE
+  #
+  # Determine the default css-rules for each <img> tag to be used.
+  # ========================================================================= #
+  IMG_CSS_STYLE =
+    'border:1px solid black;
+     margin-left: 4.5em;
+     padding-left: 5px;'.
+     delete("\n").squeeze(' ')
+
+  # ========================================================================= #
+  # === initialize
+  #  
+  # The first argument to this method should contain the commandline
+  # arguments, which is usually ARGV.
+  # ========================================================================= #
+  def initialize(
+      commandline_arguments = ARGV,
+      run_already           = true
+    )
+    reset
+    # ======================================================================= #
+    # The next clause must come before set_commandline_arguments().
+    # ======================================================================= #
+    case commandline_arguments
+    # ======================================================================= #
+    # === :do_not_run_yet
+    # ======================================================================= #
+    when :do_not_run_yet
+      commandline_arguments = []
+      run_already = false
+    end
+    set_commandline_arguments(
+      commandline_arguments
+    )
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      case yield
+      # ===================================================================== #
+      # === :use_jquery
+      # ===================================================================== #
+      when :use_jquery,
+           :jquery
+        @internal_hash[:use_jquery] = true
+      # ===================================================================== #
+      # === :do_not_run_yet
+      # ===================================================================== #
+      when :do_not_run_yet
+        run_already = false
+      end
+    end
+    case run_already
+    # ======================================================================= #
+    # === :do_not_run_yet
+    # ======================================================================= #
+    when :do_not_run_yet,
+         :dont_run_yet
+      run_already = false
+    end
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    # ======================================================================= #
+    # Set up sane defaults first.
+    # ======================================================================= #
+    super()
+    be_verbose
+    # ======================================================================= #
+    # === @namespace
+    # ======================================================================= #
+    @namespace = NAMESPACE
+    # ======================================================================= #
+    # === @this_directory_contains_all_images
+    # ======================================================================= #
+    @this_directory_contains_all_images = return_pwd
+    # ======================================================================= #
+    # === @save_into_this_local_file
+    # ======================================================================= #
+    set_save_into_this_local_file(
+      :infer_the_name_from_the_directory_containing_all_images
+    )
+    # ======================================================================= #
+    # === @content_of_the_html_page
+    # ======================================================================= #
+    @content_of_the_html_page = ''.dup
+    # ======================================================================= #
+    # === @show_the_name_of_the_image_file
+    # ======================================================================= #
+    @show_the_name_of_the_image_file = false
+    # ======================================================================= #
+    # === @body_css_style
+    # ======================================================================= #
+    @body_css_style = '
+      background-color: black; color: white; font-size: 1.2em;'
+    # ======================================================================= #
+    # === @debug
+    # ======================================================================= #
+    @debug = DEBUG
+    # ======================================================================= #
+    # === @array_work_on_these_files
+    #
+    # This Array will contain all the different images (or videos) that
+    # were found in the given directory at hand.
+    # ======================================================================= #
+    @array_work_on_these_files = []
+    # ======================================================================= #
+    # === @work_on_video_files_only
+    # ======================================================================= #
+    @work_on_video_files_only = false
+    # ======================================================================= #
+    # === @do_traverse_into_subdirectories
+    # ======================================================================= #
+    @do_traverse_into_subdirectories = true
+    # ======================================================================= #
+    # === @internal_hash
+    # ======================================================================= #
+    @internal_hash = {}
+    # ======================================================================= #
+    # === :use_HTML_table_layout
+    # ======================================================================= #
+    @internal_hash[:use_HTML_table_layout] = false
+    # ======================================================================= #
+    # === :use_n_rows_for_the_html_table
+    # ======================================================================= # 
+    @internal_hash[:use_n_rows_for_the_html_table] = 3
+    # ======================================================================= #
+    # === :use_jquery
+    #
+    # Whether we will use jquery by default or whether we will not.
+    #
+    # I decided to set this to true during June 2021. While it creates
+    # an overhead and an increase in file size, I think jquery is
+    # very convenient. This may, however had, be subject to change in
+    # the future, hence why this comment has been added.
+    # ======================================================================= #
+    @internal_hash[:use_jquery] = true
+    # ======================================================================= #
+    # === :sort_how
+    #
+    # The next variable determines if, and how, we should sort on the
+    # Dir[] result. To disable sorting set this to nil or to
+    # :do_not_sort_at_all. The value :sort_by_date will sort by date,
+    # meaning older images are sorted before other images. This will be
+    # based on the filename, so if the filename includes "1982" then
+    # this means that it is the date 1982.
+    # ======================================================================= # 
+    @internal_hash[:sort_how] = :sort_by_date # :do_not_sort_at_all
+    # ======================================================================= #
+    # === :registered_ids
+    #
+    # This array will keep track of each id assigned to the <img> tag.
+    # This is necessary for the jquery-drag operation.
+    # ======================================================================= #
+    @internal_hash[:registered_ids] = []
+  end
+
+  # ========================================================================= #
+  # === show_the_name_of_the_image_file?
+  # ========================================================================= #
+  def show_the_name_of_the_image_file?
+    @show_the_name_of_the_image_file
+  end
+
+  # ========================================================================= #
+  # === return_image
+  #
+  # Use this when you wish to append an image.
+  # ========================================================================= #
+  def return_image(i)
+    result = ''.dup
+    i = rds(i)
+    if show_the_name_of_the_image_file? and !use_html_table?
+      result <<
+        '<h2 style="color:orange; font-style: italic; padding: 5px">'+i+'</h2>'+NBR
+    end
+    new_filename = File.basename(i).gsub(/#{File.extname(i)}/, '')
+    id = 'drag_'+new_filename.downcase.tr(' ','').tr('.','_')
+    # ======================================================================= #
+    # Store these IDs in the global Array as well:
+    # ======================================================================= #
+    @internal_hash[:registered_ids] << id
+    result << '<img id="'+id+'" style="'+IMG_CSS_STYLE+'" src="'+i+'"'.dup
+    if use_HTML_table?
+      result << ' width="440"'
+    end
+    result << '>'+NBR
+    if use_jquery?
+      result << '<script>
+      $(function() {
+    $( "#'+id+'" ).draggable();
+  });
+  </script>'
+    end
+    return result
+  end
+
+  # ========================================================================= #
+  # === clear_images
+  # ========================================================================= #
+  def clear_images
+    @array_work_on_these_files.clear # Should always be an Array.
+  end; alias clear_array clear_images # === clear_array
+
+  # ========================================================================= #
+  # === apply_filter
+  #
+  # This method can be used to, for instance, selectively ignore .gif
+  # files.
+  # ========================================================================= #
+  def apply_filter(i) # Apply a filter here.
+    case i
+    # ======================================================================= #
+    # === only gif
+    # ======================================================================= #
+    when /^only gif/
+      @array_work_on_these_files.reject! {|img| !img.include? '.gif' }
+    end
+  end
+
+  # ========================================================================= #
+  # === scan_for_images_in_this_directory
+  # ========================================================================= #
+  def scan_for_images_in_this_directory(
+      i                      = return_pwd,
+      include_subdirectories = true
+    )
+    if i.is_a? Array
+      i = i.first # We only use the first argument of Arrays passed for now.
+    end
+    case i
+    # ======================================================================= #
+    # === :return_pwd
+    # ======================================================================= #
+    when :return_pwd
+      i = return_pwd
+    end
+    case i.to_s.downcase
+    # ======================================================================= #
+    # === njoy
+    # ======================================================================= #
+    when 'njoy'
+      i = ENV['MY_DATA'].to_s.dup+'/images/NJOY/'
+    end
+    i = ConvertGlobalEnv.convert(i) if i.include? '$'
+    set_work_on_this_directory(i)
+    look_for_the_images_here(i, :include_the_subdirectories_as_well) # This is ok because set_images will check on its own.
+  end; alias scan_here     scan_for_images_in_this_directory # === scan_here
+       alias scan_there    scan_for_images_in_this_directory # === scan_there
+       alias scan_from     scan_for_images_in_this_directory # === scan_from
+       alias use_this_dir= scan_for_images_in_this_directory # === use_this_dir=
+
+  # ========================================================================= #
+  # === the_three_main_actions
+  # ========================================================================= #
+  def the_three_main_actions
+    look_for_the_images
+    build_up_the_HTML_string
+    do_create_the_html_page
+  end
+
+  # ========================================================================= #
+  # === use_HTML_table_layout?
+  # ========================================================================= #
+  def use_HTML_table_layout?
+    @internal_hash[:use_HTML_table_layout]
+  end; alias use_html_table_layout? use_HTML_table_layout? # === use_html_table_layout?
+       alias use_html_table?        use_HTML_table_layout? # === use_html_table?
+       alias use_HTML_table?        use_HTML_table_layout? # === use_HTML_table?
+
+  # ========================================================================= #
+  # === return_infer_the_name_from_the_directory_containing_all_images
+  # ========================================================================= #
+  def return_infer_the_name_from_the_directory_containing_all_images(i)
+    basename = File.basename(i.to_s)
+    basename.downcase!
+    basename << '.html' unless basename.end_with? '.html'
+    basename = File.absolute_path(basename)
+    return basename
+  end
+
+  # ========================================================================= #
+  # === add                                                         (add tag)
+  #
+  # This method can be used to add (append) onto the main String that stores
+  # the content of the webpage as such.
+  #
+  # Using the alias _ is also permissive, but I recommend using only
+  # add() - it makes the code more explicit without it becoming too long,
+  # in my opinion.
+  # ========================================================================= #
+  def add(i) # Use this (and only this) method to append onto the main string.
+    @content_of_the_html_page << i
+  end; alias _ add # === _
+
+  # ========================================================================= #
+  # === look_for_the_images
+  #
+  # Use this method to set the list of images. It will obtain all images
+  # from the given subdirectory.
+  #
+  # In order for this to work correctly the variable that keeps track of
+  # the main directory at hand has to be set.
+  # ========================================================================= #
+  def look_for_the_images(
+      i                      = work_on_which_directory?,
+      include_subdirectories = @do_traverse_into_subdirectories
+    )
+    case i
+    # ======================================================================= #
+    # === :return_pwd
+    # ======================================================================= #
+    when :return_pwd
+      i = return_pwd
+    end
+    case include_subdirectories
+    when true,
+         :include_the_subdirectories_as_well
+      i = "#{i}/**/**"
+    else
+      i = "#{i}/*"
+    end
+    _ = Dir[i.squeeze('/')]
+    if sort_how?
+      case sort_how?
+      # ===================================================================== #
+      # === :sort_by_date
+      # ===================================================================== #
+      when :sort_by_date,
+           :sort_by_time
+        require 'time'
+        _ = ::Cyberweb.sort_this_array_by_time(_)
+      end
+    end
+    if work_on_video_files_only?
+      @array_work_on_these_files = _.select {|entry|
+        is_a_video_file?(entry)
+      }
+    else
+      @array_work_on_these_files = _.select {|entry|
+        is_an_image?(entry)
+      }
+    end
+  end; alias store_images                                    look_for_the_images # === store_images
+       alias append_images                                   look_for_the_images # === append_images
+       alias set_images                                      look_for_the_images # === set_images
+       alias obtain_all_images_from_the_designated_directory look_for_the_images # === obtain_all_images_from_the_designated_directory
+       alias look_for_the_images_here                        look_for_the_images # === look_for_the_images_here
+
+  # ========================================================================= #
+  # === work_on_video_files_only?
+  # ========================================================================= #
+  def work_on_video_files_only?
+    @work_on_video_files_only
+  end
+
+  # ========================================================================= #
+  # === report_scanning_directory
+  # ========================================================================= #
+  def report_scanning_directory
+    opnn; e "Scanning from the directory "\
+            "`#{sdir(work_on_which_directory?)}`."
+  end
+
+  # ========================================================================= #
+  # === n_rows?
+  # ========================================================================= #
+  def n_rows?
+    @internal_hash[:use_n_rows_for_the_html_table]
+  end
+
+  # ========================================================================= #
+  # === save_into_this_local_file?
+  # ========================================================================= #
+  def save_into_this_local_file?
+    @save_into_this_local_file
+  end; alias title?                save_into_this_local_file? # === title?
+       alias store_where?          save_into_this_local_file? # === store_where?
+       alias stored_where?         save_into_this_local_file? # === stored_where?
+       alias output_file?          save_into_this_local_file? # === output_file?
+       alias store_into?           save_into_this_local_file? # === store_into?
+       alias save_into_which_file? save_into_this_local_file? # === save_into_which_file?
+       alias save?                 save_into_this_local_file? # === save?
+
+  # ========================================================================= #
+  # === do_create_the_html_page
+  # ========================================================================= #
+  def do_create_the_html_page(
+      into = save_into_which_file?
+    )
+    # ======================================================================= #
+    # Make the title a bit cleaner next:
+    # ======================================================================= #
+    use_this_title = File.basename(title?).delete_suffix('.html')
+    # ======================================================================= #
+    # Build the .html file via the HtmlTemplate class next:
+    # ======================================================================= #
+    what = Cyberweb::HtmlTemplate.new {{
+      title:          use_this_title,
+      css_style:      '
+        a:link  { text-decoration: none; color: gold; }
+        a:hover { text-decoration: none; color: lightblue; }
+      ',
+      body_css_style: @body_css_style, # This will honour the CSS rules.
+      body:           html_content?
+    }}.to_s
+    save_file(what, into)
+  end; alias append_everything do_create_the_html_page # === append_everything
+
+  # ========================================================================= #
+  # === set_save_into_this_local_file
+  # ========================================================================= #
+  def set_save_into_this_local_file(
+      i = INFO_DIRECTORY+
+          '/all_files_from_'+
+          input_directory?.to_s
+    ) # contains the full path where to store things.
+    case i
+    # ======================================================================= #
+    # === :use_the_current_working_directory_base_name
+    # ======================================================================= #
+    when :use_the_current_working_directory_base_name
+      i = File.basename(return_pwd).downcase
+    # ======================================================================= #
+    # === :infer_the_name_from_the_directory_containing_all_images
+    # ======================================================================= #
+    when :infer_the_name_from_the_directory_containing_all_images,
+         :infer,
+         :use_the_directory_containing_all_images_as_base
+      _ = directory_containing_all_images?
+      i = File.basename(_).downcase
+    end
+    if i
+      i = i.dup if i.frozen?
+      # ===================================================================== #
+      # i = File.basename(i) # File.basename() is not good, it removes '/'
+      # Append '.html' string, unless it already exists there.
+      # ===================================================================== #
+      i << HTML unless i.end_with? HTML
+    end
+    i = File.absolute_path(i)
+    @save_into_this_local_file = i
+  end; alias set_store_where      set_save_into_this_local_file # === set_store_where
+       alias store_where          set_save_into_this_local_file # === store_where
+       alias set_page_name        set_save_into_this_local_file # === set_page_name
+       alias store_where=         set_save_into_this_local_file # === store_where=
+       alias set_output_page_here set_save_into_this_local_file # === set_output_page_here
+
+  # ========================================================================= #
+  # === set_content_of_the_html_page
+  # ========================================================================= #
+  def set_content_of_the_html_page(i)
+    @content_of_the_html_page = i
+  end
+
+  # ========================================================================= #
+  # === return_jquery
+  #
+  # This method will add the jquery version.
+  #
+  # In order to do this, we have to tap into the Cyberweb project.
+  # ========================================================================= #
+  def return_jquery
+    return "\n#{::Cyberweb.return_jquery_string}"
+  end
+
+  # ========================================================================= #
+  # === content_of_the_html_page?
+  # ========================================================================= #
+  def content_of_the_html_page?
+    @content_of_the_html_page
+  end; alias html_content? content_of_the_html_page? # === html_content?
+       alias html_string?  content_of_the_html_page? # === html_string?
+
+  # ========================================================================= #
+  # === show_names_of_image_files
+  # ========================================================================= #
+  def show_names_of_image_files
+    @show_the_name_of_the_image_file = true
+  end; alias show_names show_names_of_image_files # === show_names
+
+  # ========================================================================= #
+  # === set_background
+  #
+  # Pass the colour that you want to use for the background here, such
+  # as :orange or :tomato.
+  # ========================================================================= #
+  def set_background(i)
+    i = i.to_s
+    @body_css_style = "background-color:#{i};"
+  end; alias background set_background # === background
+
+  # ========================================================================= #
+  # === scan_for_images_in_current_directory
+  # ========================================================================= #
+  def scan_for_images_in_current_directory
+    scan_for_images_in_this_directory(return_pwd)
+  end
+
+  # ========================================================================= #
+  # === set_this_directory_contains_all_images
+  # ========================================================================= #
+  def set_this_directory_contains_all_images(
+      i = :pwd
+    )
+    i = i.first if i.is_a? Array
+    case i
+    # ======================================================================= #
+    # === :pwd
+    #
+    # This entry points defaults to the current working directory.
+    # ======================================================================= #
+    when :pwd,
+         :default,
+         :return_pwd,
+         nil
+      i = return_pwd
+    end
+    if i
+      i = i.dup if i.frozen? # Ensure that we do not have a frozen String.
+      i << '/' unless i.end_with? '/'
+    end
+    @this_directory_contains_all_images = i
+  end; alias set_this_dir                           set_this_directory_contains_all_images # === set_this_dir 
+       alias set_work_on_this_directory             set_this_directory_contains_all_images # === set_work_on_this_directory
+       alias set_main_directory                     set_this_directory_contains_all_images # === set_main_directory
+       alias set_this_directory_contains_the_images set_this_directory_contains_all_images # === set_this_directory_contains_the_images
+
+  # ========================================================================= #
+  # === save_file
+  # ========================================================================= #
+  def save_file(
+      what = content_of_the_html_page?,
+      into = save_into_this_local_file?
+    )
+    into = File.absolute_path(into)
+    if @be_verbose
+      opnn; e "Now saving into the file `#{sfile(into)}`."
+    end
+    if File.exist? into
+      opnn; puts ::Colours.tomato('Warning: ')+
+                 sfile(into)+
+                 ::Colours.tomato(' already exists.')
+      opnn; puts ::Colours.tomato('We will delete it first.')
+      File.delete(into)
+    end
+    write_what_into(what, into)
+  end; alias save_what_to save_file # === save_what
+
+  # ========================================================================= #
+  # === do_use_HTML_table_layout
+  # ========================================================================= #
+  def do_use_HTML_table_layout
+    @internal_hash[:use_HTML_table_layout] = true
+  end
+
+  # ========================================================================= #
+  # === menu                                                       (menu tag)
+  # ========================================================================= #
+  def menu(
+      i = commandline_arguments?
+    )
+    if i.is_a? Array
+      i.each {|entry| menu(entry) }
+    else
+      case i # case tag
+      # ===================================================================== #
+      # === cweb --tablelayout
+      # ===================================================================== #
+      when /^-?-?tablelayout$/i,
+           /^-?-?table$/i,
+           /^-?-?html(-|_)?tables?$/i,
+           /^-?-?use(-|_)?HTML(-|_)?tables?$/i
+        do_use_HTML_table_layout
+      # ===================================================================== #
+      # === cweb --table=4 # 4 rows
+      #
+      # This entry point allows the user to set another number of rows
+      # for the generated HTML table.
+      # ===================================================================== #
+      when /^-?-?table=(.+)$/i
+        n_rows = $1.to_s.to_i
+        @internal_hash[:use_n_rows_for_the_html_table] = n_rows
+        do_use_HTML_table_layout
+      # ===================================================================== #
+      # === --pwd
+      # ===================================================================== #
+      when /^-?-?pwd$/i, # This means we store in the current directory.
+           :return_pwd
+        set_this_directory_contains_the_images(:pwd)
+        set_store_where(:infer)
+        clear_images
+        scan_for_images_in_this_directory
+        the_three_main_actions
+        exit
+      # ===================================================================== #
+      # === cweb --videos
+      #
+      # This entry point allows us to work on video-files only. If that
+      # is the case then the sorting-mode will be changed - aka to not
+      # sort at all.
+      # ===================================================================== #
+      when /^-?-?videos$/i,
+           /^-?-?videos(-|_)?only$/i
+        @work_on_video_files_only = true
+        @internal_hash[:sort_how] = :do_not_sort_at_all
+      # ===================================================================== #
+      # === cweb --do-not-traverse
+      #
+      # This will NOT check for any images in a subdirectory.
+      # ===================================================================== #
+      when /^-?-?do(-|_)?not(-|_)?traverse$/i,
+           /^-?-?simple$/i # cweb --simple
+        @do_traverse_into_subdirectories = false
+      # ===================================================================== #
+      # === --help
+      # ===================================================================== #
+      when /^-?-?help$/i
+        show_help
+        exit
+      # ===================================================================== #
+      # === ?
+      # ===================================================================== #
+      when '?'
+        opnn; e 'The file in question will be:'
+        e
+        e "  #{sfile(store_where?)}"
+        e
+        exit
+      # ===================================================================== #
+      # === --njoy
+      # ===================================================================== #
+      when /-?-?njoy$/i,
+           :njoy
+        e 'We will use the excellent images from a special directory.'
+        scan_there :njoy
+      else
+        if i.is_a?(String) and File.directory?(i)
+          # ================================================================= #
+          # (1) Assign a new main directory.
+          # ================================================================= #
+          set_this_directory_contains_all_images(i)
+          # ================================================================= #
+          # (2) Infer a new name for the locally saved file.
+          # ================================================================= #
+          set_save_into_this_local_file(
+            :use_the_directory_containing_all_images_as_base
+          )
+        end
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === run
+  # ========================================================================= #
+  def run
+    menu
+    debug if @debug
+    the_three_main_actions
+  end
+
+  # ========================================================================= #
+  # === show_help                                                  (help tag)
+  #
+  # This method will show usage-information, on the commandline, to the
+  # end user.
+  # ========================================================================= #
+  def show_help
+    e 'This class currently allows for these special arguments:'
+    e
+    e steelblue('  NJOY')
+    e steelblue('  PWD')
+    e steelblue('  ?')
+    e steelblue('  --videos-only     ')+lightgreen('# to work on video-files only')
+    e steelblue('  --do-not-traverse ')+lightgreen('# do not obtain images from any subdirectory')
+    e steelblue('  --use-HTML-table  ')+lightgreen('# display via a HTML table; currently hardcoded to 3 images per row')
+    e
+  end
+
+  # ========================================================================= #
+  # === build_up_the_HTML_string
+  #
+  # This is the method that will build up our resulting HTML string.
+  # ========================================================================= #
+  def build_up_the_HTML_string(
+      array = @array_work_on_these_files
+    )
+    _ = ''.dup # This will become the content for the HtmlTemplate.
+    # ======================================================================= #
+    # Next add jquery support, after the appropriate CSS was added.
+    # ======================================================================= #
+    if use_jquery?
+      _ << return_jquery
+    end
+    if use_HTML_table_layout?
+      _ << "<table style=\"table-layout: fixed\">\n" # This will force equally spaced cells.
+    end
+    # ======================================================================= #
+    # Next add the images. Note that return_image() will handle
+    # this situation for us.
+    # ======================================================================= #
+    unless array.empty?
+      array.each_with_index {|this_entry, index|
+        if work_on_video_files_only?
+          _ << '<div style="color: lightgreen">'
+          _ << HtmlTags.h2(this_entry, 'lightgreen')
+          _ << HtmlTags.video(this_entry)
+          _ << "<br>\n"
+          _ << "</div>\n"
+        else
+          if use_HTML_table_layout?
+            filesize_string = ' <span style="color: lightblue">'+
+                              '(<b>filesize</b>: <b>'+
+                              (File.size(this_entry).to_f / 1000.0).floor(0).to_s+
+                              '</b> <b>kb</b>)'+
+                              '</span>'
+            
+            raw_description_of_the_image = File.basename(this_entry).
+                                           delete_suffix(File.extname(this_entry)).
+                                           tr('_',' ')
+            # =============================================================== #
+            # Next make the leading date, in dd.mm.yyyy format, bold:
+            # =============================================================== #
+            description_of_the_image = '<br><span style="font-size: 1.2em; color: gold;">'+
+                                       raw_description_of_the_image.sub(
+                                         /(\d{1,2}\.?\d{1,2}\.?\d{4,4})/,
+                                         '(<b>\1</b>)'
+                                       )+'</span>'
+            this_entry = File.basename(this_entry) # We try this line as of October 2022.
+            case index % n_rows?
+            when 0 # This would mean we should do a new row.
+              _ << "<tr style=\"width:25%;\"><td style=\"width:28%\">"
+              _ << "<a target=\"_blank\" href=\"#{this_entry}\">#{return_image(this_entry)}#{description_of_the_image}"
+              _ << "</a>#{filesize_string}</td>\n"
+            when (n_rows? - 3),
+                 (n_rows? - 2)
+              _ << "<td style=\"width:28%\">"
+              _ << "<a target=\"_blank\" href=\"#{this_entry}\">#{return_image(this_entry)}#{description_of_the_image}"
+              _ << "</a>#{filesize_string}</td>\n"
+            when (n_rows? - 1)
+              _ << "<td style=\"width:28%\">"
+              _ << "<a target=\"_blank\" href=\"#{this_entry}\">#{return_image(this_entry)}#{description_of_the_image}"
+              _ << "</a>#{filesize_string}</td></tr>\n"
+            end
+          else
+            _ << return_image(this_entry)
+          end
+        end
+      }
+    end
+    set_content_of_the_html_page(_)
+  end
+
+end
+
+# =========================================================================== #
+# === Cyberweb.create_webpage_for_images
+# =========================================================================== #
+def self.create_webpage_for_images(
+    i = ARGV
+  )
+  Cyberweb::ImagesToHtml.new(i) { :use_jquery }
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  require 'colours/colours_e_autoinclude.rb'
+  _ = Cyberweb::ImagesToHtml.new(ARGV, :do_not_run_yet) { :use_jquery }
+  _.append_to_the_commandline_arguments(:return_pwd) # This is the default.
+  # ========================================================================= #
+  # The next line of code could be used to designate a black background.
+  #
+  #   _.background :black
+  #
+  # ========================================================================= #
+  # _.background :yellow
+  _.show_names
+  # _.scan_for_images_in_this_directory '$IMG/science'
+  # _.set_output_page_here('/Depot/Information/Images.html') # We store the data into this html file here.
+  # _.scan_for_images_in_this_directory '$IMG',true
+  # _.apply_filter 'only gifs'
+  _.run
+end # cweb $MY_DATA/images/NJOY/