cyberweb 0.7.9 → 0.8.17

data/lib/cyberweb/toplevel_methods/misc.rb

@@ -61,6 +61,7 @@ module Cyberweb
   require 'cyberweb/toplevel_methods/s2.rb'
   require 'cyberweb/toplevel_methods/write_what_into.rb'
   require 'cyberweb/html_tags/option.rb'
+  require 'cyberweb/toplevel_methods/is_an_image.rb'
 
   # ========================================================================= #
   # === Cyberweb.return_all_images_from_this_webpage
@@ -334,56 +335,6 @@ module Cyberweb
     return `magick #{this_image} #{file_type}:- | base64`
   end
 
-  # ========================================================================= #
-  # === Cyberweb.sort_this_array_by_time
-  #
-  # This method can be used to sort an array by time. In particular it
-  # was designed to sort an array of image-files that include their
-  # "timestamp" as part of the filename.
-  # ========================================================================= #
-  def self.sort_this_array_by_time(array)
-    array.sort_by {|filename|
-      filename = File.basename(filename)
-      if filename =~ /\d{4}/ # Assume a year such as "1984" here.
-        # ================================================================= #
-        # Extract from the start to the year-part next.
-        #
-        # An example for a filename will be:
-        #
-        #   "2013_Marchettigasse_6_Garten_am_Abend.jpg".
-        #
-        # ================================================================= #
-        filename = filename.scan(/^.*\d{4}/).flatten.first
-        filename.tr!('_','.')
-        filename = filename.delete('^0-9.')
-        filename.squeeze!('.') # Some entries may now be "...1986".
-        filename.chop! if filename.end_with? '.'
-        if filename.start_with?('.')
-          if filename.count('.') > 1 # Assume here: ".2.1981"
-            filename.prepend('01') if filename.count('.') == 2
-          else
-            filename.prepend('01.01')
-          end
-        end
-        unless filename.include? '.'
-          unless filename.start_with?('.')
-            filename.prepend('.')
-          end
-          filename.prepend('01.01')
-        end
-        if filename.split('.')[1].to_i > 12
-          splitted = filename.split('.')
-          splitted[1] = '12'
-          filename = splitted.join('.')
-        end
-        sort_on_this = ::Time.parse(filename)
-      else
-        sort_on_this = ::Time.parse('01.01.1970') # Simply assume this here.
-      end
-      sort_on_this
-    }
-  end; self.instance_eval { alias sort_based_on_time sort_this_array_by_time } # === Cyberweb.sort_based_on_time
-
   # ========================================================================= #
   # === Cyberweb.return_all_html_tags_in_this_line
   # ========================================================================= #
@@ -1852,13 +1803,6 @@ and <b>newlines</b>.</p>
     return result
   end
 
-  # ========================================================================= #
-  # === Cyberweb.is_an_image_file?
-  # ========================================================================= #
-  def self.is_an_image_file?(i)
-    ARRAY_IMAGES.include?(File.extname(i).delete('.'))
-  end; self.instance_eval { alias is_an_image? is_an_image_file? } # === Cyberweb.is_an_image?
-
   # ========================================================================= #
   # === Cyberweb.sanitize_this_string_by_adding_a_newline_after_every_closing_HTML_tag
   #

data/lib/cyberweb/toplevel_methods/registered_ids.rb

@@ -24,6 +24,59 @@ module Cyberweb
   end; self.instance_eval { alias array_registered_ids  all_ids? } # === Cyberweb.array_registered_ids
        self.instance_eval { alias array_registered_ids? all_ids? } # === Cyberweb.array_registered_ids?
 
+  # ========================================================================= #
+  # === Cyberweb.sanitize_this_id
+  # ========================================================================= #
+  def self.sanitize_this_id(i)
+    return i.to_s.dup.downcase.
+             delete(':(),'). # We reject these characters.
+             tr(' ','_').
+             tr('-','_').
+             tr('.','_'). # This line was inherited from the old code in class Cyberweb::ImagesToHtml.
+             squeeze('_') # Multiple '_' are not so pretty.
+  end
+
+  require 'cyberweb/toplevel_methods/umlaute.rb'
+  # ========================================================================= #
+  # === Cyberweb.sanitize_id
+  #
+  # Use this method when you want to sanitize the given id.
+  #
+  # We will generate a valid HTML id through this method.
+  #
+  # Note that this is different to the method Cyberweb.sanitize_this_id().
+  # In the long run we may unify these two methods, but for now (2023)
+  # they are separate.
+  #
+  # Usage example:
+  #
+  #    Cyberweb.sanitize_id(' hey there')
+  #
+  # ========================================================================= #
+  def self.sanitize_id(i)
+    i = convert_back_german_umlauts(i)
+    # ======================================================================= #
+    # If we have two '#' tokens, check here:
+    # ======================================================================= #
+    if i.count('#') > 1 # Example: 'drag_#NAME#'
+      if i.include? '#NAME#'
+        filename = ::Cyberweb.filename?
+        new_name = File.basename(filename, File.extname(filename)).downcase
+        i = i.gsub(/#NAME#/, new_name)
+      end
+    end
+    i.strip! # Get rid of leading and trailing ' ' tokens.
+    i.gsub!(/ /,'_') if i.include? ' '
+    case i
+    when 'DEF' # Overrule.
+      filename = $0
+      filename = ensure_main_encoding(filename)
+      i = File.basename(filename).downcase.gsub(/\..*$/,'')
+    end
+    i = no_html(i) if i.include? '>' # We assume a HTML tag here.
+    return i
+  end
+
   # ========================================================================= #
   # === return_the_id
   # ========================================================================= #
@@ -131,43 +184,6 @@ module Cyberweb
     ee return_the_id(the_id)
   end
 
-  require 'cyberweb/toplevel_methods/umlaute.rb'
-  # ========================================================================= #
-  # === Cyberweb.sanitize_id
-  #
-  # Use this method when you want to sanitize the given id.
-  #
-  # We will generate a valid HTML id through this method.
-  #
-  # Usage example:
-  #
-  #    Cyberweb.sanitize_id(' hey there')
-  #
-  # ========================================================================= #
-  def self.sanitize_id(i)
-    i = convert_back_german_umlauts(i)
-    # ======================================================================= #
-    # If we have two '#' tokens, check here:
-    # ======================================================================= #
-    if i.count('#') > 1 # Example: 'drag_#NAME#'
-      if i.include? '#NAME#'
-        filename = ::Cyberweb.filename?
-        new_name = File.basename(filename, File.extname(filename)).downcase
-        i = i.gsub(/#NAME#/, new_name)
-      end
-    end
-    i.strip! # Get rid of leading and trailing ' ' tokens.
-    i.gsub!(/ /,'_') if i.include? ' '
-    case i
-    when 'DEF' # Overrule.
-      filename = $0
-      filename = ensure_main_encoding(filename)
-      i = File.basename(filename).downcase.gsub(/\..*$/,'')
-    end
-    i = no_html(i) if i.include? '>' # We assume a HTML tag here.
-    return i
-  end
-
   # ========================================================================= #
   # === sanitize_id
   # ========================================================================= #

data/lib/cyberweb/toplevel_methods/sort_this_array_by_time.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'cyberweb/toplevel_methods/sort_this_array_by_time.rb'
+# =========================================================================== #
+module Cyberweb
+
+  # ========================================================================= #
+  # === Cyberweb.sort_this_array_by_time
+  #
+  # This method can be used to sort an array by time. In particular it
+  # was designed to sort an array of image-files that include their
+  # "timestamp" as part of the filename.
+  # ========================================================================= #
+  def self.sort_this_array_by_time(array)
+    require 'time'
+    array.sort_by {|filename|
+      filename = File.basename(filename)
+      if filename =~ /\d{4}/ # Assume a year such as "1984" here.
+        # ================================================================= #
+        # Extract from the start to the year-part next.
+        #
+        # Examples for a filename may be:
+        #
+        #   "2013_Marchettigasse_6_Garten_am_Abend.jpg".
+        #   "41586_2012_BFnature10999_MOESM258_ESM-9391"
+        #
+        # ================================================================= #
+        filename = filename.scan(/^.*\d{4}/).flatten.first
+        filename.tr!('_','.')
+        filename = filename.delete('^0-9.')
+        filename.squeeze!('.') # Some entries may now be "...1986".
+        filename.chop! if filename.end_with? '.'
+        if filename.start_with?('.')
+          if filename.count('.') > 1 # Assume here: ".2.1981"
+            filename.prepend('01') if filename.count('.') == 2
+          else
+            filename.prepend('01.01')
+          end
+        end
+        unless filename.include? '.'
+          unless filename.start_with?('.')
+            filename.prepend('.')
+          end
+          filename.prepend('01.01')
+        end
+        if filename.split('.')[1].to_i > 12
+          splitted = filename.split('.')
+          splitted[1] = '12'
+          filename = splitted.join('.')
+        end
+        begin
+          sort_on_this = ::Time.parse(filename)
+        rescue
+          sort_on_this = ::Time.parse('01.01.1970') 
+        end
+      else
+        sort_on_this = ::Time.parse('01.01.1970') # Simply assume this here.
+      end
+      sort_on_this
+    }
+  end; self.instance_eval { alias sort_based_on_time sort_this_array_by_time } # === Cyberweb.sort_based_on_time
+
+end

data/lib/cyberweb/toplevel_methods/video.rb

@@ -15,21 +15,6 @@ module Cyberweb
   DEFAULT_VIDEO_WIDTH  = '380'
   DEFAULT_VIDEO_HEIGHT = '260'
 
-  # ========================================================================= #
-  # === imdb                                                       (imdb tag)
-  #
-  # Makes a link towards the "Internet Movie Database".
-  # ========================================================================= #
-  def imdb(
-      title, where_precisely
-    )
-    base_url = 'http://www.imdb.com/title/'
-    string_link(
-      base_url+where_precisely,
-      title
-    )
-  end
-
   # ========================================================================= #
   # === Cyberweb.embed_youtube_video                            (youtube tag)
   #
@@ -54,12 +39,25 @@ module Cyberweb
     begin
       require 'multimedia_paradise/videos/youtube_embedder.rb'
     rescue LoadError; end
-    _ = ''.dup
+    _ = ''.dup # Our String that will be returned.
+    use_this_css_class = ''.dup
     src = src.strip if src.is_a? String # We have no use for leading and trailing ' '.
+    # ======================================================================= #
+    # === Handle the case where width is a Hash next:
+    # ======================================================================= #
+    if width.is_a? Hash
+      # ===================================================================== #
+      # === :css_class
+      # ===================================================================== #
+      if width.has_key? :css_class
+        use_this_css_class << " #{width[:css_class]}"
+      end
+    end
+    #   embed_youtube_video 'https://www.youtube.com/watch?v=sAeMTsvGmoQ',
     if src.is_a? Array
-      src.each {|s| div { embed_youtube_video(s, width, height) } }
+      src.each {|entry| div { embed_youtube_video(entry, width, height) } }
     elsif src.include? ' '
-      src.split(' ').each {|s| div { embed_youtube_video(s) } }
+      src.split(' ').each {|entry| div { embed_youtube_video(entry) } }
     else
       # ===================================================================== #
       # Prepend proper youtube link:
@@ -70,7 +68,7 @@ module Cyberweb
       if src.include? 'watch'
         src.gsub!(/watch\?v\=/, 'v/')
       end
-      _ << '<object class="pad1em mar2em">'+N
+      _ << '<object class="'+use_this_css_class+'">'+N
       _ << '<param name="movie" value="'+src+'" />'+N
       _ << '<param name="wmode" value="transparent" />'+N
       _ << '<param name="allowFullScreen" value="true" />'+N # Allow fullscreen.
@@ -348,4 +346,19 @@ module Cyberweb
     ee _
   end
 
+  # ========================================================================= #
+  # === imdb                                                       (imdb tag)
+  #
+  # Makes a link towards the "Internet Movie Database".
+  # ========================================================================= #
+  def imdb(
+      title, where_precisely
+    )
+    base_url = 'http://www.imdb.com/title/'
+    string_link(
+      base_url+where_precisely,
+      title
+    )
+  end
+
 end

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

@@ -96,6 +96,11 @@ class ImagesToHtml < ::Cyberweb::Base # === Cyberweb::ImagesToHtml
      padding-left: 5px;'.
      delete("\n").squeeze(' ')
 
+  # ========================================================================= #
+  # === FONT_SIZE_TO_USE
+  # ========================================================================= #
+  FONT_SIZE_TO_USE = '1.3em'
+
   # ========================================================================= #
   # === initialize
   #  
@@ -185,7 +190,7 @@ class ImagesToHtml < ::Cyberweb::Base # === Cyberweb::ImagesToHtml
     # === @body_css_style
     # ======================================================================= #
     @body_css_style = '
-      background-color: black; color: white; font-size: 1.2em;'
+      background-color: black; color: white; font-size: '+FONT_SIZE_TO_USE+';'
     # ======================================================================= #
     # === @debug
     # ======================================================================= #
@@ -255,39 +260,6 @@ class ImagesToHtml < ::Cyberweb::Base # === Cyberweb::ImagesToHtml
     @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
   # ========================================================================= #
@@ -744,15 +716,6 @@ class ImagesToHtml < ::Cyberweb::Base # === Cyberweb::ImagesToHtml
     end
   end
 
-  # ========================================================================= #
-  # === run
-  # ========================================================================= #
-  def run
-    menu
-    debug if @debug
-    the_three_main_actions
-  end
-
   # ========================================================================= #
   # === show_help                                                  (help tag)
   #
@@ -771,6 +734,45 @@ class ImagesToHtml < ::Cyberweb::Base # === Cyberweb::ImagesToHtml
     e
   end
 
+  # ========================================================================= #
+  # === return_image
+  #
+  # Use this when you wish to append an image.
+  #
+  # This method will also have to create a proper ID for the image at
+  # hand, one that makes sense. On 25.01.2023 this was changed with
+  # a generic method first defined originally in Cyberweb::WebObject
+  # some time before that day. 
+  # ========================================================================= #
+  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_'+
+         Cyberweb.sanitize_this_id(new_filename)
+    # ======================================================================= #
+    # 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
+
   # ========================================================================= #
   # === build_up_the_HTML_string
   #
@@ -794,7 +796,18 @@ class ImagesToHtml < ::Cyberweb::Base # === Cyberweb::ImagesToHtml
     # this situation for us.
     # ======================================================================= #
     unless array.empty?
+      working_directory = return_pwd
       array.each_with_index {|this_entry, index|
+        original_this_entry = this_entry.dup
+        # =================================================================== #
+        # entry will refer to a String such as:
+        #
+        #   "/home/x/data/images/fotos/cats_and_dogs/aisha/01.01.2013_Aisha_schläft_im_Bett.jpg"
+        #
+        # =================================================================== #
+        # =================================================================== #
+        # This clause is only valid if we work on video-related multimedia.
+        # =================================================================== #
         if work_on_video_files_only?
           _ << '<div style="color: lightgreen">'
           _ << HtmlTags.h2(this_entry, 'lightgreen')
@@ -802,13 +815,19 @@ class ImagesToHtml < ::Cyberweb::Base # === Cyberweb::ImagesToHtml
           _ << "<br>\n"
           _ << "</div>\n"
         else
+          # ================================================================= #
+          # This clause will be entered if we use a HTML table layout.
+          # ================================================================= #
           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>'
-            
+            # =============================================================== #
+            # Determine the raw description for the image, based on the
+            # filename itself.
+            # =============================================================== #
             raw_description_of_the_image = File.basename(this_entry).
                                            delete_suffix(File.extname(this_entry)).
                                            tr('_',' ')
@@ -821,19 +840,20 @@ class ImagesToHtml < ::Cyberweb::Base # === Cyberweb::ImagesToHtml
                                          '(<b>\1</b>)'
                                        )+'</span>'
             this_entry = File.basename(this_entry) # We try this line as of October 2022.
+            use_this_for_the_href_entry = original_this_entry.sub(/#{working_directory}/,'')
             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 target=\"_blank\" href=\"#{use_this_for_the_href_entry}\">#{return_image(use_this_for_the_href_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}"
+              _ << "<td style=\"width: 28%\">"
+              _ << "<a target=\"_blank\" href=\"#{use_this_for_the_href_entry}\">#{return_image(use_this_for_the_href_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}"
+              _ << "<td style=\"width: 28%\">"
+              _ << "<a target=\"_blank\" href=\"#{use_this_for_the_href_entry}\">#{return_image(use_this_for_the_href_entry)}#{description_of_the_image}"
               _ << "</a>#{filesize_string}</td></tr>\n"
             end
           else
@@ -845,6 +865,15 @@ class ImagesToHtml < ::Cyberweb::Base # === Cyberweb::ImagesToHtml
     set_content_of_the_html_page(_)
   end
 
+  # ========================================================================= #
+  # === run
+  # ========================================================================= #
+  def run
+    menu
+    debug if @debug
+    the_three_main_actions
+  end
+
 end
 
 # =========================================================================== #

data/lib/cyberweb/utility_scripts/remove_this_image_from_that_webpage.rb

@@ -0,0 +1,125 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Cyberweb::RemoveThisImageFromThatWebpage
+#
+# This class will remove a specific image from a webpage, typically a
+# target .html file.
+#
+# So if you have something like "foobar.png", all <img> tags that have
+# this image will be removed. A backup will be created of that .html
+# file before modifications are made.
+#
+# Usage example:
+#
+#   RemoveThisImageFromThatWebpage.new(ARGV)
+#
+# =========================================================================== #
+# require 'remove_this_image_from_that_webpage.rb'
+# =========================================================================== #
+require 'cyberweb/base/base.rb'
+
+module Cyberweb
+
+class RemoveThisImageFromThatWebpage < Base # === Cyberweb::RemoveThisImageFromThatWebpage
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      this_image            = nil,
+      that_webpage          = nil,
+      run_already           = true
+    )
+    reset
+    @this_image = this_image
+pp that_webpage
+    @that_webpage = [that_webpage].flatten.compact
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    infer_the_namespace
+    # ======================================================================= #
+    # === @this_image
+    # ======================================================================= #
+    @this_image   = nil
+    # ======================================================================= #
+    # === @that_webpage
+    # ======================================================================= #
+    @that_webpage = []
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    if @that_webpage.empty?
+      e 'Please supply two arguments to this class:'
+      e
+      e '  (1) the image that you wish to remove from the .html file'
+      e '  (2) the local file you want to work on'
+      e
+      exit
+    end
+    @that_webpage.each {|this_webpage|
+      if this_webpage and File.exist?(this_webpage)
+        puts ::Colours.rev+'Now working on the file '+
+             sfile(this_webpage)+':'
+        dataset = File.read(this_webpage)
+        if dataset.include?(@this_image) and dataset.include?('<img')
+          # Ok in this case we can modify the file as-is.
+          puts rev+'Yes, the dataset contains the image '+
+               ::Colours.steelblue(@this_image)+rev+'.'
+          dataset = dataset.dup if dataset.frozen?
+          new_dataset = ''.dup
+          # ================================================================= #
+          # See: https://rubular.com/r/VsIipzUOSCDhA7
+          # ================================================================= #
+          # regex = /(<img.+src=".+" \/>)/
+          regex = /(<img.+src="#{@this_image}" \/>)/
+          dataset.split("\n").each {|line|
+            if line.include?('<img') and line.include?(@this_image)
+              line.gsub!(regex, '')
+            end
+            new_dataset << "#{line}\n"
+          }
+          backup_this_file(this_webpage)
+          write_what_into(new_dataset, this_webpage)
+        else
+          puts "No entry called #{::Colours.steelblue(@this_image)} "\
+               "was found."
+        end
+      else
+        opnn; no_file_exists_at(this_webpage)
+      end
+    }
+  end
+
+  # ========================================================================= #
+  # === backup_this_file
+  # ========================================================================= #
+  def backup_this_file(i)
+    target = log_dir?+File.basename(i)
+    puts 'Making a backup of the file '+sfile(i)+'. It will be copied'
+    puts 'towards '+target+'.'
+    copy_file(i, target)
+  end
+
+  # ========================================================================= #
+  # === Cyberweb::RemoveThisImageFromThatWebpage[]
+  # ========================================================================= #
+  def self.[](i = ARGV)
+    new(i)
+  end
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  Cyberweb::RemoveThisImageFromThatWebpage.new(ARGV[0], ARGV[1 .. -1])
+end # removethisimagefromthatwebpage brdrtpr.png *.htm

data/lib/cyberweb/version/version.rb

@@ -9,12 +9,12 @@ module Cyberweb
   # ========================================================================= #
   # === VERSION
   # ========================================================================= #
-  VERSION = '0.7.9'
+  VERSION = '0.8.17'
 
   # ========================================================================= #
   # === LAST_UPDATE
   # ========================================================================= #
-  LAST_UPDATE = '28.11.2022'
+  LAST_UPDATE = '26.01.2023'
 
   # ========================================================================= #
   # === URL_TO_THE_DOCUMENTATION