cyberweb 0.8.17 → 0.9.31

data/doc/README.gen

@@ -42,7 +42,7 @@ project was renamed several times as well - first to **web_foundation**,
 then to **cybersprawl**, then to **Cyberweb**, then to **web_object** and
 then back to **Cyberweb** again.
 
-I think the name **Cyberweb** is the best choice best among these alternatives.
+I think the name **Cyberweb** is the best choice among these alternatives.
 While **web_object** is the more technically correct and accurate term, as
 everything related to the www is handled via that object (or such objects),
 I prefer the name **Cyberweb** in general for the whole project - it sounds
@@ -286,21 +286,44 @@ your use cases initially. In the long run I intend to remedy this
 situation, but for the time being, you have to accept that some
 parts of the cyberweb gem are not useful for you.
 
-Nonetheless, I decided to add this subsection to document some
-things, and provide some help to new users, until eventually
-the situation improves so that people can just install the gam
-and "it will work", as-is.
+Note that the above is no longer true since as of <b>January 2023</b>.
+I have decided, for several reasons, to simply distribute these
+images as well. They are available under:
+
+    cyberweb/images/standard_images/
+
+You can also view these images via a dedicated .html file, at:
+
+    cyberweb/images/standard_images/standard_images.html
+
+Some of these images are fairly old and require adaptations/changes,
+and adding these images has made the cyberweb gem significantly larger 
+as well, which is not great - but I think the drawbacks are outweighed
+by the advantage that now every user of the cyberweb gem can use
+these images as well, without me having to offer separate download
+links. I collected these images over the last 20 years, and some are
+probably outdated at this point in time, but again - some images may
+still need to be tweaked, file sized decreased, simplified, and what
+not. I will do so over the course of the coming months.
+
+I decided to add this subsection to document some things, and provide
+some help to new users, until eventually the situation improves so
+that people can just install the gam and "it will work", as-is.
 
 Without further ado, let's clarify some things here next.
 
-The cyberweb gem needs access to a temporary directory.
+The <b>cyberweb</b> gem needs access to a temporary directory.
 
 On Linux this is typically <b>/tmp/</b>. The cyberweb gem may
 create a subdirectory there, called cyberweb/, and then copy
 some files into that subdirectory - in particular JavaScript
-.js files.
+.js files. (If you have difficulties here, consider adding
+such a subdirectory there, with explicit permissions to
+allow people to dump data into that directory - after all
+that is the point of /tmp/ on linux.)
 
-To query the base directory in use you can call this method:
+To <b>query the base directory in use</b> you can call the
+following method:
 
     Cyberweb.temp_directory?
 
@@ -2785,9 +2808,12 @@ This can be done like this:
       transform: scale(1.3);
     }
 
-The important part is the **transform: scale** specification.
+The important part is the **transform: scale** specification. You
+can specify here how large or small the image should be. For
+instance, to shrink an image, you could use
+the CSS rule <b>transform: scale(0.5);</b>.
 
-I typically put this into a special CSS class such as:
+I typically put these rules into a special CSS class, such as:
 
     .enlarge_this_image_on_hover:hover {
       transform: scale(1.1);
@@ -3567,39 +3593,6 @@ This may look as the following image shows:
 
 <img src="https://i.imgur.com/moDx2f1.png" style="margin-left: 2em">
 
-## cmd1, cmd2, cmd3
-
-The three methods called **cmd1**, **cmd2**, **cmd3**, can be used to
-show commands that the user can input. The **1**, **2** or **3** part
-refers to the indent-level, so the number **3** means **3x the 
-basic indent level**.
-
-Note that **cmd** is an alias to **cmd1**.
-
-In the last ten years or so, the code for this was stored under the
-module PredefinedMethods, but in December 2021 this was changed and
-became part of **internal_hash.rb**. The latter shall slowly replace
-all other toplevel-instance variables for the Cyberweb project.
-The net gain will be that the new code is easier to maintain.
-
-What is the use case for cmd1 or cmd2 or cmd3?
-
-See the following examples for this:
-
-    e 'Input these instructions:'
-    br
-    cmd1 'ls -la'
-    cmd2 'cd /tmp'
-    # and so forth
-
-Note that you can also customize the toplevel CSS for cmd1, cmd2
-and cmd3. The following example shows how to add the steelblue
-colour to these:
-
-    append_to_cmd1 'steelblue'
-    append_to_cmd2 'steelblue'
-    append_to_cmd3 'steelblue'
-
 ## Cyberweb::RouteHandlerModule
 
 This module shall eventually replace sinatra for my own needs.
@@ -4064,6 +4057,21 @@ This would yield the following text (shown as image):
 
 <img src="https://i.imgur.com/Ufs2IHl.png" style="margin-left:2em">
 
+And let's show another example:
+
+    generate_drop_shadow :deepskyblue,
+                       '6px 4px 8px',
+                       'drop_shadow_deepskyblue'
+    div('drop_shadow_deepskyblue pad0px mar0px') {
+      h2 dot(105, 'marr12px')+
+         'Cats are adorable creatures.',
+         'mart5px'
+    }
+
+This time no image, but you get the idea - if you want a
+fancy border, cyberweb may help automatically generate
+these.
+
 You can also use the internal CSS class called **shadow_div_without_restrictions**.
 
 Give it a try on a div-element, such as via:
@@ -4603,6 +4611,26 @@ so.
 
 ## JavaScript support in the cyberweb project
 
+The following subsection shows some of the javascript-related
+code and possibilities in regards to the cyberweb project.
+
+### The method .dump_all_javascript() in Cyberweb::WebObject
+
+If you want to embed all javascript as a String and just
+put that string into the webpage, you can use this method
+call:
+
+    dump_all_javascript
+
+This is a bit hackish for now. The use case here was that
+a local .js file has to exist, in order for the browser
+to make use of it. For some reason this was not always
+the case on webservers I used - so, rather than invest
+more time to find the real problem, I simply added
+that method to be done with it and move it. That way
+I can still call custom javascript functions such
+as .toggle() and similar functions.
+
 ### JavaScript for-in and for-of loops:
 
 Just examples for each:
@@ -4775,6 +4803,11 @@ See the following file for a working example:
 
     cyberweb/examples/advanced/simple_calculator.cgi
 
+It looks about this, by default (but remember you
+can customize it via CSS):
+
+<img src="https://i.imgur.com/2LPIU49.png" style="margin: 1em">
+
 ## Showing a fancy CSS keyboard
 
 If you use Cyberweb::WebObject then a fancy CSS keyboard
@@ -4926,6 +4959,162 @@ the above could eventually be repurposed for other
 users too, if they have a bunch of external links
 they want to display on their homepage as well.
 I'll think about this for a while.)
+
+## cmd1, cmd2, cmd3, cmd4 and cmd5
+
+The five methods called **cmd1**, **cmd2**, **cmd3**, **cmd4** and
+**cmd5** can be used to show commands that the user can input; or
+otherwise points at important content in a paragraph.
+
+The **1**, **2** or **3** part refers to the indent-level, so
+the number **3** means **3x the basic indent level**.
+
+The default indent is "mars2em", which is the class I use to
+denote:
+
+    margin-left: 2em;
+    margin-right: 2em;
+
+So that is the default padding I tend to use among my own
+web-related ruby code. But, fear not, this can be changed
+by the user at-will, for any given webpage - thus allowing
+users to customize this, if they want to.
+
+Note that **cmd** is an alias to **cmd1**. **cmd** in turn
+originated from **command**, and historically I used this
+method to display linux-specific commands, to allow me to
+understand how to operate on a linux system effectively.
+
+In the last ten years or so, the code for this was stored under the
+module <b>PredefinedMethods</b>, but in December 2021 this was changed
+and became part of **internal_hash.rb** instead. The latter shall
+slowly replace all other toplevel-instance variables for the
+Cyberweb project. The net gain will be that the new code is
+easier to maintain.
+
+In <b>January 2023</b> the old :cmd entries were removed from
+internal_hash.rb and put into a new class, called 
+Cyberweb::Cmd. This is the base class for Cyberweb::Cmd1,
+Cyberweb::Cmd2 and so forth. I believe this arrangement
+makes it easier to maintain the new code; the old code was
+also polished as it was ported into the new structure.
+
+What is the use case for cmd1 or cmd2 or cmd3?
+
+See the following example for this:
+
+    e 'Input these instructions:'
+    br
+    cmd1 'ls -la'
+    cmd2 'cd /tmp'
+    # and so forth
+
+So here we output a small span-tag, "Input these instructions:",
+and then we simply show these commands to the user via indented
+level - cmd1 is first indentation level, cmd2 is the second
+one, meaning an indentation level of margin-left: 3em, and so
+forth.
+
+Note that you can also customize the toplevel CSS for cmd1, cmd2,
+cmd3, cmd4 and cmd5. The following example shows how to add the
+<b>steelblue</b> colour to these entries:
+
+    append_to_cmd1 'steelblue'
+    append_to_cmd2 'steelblue'
+    append_to_cmd3 'steelblue'
+    append_to_cmd4 'steelblue'
+    append_to_cmd5 'steelblue'
+
+However had, only do this when you really want to change the
+default CSS code there.
+
+## Output generated by the cyberweb project, in particular by the web-object
+
+This subsection was added in January 2023, because I had to rewrite
+some old functionality, to suit a new use case. This will be explained
+next.
+
+Before 2023, the two methods that were in use by Cyberweb::WebObject
+were:
+
+    ee()
+
+    # and
+
+    e()
+
+ee() was just an alias over print, in the sense that it would call
+the method .add() directly, without modifications. .add() will
+simply add the given input to the html-string variable of the
+WebObject. This is the string that contains the content of the
+webpage, e. g. all content of a .html page (or rather, its
+equivalent).
+
+e() on the other hand is more important and it is used primarily
+to generate output. This method will yield a span-tag, and 
+add a br-tag afterwards. This worked very well for my own use
+cases in the last 15 years or so.
+
+However had, starting in 2020, I was putting more and more 
+content into projects that cyberweb has to render and handle.
+In particular, one use case I found to increase in the last
+2 years (so from 2020 to 2022) was to use paragraphs such
+as this:
+
+    p_default {
+      e 'Hello world!'
+    } 
+
+This would generate the following HTML string:
+
+    <p class="default">
+    <span>Hello world!</span>
+    </p>
+
+For short paragraphs this is ok, but for longer paragraphs
+things can become a bit messy. It is harder and harder to
+read the content, in particular when there is a lot of
+text. So, naturally, to help space things a bit, I would
+transition to use this instead:
+
+    le 'Hello world!'
+
+This is exactly as:
+
+    e 'Hello world!'
+
+but it is making use of a CSS class called "padl2em" (or
+"padlem"). This CSS class will have a padding on the left
+hand side, e. g. "padding-left: 2em".
+
+However had, changing all e() calls to le() calls for
+every single paragraph is cumbersome, so I wanted to have
+an alternative to this.
+
+Thus, in January 2023 I decided to re-arrange the code,
+and add a new padding-call.
+
+So, the following variant will make use of e():
+
+    p_default {
+    }
+
+If you want to use le() instead (the variant for left-padding)
+then the following variant can be used:
+
+    p_default_le {
+    }
+
+At a later point in time this may be revisited. For now
+this has to suffice.
+
+Note that I am currently (2023) contemplating change
+the behaviour of ebr(). ebr() was the old legacy
+function what e() does nowadays. My idea is that 
+ebr() first calls e() and then br() (aka append
+a br-tag). I have not yet decided on this though -
+need to test it first.
+
 ## Useful quotes when designing websites and web-apps
 
 The following subsection collects a few <b>interesting statements</b> -
@@ -4934,88 +5123,87 @@ and software engineering in general. Do not take any of these
 at face-value 1:1 but feel free to use any of them them as a
 starting point for **gaining new insights**.
 
-"Any <b>good-enough</b> decision that can be made right now is
+„Any <b>good-enough</b> decision that can be made right now is
 still better than any 'perfect' decision that may come in
-way too late."
+way too late.“
  
-"When you are creating a website, the primary goal as a designer
+„When you are creating a website, the primary goal as a designer
 should be to get rid of the question marks users have when 
-visiting that site."
+visiting that site.“
 
-"The most important thing a designer can do is to understand
+„The most important thing a designer can do is to understand
 the basic principle of eliminating question marks that a user
-has when visiting a website. Keep things simple."
+has when visiting a website. Keep things simple.“
 
-"If you can not make something self-evident, you should at the
-least make it self-explanatory."
+„If you can not make something self-evident, you should at the
+least make it self-explanatory.“
 
-"If a web page is going to be effective, it has to work most
-of its beautiful magic at a single glance."
+„If a web page is going to be effective, it has to work most of
+its beautiful magic at a single glance.“
 
-"The average visitor rarely spends much time reading all 
+„The average visitor rarely spends much time reading all 
 content on a given web page, so focus on designing fewer
 elements that can be easily navigated, without too much
-distracting clutter."
+distracting clutter.“
 
-"If your design forces a visitor to incur a small learning 
-curve, make sure that the added value from this design 
-change leads to it being worth that additional learning 
-curve."
+„If your design forces a visitor to incur a small learning curve,
+make sure that the added value from this design change leads to
+it being worth that additional learning curve.“
 
-"Clarity trumps consistency."
+„Clarity trumps consistency.“
 
-"Each webpage should have a clear visual hierarchy."
+„Each webpage should have a clear visual hierarchy.“
 
-"Components in a webpage that are related logically
-should also be related visually."
+„Components in a webpage that are related logically
+should also be related visually.“
 
-"In order to make a website 'scan-friendly', make good use of
+„In order to make a website 'scan-friendly', make good use of
 headings having a larger font size. The headings should 
-indicate what a subsection is about."
+indicate what a subsection is about.“
 
-"When using a heading, make them visually somewhat closer
+„When using a heading, make them visually somewhat closer
 to the section they belong to, rather than equally spaced
-to the preceding paragraph."
+to the preceding paragraph.“
 
-"If you need the visitor to make a difficult choice, provide as
+„If you need the visitor to make a difficult choice, provide as
 much guidance as necessary - but not more. Be succinct here
 and provide only the smallest amount of information that
-will help the user."
+will help the user.“
 
-"Omit needless words. Vigorous writing is concise."
+„Omit needless words. Vigorous writing is concise.“
 
-"Try to make everything on a web-site self-explanatory or as
-close to it as possible."
+„Try to make everything on a web-site self-explanatory or as
+close to it as possible.“
 
-"Navigation should ideally remain clear, simple, and consistent."
+„Navigation should ideally remain clear, simple, and consistent.“
 
-"It may be useful to consider using an identifier, such as a logo
+„It may be useful to consider using an identifier, such as a logo
 or an image, for the website, and display this e. g. on the
 upper left corner. This may help visitors identify where they
 are, in particular if they tend to use several tabs in their
-browser."
+browser.“
 
-"If your website makes use of a menu-bar or navigation-bar, 
+„If your website makes use of a menu-bar or navigation-bar, 
 consider highlighting the current location that the user
-has or uses on that website."
+has or uses on that website.“
 
-"Ideally a website should convey the big picture, and make it
-clear what the site is about."
+„Ideally a website should convey the big picture, and make it
+clear what the site is about.“
 
-"If possible consider to use visual identifiers on the
+„If possible consider to use visual identifiers on the
 whole web-application at hand, to give visitors the
 right idea about this being a cohesive and integrated
-unit."
+unit.“
 
-"Changing a website at a later time is not necessarily trivial.
+„Changing a website at a later time is not necessarily trivial.
 Some percentage of users that have grown accustomed to a 
 layout will resist almost any kind of change, and even
 apparently simple changes often turn out to have
-far-reaching effects."
+far-reaching effects.“
 
-"Focus ruthlessly on fixing the most serious problems first."
+„Focus ruthlessly on fixing the most serious problems first.“
 
-"Make the best decision you can with the information you have."
+„Make the best decision you can with the information you have.“
 
 ## Useful Links