html_tags 0.1.183

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2dfb6a7ceee870efe17695d864a404afa2b67adf81322554ca400b86dbf6b070
+  data.tar.gz: 31f182401cbdb827a4e7d09b60138d315c2c067670406b89299c6886c134f505
+SHA512:
+  metadata.gz: 809ac6c23ebdaec820bdb7cb425f0c9c036bddecced0c1f9990e2d4b0d4490d0096c1752a3e025f9265f8d9d733bff48010122e2ecefae4595817e5479bc8b1a
+  data.tar.gz: 897ede2bae83ff5f3d0ecd13f2ddc2291c611c3c37b46eddcac55672beab625bbb9127e2e383887d6e634ba9c2978241b1c47d188213a562077f58f4f939a7b8

data/README.md

@@ -0,0 +1,456 @@
+[![forthebadge](https://forthebadge.com/images/badges/built-with-love.svg)](https://www.gobolinux.org/)
+[![forthebadge](https://forthebadge.com/images/badges/made-with-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Gem Version](https://badge.fury.io/rb/html_tags.svg)](https://badge.fury.io/rb/html_tags)
+
+This gem was <b>last updated</b> on the <span style="color: darkblue; font-weight: bold">19.02.2024</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">12:19:50</span> o'clock.
+
+## Introduction to the HtmlTags gem
+
+<img src="https://i.imgur.com/A1MaV0i.png" style="margin: 1em">
+
+The <b>HtmlTags gem</b> is a somewhat small gem that will try to
+<b>autogenerate Strings</b> put into methods resembling the
+available HTML tags.
+
+Let's next have a look at a specific example supporting this statement.
+
+Take the following method call in Ruby:
+
+    span('foo')
+
+So, we call the method span() and pass the String 'foo' into it. The
+method .span() can be found as part of the HtmlTags gem.
+
+This will be expanded towards the following String:
+
+    <span>foo</span>
+
+In other words: the HtmlTags gem can be used to autogenerate 
+HTML code.
+
+This functionality is then made available to other projects, which
+can tap into that functionality, in particular the gem <b>cyberweb</b>.
+I use the latter gem for my custom cgi/sinatra/rails projects.
+
+The code that was part in the html_tags gem originally used to
+be part of the <b>cyberweb</b> gem in the past, until <b>html_tags</b>
+became a standalone gem, in the year <b>2013</b>.
+
+## Goals and Objectives for the HtmlTags gem
+
+The HtmlTags gem has various goals, some of which are more important
+than others.
+
+In no particular order, here are the different goals for this gem:
+
+    - Provide a way to generate all valid HTML tags, in particular for HTML5.
+    - Provide useful documentation as to how to use this project.
+    - Make the code as consistent as possible, unless the specific HTML tag at hand requires a different treatment
+    - Make the HtmlTags as self-contained as possible, e. g. no external dependencies.
+    - Make the HtmlTags as useful as possible, by also providing helper code unrelated to HTML-tags itself.
+    - Document the HTML that is supported by the gem. 
+
+## New ideas (playground for new ideas)
+
+We could replace code elements such as:
+
+    <button onclick="show_source()">Click me</button>
+
+With:
+
+    button.text('Click me').onclick('show_source')
+
+Or perhaps simple:
+
+    button('Click me').on_clicked {
+      show_source
+    }
+
+This is currently not implemented, though. Need to think more about
+it first.
+
+## Using HTML headers
+
+The following example shows how to use the <b>h1 tag</b> via
+HtmlTags:
+
+    HtmlTags.h1('Hello world!') # => "<h1>\nHello world!\n</h1>"
+
+You can include the module HtmlTags. Then you can just type <b>h1()</b>
+directly.
+
+Another example, this time for the <b>div tag</b>:
+
+    name = 'Joe'
+    puts HtmlTags.div("Hello, #{name}!") # => <div>Hello, Joe!</div>
+
+## HtmlTags.a
+
+The HTML <b>a</b> tag is for hyperlinks; typically it contains a 
+**href** entry.
+
+You can pass in a Hash, too, including a few supported JavaScript
+functions.
+
+Example for the latter:
+
+    onclick: 'change_the_colour_to()'
+
+Note that you still have to write the function somewhere and pull it
+into the .html file (or .cgi file or whatever else you are using).
+
+I added support for this in <b>October 2021</b>, as I needed to have clickable
+links that change colour upon being clicked. I used that to memorize
+which links I clicked, without having to depend on CSS.
+
+## Objectified HTML Tags
+
+This is mostly for clarification. An objectified HTML tag is
+a HTML tag that can be used like an object.
+
+Example:
+
+    Span.new('Hello world!') # => <span>Hello world!</span>
+
+The html_tags gem currently does not support this, but support for this
+may be added in the future, depending on whether that use case turns
+out to be sufficiently useful.
+
+## How to use HtmlTags.span()
+
+The span-tag in HTML creates something like this:
+
+    <span>Hello world!</span>
+
+To attach a CSS class to this, in HTML, one can use something such
+as:
+
+    <span class="padl1em">Hello world!</span>
+
+This is simple HTML.
+
+The html_tags gem also allows these use cases.
+
+For instance, consider the following:
+
+    e HtmlTags.span('Hey there')
+
+This is equivalent to the first variant shown before.
+
+The actual output will be:
+
+    <span>
+    Hey there</span>
+
+So there is a newline after the starting span-tag. The
+reason as to this is that I feel that, for readability,
+it is better to have a newline show up if you want to
+do a view-source action on the resulting .html file.
+
+Not everyone may want this, so we may need to have to
+add a toggle to strip newlines there. But for the time
+being this has to suffice.
+
+## How to use HtmlTags.a()
+
+Usage example for how to use <b>HtmlTags.a()</b>:
+
+    HtmlTags.a(
+      remote_url: remote_url,
+      text:       title?.to_s,
+      css_style: 'font-weight: bold; color: darkblue'
+    )
+
+## The structure of opening and closing tags
+
+This subsection just shows a tiny bit of the structure behind
+opening and closing tags.
+
+Consider a HTML a tag such as:
+
+    <a>
+
+This has three components: <b><</b>, <b>a</b> and <b>></b>.
+
+These <b>three components</b> are, in order, called:
+
+- opening bracket
+- element ID
+- closing bracket
+
+The closing tag, that is:
+
+    </a>
+
+Has one more component, the /, also called the forward slash
+(unsurprisingly so).
+
+Note that an opening tag can contain attributes.
+
+## The bdo tag
+
+<b>bdo</b> stands for <b>bi-directional override</b>.
+
+The purpose of the bdo tag in HTML is to specify the text direction
+or to override the current text direction. This is important
+for languages such as <b>Arabic</b> or <b>Hebrew</b>.
+
+Personally I do not really need this tag, but in the event that
+other users of the <b>html_tag</b> gem need support for the bdo-tag,
+support for it has been added to the html_tag gem in <b>June 2023</b>.
+
+The <b>bdo tag</b> has a special attribute called <b>dir</b> - an
+abbreviation standing for <b>direction</b>.
+
+The dir attribute specifies the direction in which the text will
+be displayed.
+
+Only two values are permissive for the dir attribute:
+
+(1) <b>ltr</b>: It means left to right. The text inside the bdo tag will
+be rendered from left to right. This is the default value.
+
+(2) <b>rtl</b>: It means right to left. The text inside the bdo tag
+will be rendered from right to left.
+
+Note that you can use the CSS class rtl-lang instead, so I am not
+sure why that HTML tag is necessary.
+
+At any rate, an invocation example follows:
+
+    HtmlTags.bdo()
+
+## Working with HTML tables
+
+You can use <b>HtmlTags.table</b> to create a String that represents
+a HTML table. In January 2024 this functionality was extended a bit,
+in that you can pass an Array to this method, via the block form.
+That Array will be used as content for the HTML table at hand.
+
+Usage example is this API:
+
+    puts HtmlTags.table(nil,'mars1em','test_table','border:1px solid rand') {
+      %w( abc def ghi jkl )
+    }
+
+This would generate the following String:
+
+    <table class="mars1em" id="test_table" style="border:1px solid rand">
+    <tr><td>
+    abc</td><td>
+    def</td></tr><tr><td>
+    ghi</td><td>
+    jkl</td></tr>
+    </table>
+
+Quite convenient, isn't it?
+
+## Available HTML tags
+
+The following HTML tags are valid, in <b>HTML5</b>:
+
+
+<pre>
+# ============================================================================ #
+# Available HTML5 tags:
+#
+#   https://dev.to/flippedcoding/the-ultimate-html5-tag-list-4i2a
+#   https://www.w3.org/TR/2012/WD-html-markup-20121025/elements.html
+#   https://www.tutorialrepublic.com/html-reference/html5-tags.php
+#
+# ============================================================================ #
+
+# - !--...--
+# - !doctype
+- a
+- abbr
+# - acronym         # Not available in HTML5, so the html_tag gem will not support it.
+- address
+# - applet          # Not available in HTML5, so the html_tag gem will not support it.
+- area
+- article
+- aside
+- audio
+- b
+- base              # Not sure if this will be implemented by the html_tag gem.
+- basefont          # Not available in HTML5, so the html_tag gem will not support it.
+- bb                # Not available in HTML5, so the html_tag gem will not support it.
+- bdo               # bdo stands for "bi-directional override".
+- big               # Not available in HTML5, so the html_tag gem will not support it.
+- blockquote        # Supported by the html_tags gem.
+- body              # Supported by the html_tags gem.
+- br                #
+- button            # Supported by the html_tags gem.
+- canvas            # Supported by the html_tags gem.
+- caption           # Supported by the html_tags gem.
+- center
+- cite              # Supported by the html_tags gem.
+- code              # Supported by the html_tags gem.
+- col
+- colgroup
+- command
+- datagrid
+- datalist
+- dd
+- del               # Supported by the html_tags gem.
+- details           # Supported by the html_tags gem.
+- dfn
+- dialog            # Supported by the html_tags gem.
+# - dir             # This feature is no longer recommended. See: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dir
+- div               # Supported by the html_tags gem.
+- dl
+- dt
+- em                # Supported by the html_tags gem.
+- embed             # This one does not seem that useful anymore.
+# - eventsource     # This tag was removed from HTML5, so the HtmlTags won't support it.
+- fieldset          # Supported by the html_tags gem.
+- figcaption
+- figure            # Supported by the html_tags gem.
+# - font            # NOT supported in HTML5.
+- footer            # Supported by the html_tags gem.
+- form              # Supported by the html_tags gem.
+# - frame           # NOT supported in HTML5.
+# - frameset        # The <frameset> tag was used in HTML4 to define a frameset. It is not part of HTML5. 
+- h1                # Supported by the html_tags gem.
+- h2                # Supported by the html_tags gem.
+- h3                # Supported by the html_tags gem.
+- h4                # Supported by the html_tags gem.
+- h5                # Supported by the html_tags gem.
+- h6                # Supported by the html_tags gem.
+- head              # Supported by the html_tags gem.
+- header            # Supported by the html_tags gem.
+- hgroup            # Supported by the html_tags gem.
+- hr                # Supported by the html_tags gem.
+- html              # Supported by the html_tags gem.
+- i                 # Supported by the html_tags gem.
+- iframe            # Supported by the html_tags gem.
+- img               # Supported by the html_tags gem.
+- input             # Supported by the html_tags gem.
+- ins               # Supported by the html_tags gem.
+# - isindex         # This has been removed from HTML5.
+- kbd               # Supported by the html_tags gem. The kbd element represents user input.
+- keygen            # Supported by the html_tags gem.
+- label             # Supported by the html_tags gem.
+- legend            # Supported by the html_tags gem.
+- li                # Supported by the html_tags gem.
+- link              # Supported by the html_tags gem.
+- map               # Supported by the html_tags gem.
+- mark              # Supported by the html_tags gem.
+- menu              # Supported by the html_tags gem.
+- meta
+- meter
+- nav
+- noframes
+- noscript
+- object            # Supported by the html_tags gem.
+- ol
+- optgroup
+- option
+- output
+- p
+- param
+- pre
+- progress          # Supported by the html_tags gem.
+- q
+- rp
+- rt
+- ruby
+- s
+- samp
+- script
+- section
+- select
+- small
+- source            # Supported by the html_tags gem.
+- span
+- strike
+- strong
+- style             # Supported by the html_tags gem.
+- sub
+- summary           # Supported by the html_tags gem.
+- sup               # Supported by the html_tags gem.
+- table             # Supported by the html_tags gem.
+- tbody
+- td
+- textarea          # Supported by the html_tags gem.
+- tfoot
+- th                # Supported by the html_tags gem.
+- thead             # Supported by the html_tags gem.
+- time              # Supported by the html_tags gem.
+- title             # Supported by the html_tags gem.
+- tr                # Supported by the html_tags gem.
+- track             # Supported by the html_tags gem.
+# - tt              # This is no longer valid as of HTML5.
+- u                 # Supported by the html_tags gem.
+- ul                # Supported by the html_tags gem.
+- var               # Supported by the html_tags gem.
+- video             # Supported by the html_tags gem.
+- wbr               # This is the "Word Break Opportunity" tag.
+</pre>
+
+
+In the long run the HtmlTags project should offer support
+for <b>all</b> these HTML tags. This applies mostly to HTML5-tags
+though; for instance, the <b>acronym tag</b> is no longer valid
+in HTML5, and will thus not be supported by the html_tags
+project.
+
+
+## Contact information and mandatory 2FA (no longer) coming up in 2022 / 2023
+
+If your creative mind has ideas and specific suggestions to make this gem
+more useful in general, feel free to drop me an email at any time, via:
+
+    shevy@inbox.lt
+
+Before that email I used an email account at Google gmail, but in **2021** I
+decided to slowly abandon gmail, for various reasons. In order to limit the
+explanation here, allow me to just briefly state that I do not feel as if I
+want to promote any Google service anymore when the user becomes the end
+product (such as via data collection by upstream services, including other
+proxy-services). My feeling is that this is a hugely flawed business model
+to begin with, and I no longer wish to support this in any way, even if
+only indirectly so, such as by using services of companies that try to
+promote this flawed model.
+
+In regards to responding to emails: please keep in mind that responding 
+may take some time, depending on the amount of work I may have at that
+moment. So it is not that emails are ignored; it is more that I have not
+(yet) found the time to read and reply. This means there may be a delay
+of days, weeks and in some instances also months. There is, unfortunately,
+not much I can do when I need to prioritise my time investment, but I try
+to consider <b>all</b> feedback as an opportunity to improve my projects
+nonetheless.
+
+In <b>2022</b> rubygems.org decided to make 2FA mandatory for every
+gem owner eventually:
+
+see
+https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
+
+Mandatory 2FA will eventually be extended to all rubygems.org developers and
+maintainers. As I can not use 2FA, for reasons I will skip explaining here,
+this means that my projects will eventually be removed, as I no longer
+have any control over my projects hosted on rubygems.org (because I
+can not use 2FA).
+
+At that point, I no longer have any control what is done to my projects
+since whoever is controlling the gems ecosystem took away our control
+here. I am not sure at which point ruby became corporate-controlled -
+that was not the case several years ago, so something has
+changed.
+
+Ruby also only allows 2FA users to participate on the issue tracker these
+days:
+
+  https://bugs.ruby-lang.org/issues/18800
+
+But this has been reverted some months ago, so it is no longer applicable.
+Suffice to say that I do not think that we should only be allowed to
+interact on the world wide web when some 'authority' authenticated us,
+such as via mandatory 2FA, so I hope this won't come back again.
+
+Fighting spam is a noble goal, but when it also means you lock out
+real human people then this is definitely NOT a good situation
+to be had.
+

data/USAGE.md

@@ -0,0 +1,17 @@
+= Usage of this Library
+
+== Requiring it
+
+  require 'html_tags'
+
+== Using it in a project
+
+  puts HtmlTags.is_valid_html? '<br>'
+  puts HtmlTags.is_valid_html? '<div>'
+  puts HtmlTags.is_valid_html? '<dav>'
+  puts HtmlTags.string_contains_only_valid_html_tags? 'hello ruby </br>'
+  puts HtmlTags.string_contains_only_valid_html_tags? 'hello ruby<haha>'
+
+  include HtmlTags # Or simply include it, but be careful with this.
+
+  p 'hi there' # This now works - it has however redefined p().