j1-template 2023.5.2 → 2023.7.0

data/lib/starter_web/pages/public/legal/en/300_privacy.adoc

@@ -1,8 +1,10 @@
 ---
 title:                                  Privacy
 tagline:                                Your Personal Data
+
 date:                                   2023-01-01
 #last_modified:                         2023-01-01
+
 description: >
                                         J1 Template is a Bootstrap V5 website template for the static
                                         site generator Jekyll.
@@ -87,14 +89,17 @@ the General Data Protection Regulation (GDPR) of the European Union.
 // Include sub-documents (if any)
 // -----------------------------------------------------------------------------
 ifeval::[{cookies} == true]
+[role="mt-5"]
 == Cookies
 
 This website uses cookies and similar technologies for its operation
 this offer. You are free to give your consent, refuse, or revoke by clicking on
-the data protection dialog button. Subsequent changes are possible
-*at any time* by clicking on the icon mdi:cookie[18px, md-blue] placed in
-the *menu bar*.
+the data protection dialog button.
+
+Subsequent changes are possible *at any time* by clicking on the icon
+mdi:cookie[24px, md-blue] placed top right in the *menu bar*.
 
+[role="mb-4"]
 *Advanced* third-party cookies are only used with your consent. Additional
 cookies are used to analyze the website usage or to offer personalized content.
 The evaluation of this information gives you a better user experience of the
@@ -125,6 +130,7 @@ endif::[]
 
 
 ifeval::[{cookie-consent} == true]
+[role="mt-5"]
 == Privacy and your settings
 
 If you want to set which *cookies* (and similar technologies) are used by
@@ -153,6 +159,7 @@ endif::[]
 
 
 ifeval::[{themes} == true]
+[role="mt-5"]
 == Themes
 
 Themes for Bootstrap are used to customize the appearance of a website
@@ -174,6 +181,7 @@ endif::[]
 
 
 ifeval::[{logs-files} == true]
+[role="mt-5"]
 == Log files
 
 We collect certain information automatically from our web servers and save them
@@ -195,6 +203,7 @@ endif::[]
 
 
 ifeval::[{google-analytics} == true]
+[role="mt-5"]
 == Google Traffic analytics (GA)
 
 This website uses Google Analytics (GA), a data service for the analysis of
@@ -229,6 +238,7 @@ endif::[]
 
 
 ifeval::[{google-ads} == true]
+[role="mt-5"]
 == Google Advertising (GAA)
 
 This website uses Google Ads (GAD), a data service for personalized
@@ -263,6 +273,7 @@ endif::[]
 
 
 ifeval::[{google-translator} == true]
+[role="mt-5"]
 == Google Translation (GT)
 
 This website uses Google Google Translator (GT), a service to translate the
@@ -292,6 +303,7 @@ endif::[]
 
 
 ifeval::[{hyvor} == true]
+[role="mt-5"]
 == Use of Comments (HT)
 
 On our pages, functions of the service *Hyvor Talk* (HT) may be embedded.
@@ -329,6 +341,7 @@ endif::[]
 
 
 ifeval::[{facebook} == true]
+[role="mt-5"]
 == Use of the Facebook Integration
 
 On our pages, *functions* of the social network *Facebook* (HT) may be embedded.
@@ -365,6 +378,7 @@ endif::[]
 
 
 ifeval::[{twitter} == true]
+[role="mt-5"]
 == Use of the Twitter Integration
 
 On our pages, *functions* of the news network *Twitter* may be embedded.
@@ -401,6 +415,7 @@ endif::[]
 
 
 ifeval::[{instagram} == true]
+[role="mt-5"]
 == Use of the Instagram Integration
 
 On our pages, *functions* of the social network *Instagram* may be embedded.
@@ -437,6 +452,7 @@ endif::[]
 
 
 ifeval::[{youtube} == true]
+[role="mt-5"]
 == Use of YouTube Videos (YTV)
 
 On our pages, *functions* (player) of the video platform *YouTube* (YT) may be
@@ -472,6 +488,7 @@ endif::[]
 
 
 ifeval::[{vimeo} == true]
+[role="mt-5"]
 == Use of Vimeo Videos (VIV)
 
 On our pages, *functions* (player) of the video platform *Vimeo* (VI) may be
@@ -507,6 +524,7 @@ endif::[]
 
 
 ifeval::[{dailymotion} == true]
+[role="mt-5"]
 == Use of DailyMotion Videos (DMV)
 
 On our pages, *functions* (player) of the video platform *DailyMotion* (DMV)
@@ -542,6 +560,7 @@ endif::[]
 
 
 ifeval::[{vk} == true]
+[role="mt-5"]
 == Use of VK Videos (VKV)
 
 On our pages, *functions* (player) of the video platform *VK* (VKV) may be

data/lib/starter_web/pages/public/legal/en/400_comment_policy.adoc

@@ -1,8 +1,10 @@
 ---
 title:                                  Comment Policy
 tagline:                                Discuss With Respect
+
 date:                                   2021-03-30
 #last_modified:                         2023-01-01
+
 description: >
                                         J1 Template is a Bootstrap V5 website template for the static
                                         site generator Jekyll.
@@ -96,6 +98,8 @@ various features, such as social integration and social networking to support
 your personal networks.
 endif::[]
 
+
+[role="mt-5"]
 == Discuss with Respect
 
 One of the most important aspects of a helpful blog is the conversation
@@ -113,6 +117,7 @@ without notice.
 
 NOTE: This comment policy is subject to change at any time.
 
+[role="mt-5"]
 Promotional::
 Comments deemed to be spam or solely promotional in nature will be
 deleted. Links to relevant content are permitted, but comments should be

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

@@ -0,0 +1,412 @@
+---
+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/panels/intro_panel/panel.adoc

@@ -1,8 +1,10 @@
 ---
 title:                                  J1 Template
 tagline:                                Creating Responsive Websites
+
 date:                                   2020-11-03
 #last_modified:                         2023-01-01
+
 description: >
                                         J1 Template is a Bootstrap V5 website template for the static
                                         site generator Jekyll.
@@ -68,16 +70,18 @@ resource_options:
 // Include sub-documents (if any)
 // -----------------------------------------------------------------------------
 [[responsive-design]]
+[role="mt-5"]
 == Full Responsive
 
+A good user experience browsing a Web site is one of the most important
+features a website offers as a must, besides excellent content.
+
 [role="mb-3"]
 image::/assets/images/pages/panels/responsive-text-1920x800.jpg[{{page.title}}, width=1280]
 
-A good user experience browsing a Web site is one of the most important
-features a website offers as a must, besides excellent content. Presenting
-content at its best on all devices for all window sizes makes a great Web
-brilliant. J1 Template supports your Web for full responsiveness, for the
-best user experience on all modern devices.
+Presenting content at its best on all devices for all window sizes makes
+a great Web brilliant. J1 Template supports your Web for full responsiveness,
+for the best user experience on all modern devices.
 
 // [role="skiptranslate"]
 === Bootstrap Integration
@@ -122,15 +126,17 @@ modifications; your unique design.
 
 
 [[current-technology]]
+[role="mt-5"]
 == HTML5 · CSS3 · JS
+The Internet is a rapidly changing world. Like the fashion industries, new
+trends are set every year.
 
 [role="mb-3"]
 image::/assets/images/pages/panels/florian-olivo-1920x800.jpg[{{page.title}}, width=1280]
 
-The Internet is a rapidly changing world. Like the fashion industries, new
-trends are set every year. J1 Template combines modern technologies for the
-world of static Webs to make a site unique using current standards in terms
-of web development, languages, and tools.
+J1 Template combines modern technologies for the world of static Webs to
+make a site unique using current standards in terms of web development,
+languages, and tools.
 
 === Coding web pages
 
@@ -180,17 +186,16 @@ viewed on all current devices like Mobiles, Tablets, or the classic Desktop
 PC. The new HTML5 elements plus CSS3 modules can replace proprietary
 solutions like Adobe Flash to build modern web pages based on open standards.
 
-
 === Javascript
 
-[role="mb-3"]
-image::/assets/images/pages/panels/modules-apps-1920x800.jpg[{{page.title}}, width=1280]
-
 JavaScript is a text-based programming language used on the client-side and
 server-side to make web pages interactive. HTML and CSS are languages that
 give structure and style to web pages, and JavaScript provides web pages
 interactive elements that engage a user.
 
+[role="mb-3"]
+image::/assets/images/pages/panels/modules-apps-1920x800.jpg[{{page.title}}, width=1280]
+
 Content placement and basic methods for the dynamic of elements can be done
 using pure HTML5 and CSS3. For more complex solutions like *modules* (to
 provide dynamic, interactive features), the support of *Javascript* for a
@@ -212,18 +217,21 @@ website, e.g., by a powerful navigation system, for presenting image data
 in galleries, lightboxes, and so on. The good news is: no programming
 JavaScript is needed to use the build-in JS-based modules.
 
+
 [[launch-ready]]
+[role="mt-5"]
 == Start in No Time
 
+The base idea of the J1 Template is to give all people a toolset at their
+hands to create a website with no need to start by web development or
+web design from the beginning.
+
 [role="mb-3"]
 image::/assets/images/pages/panels/no-time-1920x800.jpg[{{page.title}}, width=1280]
 
-The base idea of the J1 Template is to give all people a toolset at their
-hands to create a website with no need to start by web development or
-web design from the beginning. A website based on J1 is using build-in
-templates and engines. As a result, the process to generate HTML code from
-your content is done automatically and allows you to concentrate on what
-truly matters: your content.
+A website based on J1 is using build-in templates and engines. As a result,
+the process to generate HTML code from your content is done automatically
+and allows you to concentrate on what truly matters: your content.
 
 Using J1, you can instantly start a web project by creating your content and
 not earning the deep of web development technologies.