j1-template 2023.7.0 → 2023.8.0

data/lib/starter_web/pages/public/manuals/speak2me.adoc

@@ -1,412 +0,0 @@
----
-title:                                  Speak2Me
-title_extention:                        J1 Module for Speech Synthesise (TTS)
-tagline:                                Screen Reader for J1 Template
-
-date:                                   2023-07-26
-#last_modified:                         2023-01-01
-
-description: >
-                                        Speak2Me for J1 Template is a speech synthesise module that enables a
-                                        so-called screen reader. The reader functionality allows users to sit back
-                                        and listen to the browser read aloud the important contents on a Web page.
-keywords: >
-                                        open source, free, template, jekyll, jekyllone, web,
-                                        sites, static, jamstack, bootstrap,
-                                        speech, synthesise, sst, j1 module, jquery
-
-categories:                             [ Module ]
-tags:                                   [ Speech Synthesise, jQuery ]
-
-regenerate:                             true
-permalink:                              /pages/public/modules/speak2me/
-
-resources:                              [ animate, clipboard, lightbox, rouge ]
-resource_options:
-  - attic:
-      slides:
-        - url:                          /assets/images/pages/roundtrip/images-1920x1280-bw.jpg
-          alt:                          Photo by Ricardo Gomez Angel on Unsplash
-          badge:
-            type:                       unsplash
-            author:                     Ricardo Gomez Angel
-            href:                       https://unsplash.com/@ripato/portfolio
----
-
-// Page Initializer
-// =============================================================================
-// Enable the Liquid Preprocessor
-:page-liquid:
-
-// Set (local) page attributes here
-// -----------------------------------------------------------------------------
-// :page--attr:                         <attr-value>
-
-//  Load Liquid procedures
-// -----------------------------------------------------------------------------
-{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
-
-// Load page attributes
-// -----------------------------------------------------------------------------
-{% include {{load_attributes}} scope="none" %}
-
-// Page content
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-// https://github.com/mdn/dom-examples/tree/main/web-speech-api
-// https://mdn.github.io/dom-examples/web-speech-api/speak-easy-synthesis/
-// https://stackoverflow.com/questions/11279291/a-good-text-to-speech-javascript-library
-// https://codepen.io/meetselva/pen/EVaLmP
-// https://dev.to/jankapunkt/cross-browser-speech-synthesis-the-hard-way-and-the-easy-way-353
-//
-[role="dropcap"]
-Speech synthesis is an application programming interface (API) in web
-development that allows web browsers to generate synthesized speech,
-commonly known as text-to-speech (TTS). It enables developers to incorporate
-speech synthesis functionality into web pages, applications, and other
-online experiences.
-
-With the speech synthesis API, you can convert text into speech, and the
-synthesized speech can then be played through the user's speakers or
-headphones. Spoken content is especially useful for making web content
-more accessible to individuals with visual impairments and for adding
-interactive voice elements to web applications.
-
-// Include sub-documents (if any)
-// -----------------------------------------------------------------------------
-[role="mt-5"]
-== Installation
-
-Speak2Me is a jQuery plugin that enables developers, with as little as
-one line of code, to create links that allow users to click, sit back, and
-listen to the browser read aloud the important content on a Web page.
-In some ways, it can turn a thoughtful essay or article into a mini podcast.
-And because it uses built-in JavaScript functionality, no browser extensions
-or other system software is needed.
-
-Simply include the `speak2me.js` or `speak2me.min.js` file in your project.
-
-[role="mt-5"]
-== API Reference
-
-Leverage the powerful selector options of jQuery to specify which parts
-of the Web page that you want spoken. For example, depending on how you
-have the Web page organized, a single line of code, like the following,
-can direct Speak2Me to speak the entire contents of an article or a
-blog post.
-
-[source, javascript]
-----
-$('article').speak2me('speak')
-----
-
-Or how about only the primary headers and paragraphs
-
-[source, javascript]
-----
-$('h1,h2,p').speak2me('speak')
-----
-
-NOTE: Internally, Speak2Me clones the matched set of elements and all
-their descendant elements and text nodes. It then parses this clone
-using a default set of rules, deciding what should be spoken and
-ignored, then adding the appropriate pauses to make everything sound
-more like a narrative.
-
-=== Examples
-
-Do not speak the content of `<h5>`, `<h6>`, and `<em>` tags.
-[source, javascript]
-----
-$().speak2me('ignore','h5','h6','em')
-----
-
-Speak the content of `<button>` and `<code>` tags.
-[source, javascript]
-----
-$().speak2me('recognize','button','code')
-----
-
-When `i.e.` is encountered, say `That is`.
-[source, javascript]
-----
-$().speak2me('replace','i.e.','That is')
-----
-
-Change default intro text spoken when an HTML tga `<img>` is
-encountered.
-[source, javascript]
-----
-$().speak2me('customize','img','Embedded')
-----
-
-Change default intro and outro text spoken when an HTML tag `<ol>`
-is encountered.
-[source, javascript]
-----
-$().speak2me('customize','ol','Start of numbered List.','End of Numbered List')
-----
-
-=== Base Functions
-
-[cols="6a,6a", options="header", width="100%", role="rtable"]
-|===
-|Method |Description
-
-|`$(selector).speak2me('speak')`
-|Speaks aloud the specified DOM element(s) and their descendants.
-
-|`$().speak2me('pause')`
-|Pauses the speaking.
-
-|`$().speak2me('resume')`
-|Resumes the speaking after it has been paused.
-
-|`$().speak2me('stop')`
-|Stops the speaking permanently.
-
-|===
-
-=== Voice Parameters
-
-[cols="4a,5a,3", options="header", width="100%", role="rtable"]
-|===
-|Method |Description |Default\|Range
-
-|`$().speak2me('rate', number)`
-|Sets the rate of the speaking voice.
-|Default: 1.1 +
-Range: [0.1 - 10.0]
-
-|`$().speak2me('pitch', number)`
-|Sets the pitch of the speaking voice.
-|Default: 1.0 +
-Range: [0.0 - 2.0]
-
-|`$().speak2me('volume', number)`
-|Sets the volume of the speaking voice.
-|Default: 1.0 +
-Range: [0.0 - 1.0]
-|===
-
-NOTE: Omitting number resets the parameter to its default value;
-changes take effect only when next speak call is made
-
-=== Read-Only Attributes
-
-[cols="6a,6a", options="header", width="100%", role="rtable"]
-|===
-|Method |Description
-|`$().speak2me('enabled')`
-|Returns `true`\|`false` specifying whether the browser supports
-the Web *Speech API*.
-
-|`$().speak2me('isSpeaking')`
-|Returns `true`\|`false` specifying whether speaking has not
-yet been completed or stopped.
-
-|`$().speak2me('isPaused')`
-|Returns `true`\|`false` specifying whether speaking is paused.
-|===
-
-NOTE: `$().speak2me('isSpeaking')` returns the value of true even
-when paused
-
-=== Get and Set Voices
-
-NOTE: Language codes consist of two-characters that specify the
-language, followed by a hyphen, followed by additional characters that
-specify the particular country or regional dialect of that language. For
-example, the codes ``en-US'' and ``en-GB'' are both English language,
-but each represent a different country.
-
-[cols="6a,6a", options="header", width="100%", role="rtable"]
-|===
-|Method |Description
-
-|`$().speak2me('getVoices')`
-|Returns an array of voice objects; each object has two properties:
-`name` and `language`
-
-|`$().speak2me('getVoices',selector,text)`
-|Populates the DOM element(s) _selector_ with a dropdown menu for
-voice selection; optional _text_ overwrites default dropdown menu instruction
-
-|`$().speak2me('setVoice','name',voice)`
-|Sets the voice. Must exactly match one of the names returned
-when using `getVoices`.
-
-|`$().speak2me('setVoice','language',twoDigit)`
-|Sets the voice by finding the first voice that matches the _two digit_
-language code (case-insensitive).
-
-|`$().speak2me('setVoice','language',code)`
-|Sets the voice by finding the first voice that exactly matches the
-complete language code
-|===
-
-.Setting a Voice
-[TIP]
-====
-Setting a voice by specifying only a two-digit language code is
-useful for when you have text on the page in another language, but don’t
-want to bother checking to see if that language is available. For
-example, a page otherwise in English may have a paragraph in German that
-you want spoken. That paragraph can have a link like this:
-
-`$('p').speak2me('setVoice','language','de').speak2me('speak')`
-====
-
-If the German language is available, it will be appropriately spoken. If
-not, the current voice will remain.
-
-=== Text Manipulation
-
-[cols="6a,6a", options="header", width="100%", role="rtable"]
-|===
-|Method |Description
-
-|`$().speak2me('ignore',tagName,tagName,...)`
-|Adds one or more *HTML tags* to the default array of ignored HTML tags.
-Omitting _tagName_ clears the array of user-specified ignored HTML tags. +
-See Reference Information below
-
-|`$().speak2me('recognize',tagName,tagName,...)`
-|Removes one or more *HTML tags* from the default array of ignored
-HTML tags. Omitting _tagName_ clears the array of user-specified
-recognized HTML tags. +
-See Reference Information below
-
-|`$().speak2me('replace',oldText,newText,...)`
-|Replaces _oldText_ with _newText_ when speaking. This is case-insensitive
-Multiple pairs of text can be specified. Omitting parameters deletes previous
-replace commands
-
-|`$().speak2me('customize',tagName,prepend)`
-|Replaces default text spoken prior to the description of the *HTML tags*
-`<img>`, `<table>`, and `<figure>`. Omitting parameters reverts values to
-its defaults. +
-See Reference Information below
-
-|`$().speak2me('customize',tagName,prepend,append)`
-|Replaces default text spoken prior to and after the content of the
-*HTML tags* `<q>`, `<ol>`, `<ul>`, and `<blockquote>`. +
-Omitting parameters reverts values to its defaults. +
-See Reference Information below
-|===
-
-=== HTML Data Attributes
-
-[cols="6a,6a", options="header", width="100%", role="rtable"]
-|===
-|Data Attribute |Description
-
-|`data-speak2me-ignore`
-|Content from that DOM element and its descendents are ignored.
-
-|`data-speak2me-recognize`
-|Content from that DOM element is spoken, overriding the default.
-
-|`data-speak2me-spell`
-|Content from that DOM element is spelled out.
-
-|`data-speak2me-prepend=text`
-|Specified _text_ is spoken prior to the content of its DOM element.
-
-|`data-speak2me-append=text`
-|Specified _text_ is spoken after to the content of its DOM element.
-
-|`data-speak2me-swap=text`
-|Specified _text_ is spoken in place of the content of its DOM element.
-|===
-
-=== Reference Information
-
-Chaining calls is acceptable. For example, the following works just
-fine.
-[source, javascript]
-----
-$('article').speak2me('rate',1.3).speak2me('speak');
-----
-
-CAUTION: *Ignored Tags:* audio, button, canvas, code, del, dialog, dl, embed,
-form, head, iframe, meter, nav, noscript, object, s, script, select,
-style, textarea, video
-
-[cols=",,", options="header", width="100%", role="rtable"]
-|===
-|HTML Tag |Default Prepend Text |Default Append Text
-|`<img>` |There’s an embedded image with the description, |n/a
-|`<table>` |There’s an embedded table with the caption, |n/a
-|`<figure>` |There’s an embedded figure with the caption, |n/a
-|`<q>` and “ ” |Quote, |, Unquote,
-|`<ol>` |Start of list. |End of list.
-|`<ul>` |Start of list. |End of list.
-|`<blockquote>` |Blockquote start. |Blockquote end.
-|===
-
-IMPORTANT: A comma `,` followed by a space results in a pause when
-spoken. A period `.` results in a *slightly* longer *pause*.
-
-
-[role="mt-5"]
-== Issues
-
-=== Issues can't be fixed with JavaScript
-
-Some issues are platform-specific. You need to your app in a way to avoid
-these issues, where possible:
-
-* All browsers on Android actually do a cancel/stop when calling
-`peechSynthesis.pause`; pause is simply not supported on Android
-
-* There are *no* voices on *Chromium-Ubuntu* and Ubuntu-derivatives
-  unless the browser is started with a flag
-* If on Chromium-Desktop Ubuntu and the very first page wants to load
-  speech synthesis, then there are no voices ever loaded until the
-  page is refreshed or a new page is entered. This can be fixed with
-  JavaScript but it can lead to very bad UX to auto-refresh the page.
-* If voices are not installed on the host-OS and there are no voices
-  loaded from remote by the browser, then there are no voices and
-  thus no speech synthesis
-* There is no chance to just instant-load custom voices from remote
-  and use them as a shim in case there are no voices
-* If the installed voices are just bad users have to manually install
-  better voices
-
-=== Chrome-specific fix
-
-Longer texts on Chrome-Desktop will be cancelled automatically after
-*15 seconds*. This can be fixed by either chunking the texts or by
-using an interval of "zero"-latency pause/resume combination. At the
-same time this fix breaks on *Android*, since Android devices don't implement
-speechSynthesis.pause() as pause but as cancel:
-
-[source, javascript]
-----
-let timer
-
-utterance.onstart = () => {
-  // detection is up to you for this article as
-  // this is an own huge topic for itself
-  if (!isAndroid) {
-    resumeInfinity(utterance)
-  }
-}
-
-const clear = () => {  clearTimeout(timer) }
-
-utterance.onerror = clear
-utterance.onend = clear
-
-const resumeInfinity = (target) => {
-  // prevent memory-leak in case utterance is deleted, while this is ongoing
-  if (!target && timer) { return clear() }
-
-  speechSynthesis.pause()
-  speechSynthesis.resume()
-
-  timer = setTimeout(function () {
-    resumeInfinity(target)
-  }, 5000)
-}
-----

data/lib/starter_web/pages/public/tools/cheatsheet/gem.adoc

@@ -1,259 +0,0 @@
----
-title:                                  Gem
-tagline:                                Cheatsheet for daily use
-
-date:                                   2023-05-19
-#last_modified:                         2023-01-01
-
-description: >
-                                        J1 Template is a Bootstrap V5 website template for the static
-                                        site generator Jekyll.
-                                        The Cheatsheet discuss RubyGems commands for daily use.
-                                        RubyGems is a package manager for the Ruby programming language. It provides
-                                        a convenient way to distribute and manage software packages, called gems,
-                                        written in Ruby. With RubyGems, developers can easily install, uninstall, and
-                                        manage Ruby libraries and applications.
-keywords: >
-                                        Jekyll, Theme, JekyllOne, Info, Manual, Cheatsheet, Ruby, Gem
-
-categories:                             [ Manual ]
-tags:                                   [ Cheatsheet, Gem ]
-
-image:
-  path:                                 /assets/images/modules/attics/1920x1280/recha-oktaviani.jpg
-  width:                                1920
-  height:                               1280
-
-regenerate:                             false
-permalink:                              /pages/public/tools/cheatsheet/gem/
-
-resources:                              [ animate, clipboard, rouge ]
-resource_options:
-  - attic:
-      slides:
-        - url:                          /assets/images/modules/attics/1920x1280/recha-oktaviani.jpg
-          alt:                          Photo by Recha Oktaviani on Unsplash
-          badge:
-            type:                       unsplash
-            author:                     Recha Oktaviani
-            href:                       https://unsplash.com/de/@rechaoktaviani
----
-
-// Page Initializer
-// =============================================================================
-// Enable the Liquid Preprocessor
-:page-liquid:
-
-// Set (local) page attributes here
-// -----------------------------------------------------------------------------
-// :page--attr:                         <attr-value>
-
-//  Load Liquid procedures
-// -----------------------------------------------------------------------------
-{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
-
-// Load page attributes
-// -----------------------------------------------------------------------------
-{% include {{load_attributes}} scope="global" %}
-
-
-// Page content
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-// Include sub-documents (if any)
-// -----------------------------------------------------------------------------
-[role="dropcap"]
-The Cheatsheet discuss RubyGems commands for daily use.
-RubyGems is a package manager for the Ruby programming language. It provides
-a convenient way to distribute and manage software packages, called GEMs.
-With RubyGems, developers can easily install, uninstall, and manage Ruby
-libraries and applications. It simplifies obtaining and managing the
-dependencies needed for a Ruby project by automatically resolving and
-installing the GEMs required.
-
-NOTE: The term `gem` is related to the *tool* provided by RubyGems. `GEM`
-(capital letters) means the *library* to be managed by the command `gem`
-at the command line.
-
-RubyGems also provides a centralized *repository*, the RubyGems website
-at https://rubygems.org/[rubygems.org, {browser-window--new}], where developers
-can publish their *GEMs* for others to use. The website serves as a searchable
-catalog of available GEMs, allowing developers to discover and download GEMs
-for their projects.
-
-TIP: In addition to the default RubyGems repository, developers can
-configure their own GEM sources or specify alternative sources when
-installing GEMs. This flexibility allows private GEM repositories or
-custom sources to be used as needed.
-
-RubyGems comes pre-installed with a Ruby installation. It provides
-a command-line interface, the `gem` command, for performing various
-operations, such as installing GEMS, listing installed libraries,
-updating GEMs, and managing library sources.
-
-Here are *common* commands you can use with the RubyGems `gem` command:
-
-* *install*     -- Installs a GEM from the default RubyGems repository
-* *uninstall*   -- Uninstalls a GEM
-* *update*      -- Updates installed GEMs to their latest versions
-* *search*      -- Searches for GEMs matching a specific term
-* *list*        -- Lists all installed GEMs
-* *info*        -- Provides information about a specific GEM
-* *cleanup*     -- Removes old versions of installed GEMs, keeping only the latest version
-
-The following examples give your an overview of the most *common* used
-commands managing Ruby GEMs for daily use. All examples are focussing the *J1*
-template to make it easier for users using the template system. Anyway, all
-commands can be used for *any* Ruby Appication by simply replacing the *name*
-of the GEM as required.
-
-// Include sub-documents (if any)
-// -----------------------------------------------------------------------------
-[role="mt-5"]
-== Install commands
-
-The `install` command installs software packages (libraries) in the
-Ruby programming language. The command will then search for the
-GEM specified on the _RubyGems_ website (or a diifrerebt GEM
-repository configured), download it, and finally install it on your
-system.
-
-=== Install from a Gemfile
-
-Add this line to your application's Gemfile:
-
-[source, sh]
-----
-gem 'j1_template', '~> 2023.4.2'
-----
-
-and install the locally created RubGem as:
-
-[source, sh]
-----
-gem install --local j1-template --no-document
-----
-
-=== Install globally
-
-bla ... latest version ...
-
-[source, sh]
-----
-gem install j1-template
-----
-
-=== Install with no docs
-
-bla ... latest version ...
-
-[source, sh]
-----
-gem install j1-template --no-document
-----
-
-=== Install userized
-
-bla ... latest version ...
-
-When you use the `--user-install` option, RubyGems will install the GEMs
-to a directory inside your *home* directory under `~/.gem/ruby/3.1.0`
-for Ruby version `3.1.x`. The *commands* provided by the GEMs you have
-installed will end up in folder `~/.gem/ruby/3.1.0/bin`.
-
-[source, sh]
-----
-gem install j1-template --user-install --no-document
-----
-
-For GEMs installed *userized* that contain *programs*, you need to add
-the folder `~/.gem/ruby/3.1.0/bin` to your `PATH` environment variable
-to get access.
-
-=== Install a specific version
-
-bla ... specific version ...
-
-[source, sh]
-----
-gem install j1-template -v 2023.4.2 --user-install --no-document
-----
-
-You can also use *version* comparators like `>=` or `~>`.
-
-[source, sh]
-----
-gem install j1-template -v "~> 2023.4.2" --user-install --no-document
-----
-
-=== Install from a different source
-
-bla ... specific version ...
-
-[source, sh]
-----
-gem install j1-template -v 2023.4.2 --source 'https://gem.fury.io/jekyll-one-org/' --user-install --no-document
-----
-
-[role="mt-5"]
-== Uninstall commands
-
-bla
-
-
-[role="mt-5"]
-== Update commands
-
-bla
-
-
-[role="mt-5"]
-== Search commands
-
-bla
-
-
-[role="mt-5"]
-== List commands
-
-bla
-
-
-[role="mt-5"]
-== Info commands
-
-bla
-
-
-[role="mt-5"]
-== Cleanup commands
-
-bla
-
-[role="mt-5"]
-=== Clean up old GEM versions
-
-To clean up old versions on your `GEM_PATH` of installed gems use
-below command:
-
-[source, sh]
-----
-gem cleanup <GEMNAME …>
-----
-
-The cleanup command removes old versions of gems from GEM_HOME that are not
-required to meet a dependency. If a gem is installed elsewhere in GEM_PATH
-the cleanup command won’t delete it.
-
-If no gems are named all gems in GEM_HOME are cleaned.
-
-
-[role="mt-5"]
-== Update Rubygems
-
-[source, sh]
-----
-gem install rubygems-update
-update_rubygems
-gem update --system
-----